ctdb/common/comm.h

   1 /*
   2    Communication endpoint API
   3
   4    Copyright (C) Amitay Isaacs 2015
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_COMM_H__
  21 #define __CTDB_COMM_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 /**
  27  * @file comm.h
  28  *
  29  * @brief Communication over a socket or file descriptor
  30  *
  31  * This abstraction is a wrapper around a socket or file descriptor to
  32  * send/receive complete packets.
  33  */
  34
  35 /**
  36  * @brief Packet handler function
  37  *
  38  * This function is registered while setting up communication endpoint.  Any
  39  * time packets are read, this function is called.
  40  */
  41 typedef void (*comm_read_handler_fn)(uint8_t *buf, size_t buflen,
  42                                      void *private_data);
  43
  44 /**
  45  * @brief Communication endpoint dead handler function
  46  *
  47  * This function is called when the communication endpoint is closed.
  48  */
  49 typedef void (*comm_dead_handler_fn)(void *private_data);
  50
  51 /**
  52  * @brief Abstract struct to store communication endpoint details
  53  */
  54 struct comm_context;
  55
  56 /**
  57  * @brief Initialize the communication endpoint
  58  *
  59  * This return a new communication context. Freeing this context will free all
  60  * memory assoicated with it.
  61  *
  62  * @param[in] mem_ctx Talloc memory context
  63  * @param[in] ev Tevent context
  64  * @param[in] fd The socket or file descriptor
  65  * @param[in] read_handler The packet handler function
  66  * @param[in] read_private_data Private data for read handler function
  67  * @param[in] dead_handler The communication dead handler function
  68  * @param[in] dead_private_data Private data for dead handler function
  69  * @param[out] result The new comm_context structure
  70  * @return 0 on success, errno on failure
  71  */
  72 int comm_setup(TALLOC_CTX *mem_ctx, struct tevent_context *ev, int fd,
  73                comm_read_handler_fn read_handler, void *read_private_data,
  74                comm_dead_handler_fn dead_handler, void *dead_private_data,
  75                struct comm_context **result);
  76
  77 /**
  78  * @brief Async computation start to send a packet
  79  *
  80  * @param[in] mem_ctx Talloc memory context
  81  * @param[in] ev Tevent context
  82  * @param[in] comm Communication context
  83  * @param[in] buf The packet data
  84  * @param[in] buflen The size of the packet
  85  * @return new tevent request, or NULL on failure
  86  */
  87 struct tevent_req *comm_write_send(TALLOC_CTX *mem_ctx,
  88                                    struct tevent_context *ev,
  89                                    struct comm_context *comm,
  90                                    uint8_t *buf, size_t buflen);
  91
  92 /**
  93  * @brief Async computation end to send a packet
  94  *
  95  * @param[in] req Tevent request
  96  * @param[out] perr errno in case of failure
  97  * @return true on success, false on failure
  98  */
  99 bool comm_write_recv(struct tevent_req *req, int *perr);
 100
 101 #endif /* __CTDB_COMM_H__ */