git.m6w6.name Git - awesomized/libmemcached/blob - libmemcached/protocol_handler.h

   1 /*
   2  * Summary: Definition of the callback interface to the protocol handler
   3  *
   4  * Copy: See Copyright for the status of this software.
   5  *
   6  * Author: Trond Norbye
   7  */
   8 #ifndef MEMCACHED_PROTOCOL_H
   9 #define MEMCACHED_PROTOCOL_H
  10
  11 #include <sys/types.h>
  12 #include <stdbool.h>
  13
  14 #include <libmemcached/memcached/protocol_binary.h>
  15 #include <libmemcached/visibility.h>
  16 #include <libmemcached/protocol/callback.h>
  17
  18 /* Forward declarations */
  19 /*
  20  * You should only access memcached_binary_protocol_st from one thread!,
  21  * and never assume anything about the internal layout / sizes of the
  22  * structures.
  23  */
  24 struct memcached_binary_protocol_st;
  25 struct memcached_binary_protocol_client_st;
  26
  27 /**
  28  * Function the protocol handler should call to receive data.
  29  * This function should behave exactly like read(2)
  30  *
  31  * @param cookie a cookie used to represent a given client
  32  * @param fd the filedescriptor associated with the client
  33  * @param buf destination buffer
  34  * @param nbuf number of bytes to receive
  35  * @return the number of bytes copied into buf
  36  *         or -1 upon error (errno should contain more information)
  37  */
  38 typedef ssize_t (*memcached_binary_protocol_recv_func)(const void *cookie,
  39                                                        int fd,
  40                                                        void *buf,
  41                                                        size_t nbuf);
  42
  43 /**
  44  * Function the protocol handler should call to send data.
  45  * This function should behave exactly like write(2)
  46  *
  47  * @param cookie a cookie used to represent a given client
  48  * @param fd the filedescriptor associated with the client
  49  * @param buf the source buffer
  50  * @param nbuf number of bytes to send
  51  * @return the number of bytes sent
  52  *         or -1 upon error (errno should contain more information)
  53  */
  54 typedef ssize_t (*memcached_binary_protocol_send_func)(const void *cookie,
  55                                                        int fd,
  56                                                        const void *buf,
  57                                                        size_t nbuf);
  58
  59 /**
  60  * Create an instance of the protocol handler
  61  *
  62  * @return NULL if allocation of an instance fails
  63  */
  64 LIBMEMCACHED_API
  65 struct memcached_binary_protocol_st *memcached_binary_protocol_create_instance(void);
  66
  67 /**
  68  * Get the callbacks associated with a protocol handler instance
  69  * @return the callbacks currently used
  70  */
  71 LIBMEMCACHED_API
  72 struct memcached_binary_protocol_callback_st *memcached_binary_protocol_get_callbacks(struct memcached_binary_protocol_st *instance);
  73
  74 /**
  75  * Set the callbacks to be used by the given protocol handler instance
  76  * @param instance the instance to update
  77  * @param callback the callbacks to use
  78  */
  79 LIBMEMCACHED_API
  80 void memcached_binary_protocol_set_callbacks(struct memcached_binary_protocol_st *instance, struct memcached_binary_protocol_callback_st *callback);
  81
  82 /**
  83  * Should the library inspect the packages being sent and received and verify
  84  * that they are according to the specification? If it encounters an invalid
  85  * packet, it will return an EINVAL packet.
  86  *
  87  * @param instance the instance to update
  88  * @param enable true if you want the library to check packages, false otherwise
  89  */
  90 LIBMEMCACHED_API
  91 void memcached_binary_protocol_set_pedantic(struct memcached_binary_protocol_st *instance, bool enable);
  92
  93 /**
  94  * Is the library inpecting each package?
  95  * @param instance the instance to check
  96  * @return true it the library is inspecting each package, false otherwise
  97  */
  98 LIBMEMCACHED_API
  99 bool memcached_binary_protocol_get_pedantic(struct memcached_binary_protocol_st *instance);
 100
 101 /**
 102  * Destroy an instance of the protocol handler
 103  *
 104  * @param instance The instance to destroy
 105  */
 106 LIBMEMCACHED_API
 107 void memcached_binary_protocol_destroy_instance(struct memcached_binary_protocol_st *instance);
 108
 109 /**
 110  * Set the IO functions used by the instance to send and receive data. The
 111  * functions should behave like recv(3socket) and send(3socket).
 112  *
 113  * @param instance the instance to specify the IO functions for
 114  * @param recv the function to call for reciving data
 115  * @param send the function to call for sending data
 116  */
 117 LIBMEMCACHED_API
 118 void memached_binary_protocol_set_io_functions(struct memcached_binary_protocol_st *instance,
 119                                                memcached_binary_protocol_recv_func recv,
 120                                                memcached_binary_protocol_send_func send);
 121
 122
 123 /**
 124  * Create a new client instance and associate it with a socket
 125  * @param instance the protocol instance to bind the client to
 126  * @param sock the client socket
 127  * @return NULL if allocation fails, otherwise an instance
 128  */
 129 LIBMEMCACHED_API
 130 struct memcached_binary_protocol_client_st *memcached_binary_protocol_create_client(struct memcached_binary_protocol_st *instance, int sock);
 131
 132 /**
 133  * Destroy a client handle.
 134  * The caller needs to close the socket accociated with the client
 135  * <b>before</b> calling this function. This function invalidates the
 136  * client memory area.
 137  *
 138  * @param client the client to destroy
 139  */
 140 LIBMEMCACHED_API
 141 void memcached_binary_protocol_client_destroy(struct memcached_binary_protocol_client_st *client);
 142
 143 /**
 144  * The different events the client is interested in
 145  */
 146 enum MEMCACHED_BINARY_PROTOCOL_EVENT {
 147    /* Error event means that the client encountered an error with the
 148     * connection so you should shut it down */
 149    ERROR_EVENT,
 150    /* Please notify when there is more data available to read */
 151    READ_EVENT,
 152    /* Please notify when it is possible to send more data */
 153    WRITE_EVENT,
 154    /* Please notify when it is possible to send or receive data */
 155    READ_WRITE_EVENT
 156 };
 157
 158 /**
 159  * Let the client do some work. This might involve reading / sending data
 160  * to/from the client, or perform callbacks to execute a command.
 161  * @param client the client structure to work on
 162  * @return The next event the protocol handler will be notified for
 163  */
 164 LIBMEMCACHED_API
 165 enum MEMCACHED_BINARY_PROTOCOL_EVENT memcached_binary_protocol_client_work(struct memcached_binary_protocol_client_st *client);
 166
 167 /**
 168  * Get the socket attached to a client handle
 169  * @param client the client to query
 170  * @return the socket handle
 171  */
 172 LIBMEMCACHED_API
 173 int memcached_binary_protocol_client_get_socket(struct memcached_binary_protocol_client_st *client);
 174
 175 /**
 176  * Get the error id socket attached to a client handle
 177  * @param client the client to query for an error code
 178  * @return the OS error code from the client
 179  */
 180 LIBMEMCACHED_API
 181 int memcached_binary_protocol_client_get_errno(struct memcached_binary_protocol_client_st *client);
 182
 183 /**
 184  * Get a raw response handler for the given cookie
 185  * @param cookie the cookie passed along into the callback
 186  * @return the raw reponse handler you may use if you find
 187  *         the generic callback too limiting
 188  */
 189 LIBMEMCACHED_API
 190 memcached_binary_protocol_raw_response_handler memcached_binary_protocol_get_raw_response_handler(const void *cookie);
 191 #endif