git.m6w6.name Git - m6w6/libmemcached/blob - include/libmemcachedprotocol-0.0/handler.h

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