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

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