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

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