git.m6w6.name Git - m6w6/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 struct memcached_binary_protocol_callback_v0_st {
  91    memcached_binary_protocol_command_handler comcode[256];
  92 };
  93
  94 /**
  95  * The first version of the callback struct containing all of the
  96  * documented commands in the initial release of the binary protocol
  97  * (aka. memcached 1.4.0).
  98  *
  99  * You might miss the Q commands (addq etc) but the response function
 100  * knows how to deal with them so you don't need to worry about that :-)
 101  */
 102 struct memcached_binary_protocol_callback_v1_st {
 103    /**
 104     * Add an item to the cache
 105     * @param cookie id of the client receiving the command
 106     * @param key the key to add
 107     * @param len the length of the key
 108     * @param val the value to store for the key (may be NIL)
 109     * @param vallen the length of the data
 110     * @param flags the flags to store with the key
 111     * @param exptime the expiry time for the key-value pair
 112     * @param cas the resulting cas for the add operation (if success)
 113     */
 114    protocol_binary_response_status (*add)(const void *cookie,
 115                                           const void *key,
 116                                           uint16_t keylen,
 117                                           const void* val,
 118                                           uint32_t vallen,
 119                                           uint32_t flags,
 120                                           uint32_t exptime,
 121                                           uint64_t *cas);
 122
 123    /**
 124     * Append data to an <b>existing</b> key-value pair.
 125     *
 126     * @param cookie id of the client receiving the command
 127     * @param key the key to add data to
 128     * @param len the length of the key
 129     * @param val the value to append to the value
 130     * @param vallen the length of the data
 131     * @param cas the CAS in the request
 132     * @param result_cas the resulting cas for the append operation
 133     *
 134     */
 135    protocol_binary_response_status (*append)(const void *cookie,
 136                                              const void *key,
 137                                              uint16_t keylen,
 138                                              const void* val,
 139                                              uint32_t vallen,
 140                                              uint64_t cas,
 141                                              uint64_t *result_cas);
 142
 143    /**
 144     * Decrement the value for a key
 145     *
 146     * @param cookie id of the client receiving the command
 147     * @param key the key to decrement the value for
 148     * @param len the length of the key
 149     * @param delta the amount to decrement
 150     * @param initial initial value to store (if the key doesn't exist)
 151     * @param expiration expiration time for the object (if the key doesn't exist)
 152     * @param cas the CAS in the request
 153     * @param result the result from the decrement
 154     * @param result_cas the cas of the item
 155     *
 156     */
 157    protocol_binary_response_status (*decrement)(const void *cookie,
 158                                                 const void *key,
 159                                                 uint16_t keylen,
 160                                                 uint64_t delta,
 161                                                 uint64_t initial,
 162                                                 uint32_t expiration,
 163                                                 uint64_t *result,
 164                                                 uint64_t *result_cas);
 165
 166    /**
 167     * Delete an existing key
 168     *
 169     * @param cookie id of the client receiving the command
 170     * @param key the key to delete
 171     * @param len the length of the key
 172     * @param cas the CAS in the request
 173     */
 174    protocol_binary_response_status (*delete)(const void *cookie,
 175                                              const void *key,
 176                                              uint16_t keylen,
 177                                              uint64_t cas);
 178
 179
 180    /**
 181     * Flush the cache
 182     *
 183     * @param cookie id of the client receiving the command
 184     * @param when when the cache should be flushed (0 == immediately)
 185     */
 186    protocol_binary_response_status (*flush)(const void *cookie,
 187                                             uint32_t when);
 188
 189
 190
 191    /**
 192     * Get a key-value pair
 193     *
 194     * @param cookie id of the client receiving the command
 195     * @param key the key to get
 196     * @param len the length of the key
 197     * @param response_handler to send the result back to the client
 198     */
 199    protocol_binary_response_status (*get)(const void *cookie,
 200                                           const void *key,
 201                                           uint16_t keylen,
 202                                           memcached_binary_protocol_get_response_handler response_handler);
 203
 204    /**
 205     * Increment the value for a key
 206     *
 207     * @param cookie id of the client receiving the command
 208     * @param key the key to increment the value on
 209     * @param len the length of the key
 210     * @param delta the amount to increment
 211     * @param initial initial value to store (if the key doesn't exist)
 212     * @param expiration expiration time for the object (if the key doesn't exist)
 213     * @param cas the CAS in the request
 214     * @param result the result from the decrement
 215     * @param result_cas the cas of the item
 216     *
 217     */
 218    protocol_binary_response_status (*increment)(const void *cookie,
 219                                                 const void *key,
 220                                                 uint16_t keylen,
 221                                                 uint64_t delta,
 222                                                 uint64_t initial,
 223                                                 uint32_t expiration,
 224                                                 uint64_t *result,
 225                                                 uint64_t *result_cas);
 226
 227    /**
 228     * The noop command was received. This is just a notification callback (the
 229     * response is automatically created).
 230     *
 231     * @param cookie id of the client receiving the command
 232     */
 233    protocol_binary_response_status (*noop)(const void *cookie);
 234
 235    /**
 236     * Prepend data to an <b>existing</b> key-value pair.
 237     *
 238     * @param cookie id of the client receiving the command
 239     * @param key the key to prepend data to
 240     * @param len the length of the key
 241     * @param val the value to prepend to the value
 242     * @param vallen the length of the data
 243     * @param cas the CAS in the request
 244     * @param result-cas the cas id of the item
 245     *
 246     */
 247    protocol_binary_response_status (*prepend)(const void *cookie,
 248                                               const void *key,
 249                                               uint16_t keylen,
 250                                               const void* val,
 251                                               uint32_t vallen,
 252                                               uint64_t cas,
 253                                               uint64_t *result_cas);
 254
 255    /**
 256     * The quit command was received. This is just a notification callback (the
 257     * response is automatically created).
 258     *
 259     * @param cookie id of the client receiving the command
 260     */
 261    protocol_binary_response_status (*quit)(const void *cookie);
 262
 263
 264    /**
 265     * Replace an <b>existing</b> item to the cache
 266     *
 267     * @param cookie id of the client receiving the command
 268     * @param key the key to replace the content for
 269     * @param len the length of the key
 270     * @param val the value to store for the key (may be NIL)
 271     * @param vallen the length of the data
 272     * @param flags the flags to store with the key
 273     * @param exptime the expiry time for the key-value pair
 274     * @param cas the cas id in the request
 275     * @param result_cas the cas id of the item
 276     */
 277    protocol_binary_response_status (*replace)(const void *cookie,
 278                                               const void *key,
 279                                               uint16_t keylen,
 280                                               const void* val,
 281                                               uint32_t vallen,
 282                                               uint32_t flags,
 283                                               uint32_t exptime,
 284                                               uint64_t cas,
 285                                               uint64_t *result_cas);
 286
 287
 288    /**
 289     * Set a key-value pair in the cache
 290     *
 291     * @param cookie id of the client receiving the command
 292     * @param key the key to insert
 293     * @param len the length of the key
 294     * @param val the value to store for the key (may be NIL)
 295     * @param vallen the length of the data
 296     * @param flags the flags to store with the key
 297     * @param exptime the expiry time for the key-value pair
 298     * @param cas the cas id in the request
 299     * @param result_cas the cas id of the new item
 300     */
 301    protocol_binary_response_status (*set)(const void *cookie,
 302                                           const void *key,
 303                                           uint16_t keylen,
 304                                           const void* val,
 305                                           uint32_t vallen,
 306                                           uint32_t flags,
 307                                           uint32_t exptime,
 308                                           uint64_t cas,
 309                                           uint64_t *result_cas);
 310
 311    /**
 312     * Get status information
 313     *
 314     * @param cookie id of the client receiving the command
 315     * @param key the key to get status for (or NIL to request all status).
 316     *            Remember to insert the terminating packet if multiple
 317     *            packets should be returned.
 318     * @param keylen the length of the key
 319     * @param response_handler to send the result back to the client, but
 320     *                         don't send reply on success!
 321     *
 322     */
 323    protocol_binary_response_status (*stat)(const void *cookie,
 324                                            const void *key,
 325                                            uint16_t keylen,
 326                                            memcached_binary_protocol_stat_response_handler response_handler);
 327
 328    /**
 329     * Get the version information
 330     *
 331     * @param cookie id of the client receiving the command
 332     * @param response_handler to send the result back to the client, but
 333     *                         don't send reply on success!
 334     *
 335     */
 336    protocol_binary_response_status (*version)(const void *cookie,
 337                                               memcached_binary_protocol_version_response_handler response_handler);
 338 };
 339
 340 /**
 341  *
 342  */
 343 struct memcached_binary_protocol_callback_st {
 344    /**
 345     * The interface version used (set to 0 if you don't have any specialized
 346     * command handlers).
 347     */
 348    uint64_t interface_version;
 349
 350    /**
 351     * Callback fired just before the command will be executed.
 352     *
 353     * @param cookie id of the client receiving the command
 354     * @param header the command header as received on the wire. If you look
 355     *               at the content you <b>must</b> ensure that you don't
 356     *               try to access beyond the end of the message.
 357     */
 358    void (*pre_execute)(const void *cookie,
 359                        protocol_binary_request_header *header);
 360    /**
 361     * Callback fired just after the command was exected (please note
 362     * that the data transfer back to the client is not finished at this
 363     * time).
 364     *
 365     * @param cookie id of the client receiving the command
 366     * @param header the command header as received on the wire. If you look
 367     *               at the content you <b>must</b> ensure that you don't
 368     *               try to access beyond the end of the message.
 369     */
 370    void (*post_execute)(const void *cookie,
 371                         protocol_binary_request_header *header);
 372
 373    /**
 374     * Callback fired if no specialized callback is registered for this
 375     * specific command code.
 376     *
 377     * @param cookie id of the client receiving the command
 378     * @param header the command header as received on the wire. You <b>must</b>
 379     *               ensure that you don't try to access beyond the end of the
 380     *               message.
 381     * @param response_handler The response handler to send data back.
 382     */
 383    protocol_binary_response_status (*unknown)(const void *cookie,
 384                                               protocol_binary_request_header *header,
 385                                               memcached_binary_protocol_raw_response_handler response_handler);
 386
 387    /**
 388     * The different interface levels we support. A pointer is used so the
 389     * size of the structure is fixed. You must ensure that the memory area
 390     * passed as the pointer is valid as long as you use the protocol handler.
 391     */
 392    union {
 393       struct memcached_binary_protocol_callback_v0_st v0;
 394
 395       /**
 396        * The first version of the callback struct containing all of the
 397        * documented commands in the initial release of the binary protocol
 398        * (aka. memcached 1.4.0).
 399        */
 400       struct memcached_binary_protocol_callback_v1_st v1;
 401    } interface;
 402 };
 403
 404 #endif