git.m6w6.name Git - m6w6/libmemcached/blob - include/libmemcachedprotocol-0.0/callback.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 /**
  19  * Callback to send data back from a successful GET/GETQ/GETK/GETKQ command
  20  *
  21  * @param cookie Just pass along the cookie supplied in the callback
  22  * @param key What to insert as key in the reply
  23  * @param keylen The length of the key
  24  * @param body What to store in the body of the package
  25  * @param bodylen The number of bytes of the body
  26  * @param flags The flags stored with the item
  27  * @param cas The CAS value to insert into the response (should be 0
  28  *            if you don't care)
  29  */
  30 typedef protocol_binary_response_status (*memcached_binary_protocol_get_response_handler)(
  31     const void *cookie, const void *key, uint16_t keylen, const void *body, uint32_t bodylen,
  32     uint32_t flags, uint64_t cas);
  33 /**
  34  * Callback to send data back from a STAT command
  35  *
  36  * @param cookie Just pass along the cookie supplied in the callback
  37  * @param key What to insert as key in the reply
  38  * @param keylen The length of the key
  39  * @param body What to store in the body of the package
  40  * @param bodylen The number of bytes of the body
  41  */
  42 typedef protocol_binary_response_status (*memcached_binary_protocol_stat_response_handler)(
  43     const void *cookie, const void *key, uint16_t keylen, const void *body, uint32_t bodylen);
  44 /**
  45  * Callback to send data back from a VERSION command
  46  *
  47  * @param cookie Just pass along the cookie supplied in the callback
  48  * @param text The version string
  49  * @param length The number of bytes in the version string
  50  */
  51 typedef protocol_binary_response_status (*memcached_binary_protocol_version_response_handler)(
  52     const void *cookie, const void *text, uint32_t length);
  53
  54 /**
  55  * In the low level interface you need to format the response
  56  * packet yourself (giving you complete freedom :-)
  57  *
  58  * @param cookie Just pass along the cookie supplied in the callback
  59  * @param request Pointer to the request packet you are sending a reply to
  60  * @param response Pointer to the response packet to send
  61  *
  62  */
  63 typedef protocol_binary_response_status (*memcached_binary_protocol_raw_response_handler)(
  64     const void *cookie, protocol_binary_request_header *request,
  65     protocol_binary_response_header *response);
  66
  67 /**
  68  * In the low lever interface you have to do most of the work by
  69  * yourself, but it also gives you a lot of freedom :-)
  70  * @param cookie identification for this connection, just pass it along to
  71  *               the response handler
  72  * @param header the command received over the wire. Never try to access
  73  *               <u>anything</u> outside the command.
  74  * @param resonse_handler call this function to send data back to the client
  75  */
  76 typedef protocol_binary_response_status (*memcached_binary_protocol_command_handler)(
  77     const void *cookie, protocol_binary_request_header *header,
  78     memcached_binary_protocol_raw_response_handler response_handler);
  79
  80 /**
  81  * The raw interface to the packets is implemented in version 0. It contains
  82  * just an array with command handlers. The inxed in the array is the
  83  * com code.
  84  */
  85 typedef struct {
  86   memcached_binary_protocol_command_handler comcode[256];
  87 } memcached_binary_protocol_callback_v0_st;
  88
  89 /**
  90  * The first version of the callback struct containing all of the
  91  * documented commands in the initial release of the binary protocol
  92  * (aka. memcached 1.4.0).
  93  *
  94  * You might miss the Q commands (addq etc) but the response function
  95  * knows how to deal with them so you don't need to worry about that :-)
  96  */
  97 typedef struct {
  98   /**
  99    * Add an item to the cache
 100    * @param cookie id of the client receiving the command
 101    * @param key the key to add
 102    * @param len the length of the key
 103    * @param val the value to store for the key (may be NIL)
 104    * @param vallen the length of the data
 105    * @param flags the flags to store with the key
 106    * @param exptime the expiry time for the key-value pair
 107    * @param cas the resulting cas for the add operation (if success)
 108    */
 109   protocol_binary_response_status (*add)(const void *cookie, const void *key, uint16_t keylen,
 110                                          const void *val, uint32_t vallen, uint32_t flags,
 111                                          uint32_t exptime, uint64_t *cas);
 112
 113   /**
 114    * Append data to an <b>existing</b> key-value pair.
 115    *
 116    * @param cookie id of the client receiving the command
 117    * @param key the key to add data to
 118    * @param len the length of the key
 119    * @param val the value to append to the value
 120    * @param vallen the length of the data
 121    * @param cas the CAS in the request
 122    * @param result_cas the resulting cas for the append operation
 123    *
 124    */
 125   protocol_binary_response_status (*append)(const void *cookie, const void *key, uint16_t keylen,
 126                                             const void *val, uint32_t vallen, uint64_t cas,
 127                                             uint64_t *result_cas);
 128
 129   /**
 130    * Decrement the value for a key
 131    *
 132    * @param cookie id of the client receiving the command
 133    * @param key the key to decrement the value for
 134    * @param len the length of the key
 135    * @param delta the amount to decrement
 136    * @param initial initial value to store (if the key doesn't exist)
 137    * @param expiration expiration time for the object (if the key doesn't exist)
 138    * @param cas the CAS in the request
 139    * @param result the result from the decrement
 140    * @param result_cas the cas of the item
 141    *
 142    */
 143   protocol_binary_response_status (*decrement)(const void *cookie, const void *key, uint16_t keylen,
 144                                                uint64_t delta, uint64_t initial,
 145                                                uint32_t expiration, uint64_t *result,
 146                                                uint64_t *result_cas);
 147
 148   /**
 149    * Delete an existing key
 150    *
 151    * @param cookie id of the client receiving the command
 152    * @param key the key to delete_object
 153    * @param len the length of the key
 154    * @param cas the CAS in the request
 155    */
 156   protocol_binary_response_status (*delete_object)(const void *cookie, const void *key,
 157                                                    uint16_t keylen, uint64_t cas);
 158
 159   /**
 160    * Flush the cache
 161    *
 162    * @param cookie id of the client receiving the command
 163    * @param when when the cache should be flushed (0 == immediately)
 164    */
 165   protocol_binary_response_status (*flush_object)(const void *cookie, uint32_t when);
 166
 167   /**
 168    * Get a key-value pair
 169    *
 170    * @param cookie id of the client receiving the command
 171    * @param key the key to get
 172    * @param len the length of the key
 173    * @param response_handler to send the result back to the client
 174    */
 175   protocol_binary_response_status (*get)(
 176       const void *cookie, const void *key, uint16_t keylen,
 177       memcached_binary_protocol_get_response_handler response_handler);
 178
 179   /**
 180    * Increment the value for a key
 181    *
 182    * @param cookie id of the client receiving the command
 183    * @param key the key to increment the value on
 184    * @param len the length of the key
 185    * @param delta the amount to increment
 186    * @param initial initial value to store (if the key doesn't exist)
 187    * @param expiration expiration time for the object (if the key doesn't exist)
 188    * @param cas the CAS in the request
 189    * @param result the result from the decrement
 190    * @param result_cas the cas of the item
 191    *
 192    */
 193   protocol_binary_response_status (*increment)(const void *cookie, const void *key, uint16_t keylen,
 194                                                uint64_t delta, uint64_t initial,
 195                                                uint32_t expiration, uint64_t *result,
 196                                                uint64_t *result_cas);
 197
 198   /**
 199    * The noop command was received. This is just a notification callback (the
 200    * response is automatically created).
 201    *
 202    * @param cookie id of the client receiving the command
 203    */
 204   protocol_binary_response_status (*noop)(const void *cookie);
 205
 206   /**
 207    * Prepend data to an <b>existing</b> key-value pair.
 208    *
 209    * @param cookie id of the client receiving the command
 210    * @param key the key to prepend data to
 211    * @param len the length of the key
 212    * @param val the value to prepend to the value
 213    * @param vallen the length of the data
 214    * @param cas the CAS in the request
 215    * @param result-cas the cas id of the item
 216    *
 217    */
 218   protocol_binary_response_status (*prepend)(const void *cookie, const void *key, uint16_t keylen,
 219                                              const void *val, uint32_t vallen, uint64_t cas,
 220                                              uint64_t *result_cas);
 221
 222   /**
 223    * The quit command was received. This is just a notification callback (the
 224    * response is automatically created).
 225    *
 226    * @param cookie id of the client receiving the command
 227    */
 228   protocol_binary_response_status (*quit)(const void *cookie);
 229
 230   /**
 231    * Replace an <b>existing</b> item to the cache
 232    *
 233    * @param cookie id of the client receiving the command
 234    * @param key the key to replace the content for
 235    * @param len the length of the key
 236    * @param val the value to store for the key (may be NIL)
 237    * @param vallen the length of the data
 238    * @param flags the flags to store with the key
 239    * @param exptime the expiry time for the key-value pair
 240    * @param cas the cas id in the request
 241    * @param result_cas the cas id of the item
 242    */
 243   protocol_binary_response_status (*replace)(const void *cookie, const void *key, uint16_t keylen,
 244                                              const void *val, uint32_t vallen, uint32_t flags,
 245                                              uint32_t exptime, uint64_t cas, uint64_t *result_cas);
 246
 247   /**
 248    * Set a key-value pair in the cache
 249    *
 250    * @param cookie id of the client receiving the command
 251    * @param key the key to insert
 252    * @param len the length of the key
 253    * @param val the value to store for the key (may be NIL)
 254    * @param vallen the length of the data
 255    * @param flags the flags to store with the key
 256    * @param exptime the expiry time for the key-value pair
 257    * @param cas the cas id in the request
 258    * @param result_cas the cas id of the new item
 259    */
 260   protocol_binary_response_status (*set)(const void *cookie, const void *key, uint16_t keylen,
 261                                          const void *val, uint32_t vallen, uint32_t flags,
 262                                          uint32_t exptime, uint64_t cas, uint64_t *result_cas);
 263
 264   /**
 265    * Get status information
 266    *
 267    * @param cookie id of the client receiving the command
 268    * @param key the key to get status for (or NIL to request all status).
 269    *            Remember to insert the terminating packet if multiple
 270    *            packets should be returned.
 271    * @param keylen the length of the key
 272    * @param response_handler to send the result back to the client, but
 273    *                         don't send reply on success!
 274    *
 275    */
 276   protocol_binary_response_status (*stat)(
 277       const void *cookie, const void *key, uint16_t keylen,
 278       memcached_binary_protocol_stat_response_handler response_handler);
 279
 280   /**
 281    * Get the version information
 282    *
 283    * @param cookie id of the client receiving the command
 284    * @param response_handler to send the result back to the client, but
 285    *                         don't send reply on success!
 286    *
 287    */
 288   protocol_binary_response_status (*version)(
 289       const void *cookie, memcached_binary_protocol_version_response_handler response_handler);
 290 } memcached_binary_protocol_callback_v1_st;
 291
 292 /**
 293  * The version numbers for the different callback structures.
 294  */
 295 typedef enum {
 296   /** Version 0 is a lowlevel interface that tries to maximize your freedom */
 297   MEMCACHED_PROTOCOL_HANDLER_V0 = 0,
 298   /**
 299    * Version 1 abstracts more of the protocol details, and let you work at
 300    * a logical level
 301    */
 302   MEMCACHED_PROTOCOL_HANDLER_V1 = 1
 303 } memcached_protocol_interface_version_t;
 304
 305 /**
 306  * Definition of the protocol callback structure.
 307  */
 308 typedef struct {
 309   /**
 310    * The interface version you provide callbacks for.
 311    */
 312   memcached_protocol_interface_version_t interface_version;
 313
 314   /**
 315    * Callback fired just before the command will be executed.
 316    *
 317    * @param cookie id of the client receiving the command
 318    * @param header the command header as received on the wire. If you look
 319    *               at the content you <b>must</b> ensure that you don't
 320    *               try to access beyond the end of the message.
 321    */
 322   void (*pre_execute)(const void *cookie, protocol_binary_request_header *header);
 323   /**
 324    * Callback fired just after the command was exected (please note
 325    * that the data transfer back to the client is not finished at this
 326    * time).
 327    *
 328    * @param cookie id of the client receiving the command
 329    * @param header the command header as received on the wire. If you look
 330    *               at the content you <b>must</b> ensure that you don't
 331    *               try to access beyond the end of the message.
 332    */
 333   void (*post_execute)(const void *cookie, protocol_binary_request_header *header);
 334
 335   /**
 336    * Callback fired if no specialized callback is registered for this
 337    * specific command code.
 338    *
 339    * @param cookie id of the client receiving the command
 340    * @param header the command header as received on the wire. You <b>must</b>
 341    *               ensure that you don't try to access beyond the end of the
 342    *               message.
 343    * @param response_handler The response handler to send data back.
 344    */
 345   protocol_binary_response_status (*unknown)(
 346       const void *cookie, protocol_binary_request_header *header,
 347       memcached_binary_protocol_raw_response_handler response_handler);
 348
 349   /**
 350    * The different interface levels we support. A pointer is used so the
 351    * size of the structure is fixed. You must ensure that the memory area
 352    * passed as the pointer is valid as long as you use the protocol handler.
 353    */
 354   union {
 355     memcached_binary_protocol_callback_v0_st v0;
 356
 357     /**
 358      * The first version of the callback struct containing all of the
 359      * documented commands in the initial release of the binary protocol
 360      * (aka. memcached 1.4.0).
 361      */
 362     memcached_binary_protocol_callback_v1_st v1;
 363   } interface;
 364 } memcached_binary_protocol_callback_st;