git.m6w6.name Git - awesomized/libmemcached/blob - libmemcached/protocol/callback.h

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