ctdb/common/sock_client.h

   1 /*
   2    A client based on unix domain socket
   3
   4    Copyright (C) Amitay Isaacs  2017
   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_SOCK_CLIENT_H__
  21 #define __CTDB_SOCK_CLIENT_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 /**
  27  * @file sock_client.h
  28  *
  29  * @brief A framework for a client based on unix-domain sockets.
  30  *
  31  * This abstraction allows one to build clients that communicate using
  32  * unix-domain sockets.  It takes care of the common boilerplate.
  33  */
  34
  35 /**
  36  * @brief The abstract socket daemon context
  37  */
  38 struct sock_client_context;
  39
  40 /**
  41  * @brief callback function
  42  *
  43  * This function can be registered to be called in case daemon goes away.
  44  */
  45 typedef void (*sock_client_callback_func_t)(void *private_data);
  46
  47 /**
  48  * @brief Protocol marshalling functions
  49  *
  50  * The typical protocol packet will have a header and a payload.
  51  * Header will contain at least 2 fields: length and reqid
  52  *
  53  * request_push() is called when the request packet needs to be marshalled
  54  *
  55  * reply_pull() is called to unmarshall data into a reply packet
  56  *
  57  * reply_reqid() is called to extract request id from a reply packet
  58  */
  59 struct sock_client_proto_funcs {
  60         int (*request_push)(void *request, uint32_t reqid,
  61                             TALLOC_CTX *mem_ctx,
  62                             uint8_t **buf, size_t *buflen,
  63                             void *private_data);
  64
  65         int (*reply_pull)(uint8_t *buf, size_t buflen,
  66                           TALLOC_CTX *mem_ctx, void **reply,
  67                           void *private_data);
  68
  69         int (*reply_reqid)(uint8_t *buf, size_t buflen,
  70                            uint32_t *reqid, void *private_data);
  71 };
  72
  73 /**
  74  * @brief Create a new socket client
  75  *
  76  * @param[in] mem_ctx Talloc memory context
  77  * @param[in] ev Tevent context
  78  * @param[in] sockpath Unix domain socket path
  79  * @param[in] funcs Protocol marshalling functions
  80  * @param[in] private_data Private data for protocol functions
  81  * @param[out] result New socket client context
  82  * @return 0 on success, errno on failure
  83  */
  84 int sock_client_setup(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
  85                       const char *sockpath,
  86                       struct sock_client_proto_funcs *funcs,
  87                       void *private_data,
  88                       struct sock_client_context **result);
  89
  90 /**
  91  * @brief Register a callback in case of client disconnection
  92  *
  93  * @param[in] sockc Socket client context
  94  * @param[in] callback Callback function
  95  * @param[in] private_data Private data for callback function
  96  */
  97 void sock_client_set_disconnect_callback(struct sock_client_context *sockc,
  98                                          sock_client_callback_func_t callback,
  99                                          void *private_data);
 100
 101 /**
 102  * @brief Async computation to send data to the daemon
 103  *
 104  * @param[in] mem_ctx Talloc memory context
 105  * @param[in] ev Tevent context
 106  * @param[in] sockc The socket client context
 107  * @param[in] timeout How long to wait for
 108  * @param[in] request Request packet to be sent
 109  * @return new tevent request, or NULL on failure
 110  */
 111 struct tevent_req *sock_client_msg_send(TALLOC_CTX *mem_ctx,
 112                                         struct tevent_context *ev,
 113                                         struct sock_client_context *sockc,
 114                                         struct timeval timeout,
 115                                         void *request);
 116
 117 /**
 118  * @brief Async computation end to send data to the daemon
 119  *
 120  * @param[in] req Tevent request
 121  * @param[out] perr errno in case of failure
 122  * @param[in] mem_ctx Talloc memory context
 123  * @param[out] reply Reply received from server
 124  * @return true on success, false on failure
 125  */
 126 bool sock_client_msg_recv(struct tevent_req *req, int *perr,
 127                           TALLOC_CTX *mem_ctx, void *reply);
 128
 129 #endif /* __CTDB_SOCK_CLIENT_H__ */