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