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