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