git.m6w6.name Git - m6w6/libmemcached/blob - libmemcached/memcached/protocol_binary.h

   1 /*
   2  * Copyright (c) <2008>, Sun Microsystems, Inc.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of the  nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY SUN MICROSYSTEMS, INC. ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27 /*
  28  * Summary: Constants used by to implement the binary protocol.
  29  *
  30  * Copy: See Copyright for the status of this software.
  31  *
  32  * Author: Trond Norbye <trond.norbye@sun.com>
  33  */
  34
  35 #ifndef PROTOCOL_BINARY_H
  36 #define PROTOCOL_BINARY_H
  37
  38 /**
  39  * \addtogroup Protocol
  40  * @{
  41  */
  42
  43 /**
  44  * This file contains definitions of the constants and packet formats
  45  * defined in the binary specification. Please note that you _MUST_ remember
  46  * to convert each multibyte field to / from network byte order to / from
  47  * host order.
  48  */
  49 #ifdef __cplusplus
  50 extern "C"
  51 {
  52 #endif
  53
  54     /**
  55      * Definition of the legal "magic" values used in a packet.
  56      * See section 3.1 Magic byte
  57      */
  58     typedef enum {
  59         PROTOCOL_BINARY_REQ = 0x80,
  60         PROTOCOL_BINARY_RES = 0x81
  61     } protocol_binary_magic;
  62
  63     /**
  64      * Definition of the valid response status numbers.
  65      * See section 3.2 Response Status
  66      */
  67     typedef enum {
  68         PROTOCOL_BINARY_RESPONSE_SUCCESS = 0x00,
  69         PROTOCOL_BINARY_RESPONSE_KEY_ENOENT = 0x01,
  70         PROTOCOL_BINARY_RESPONSE_KEY_EEXISTS = 0x02,
  71         PROTOCOL_BINARY_RESPONSE_E2BIG = 0x03,
  72         PROTOCOL_BINARY_RESPONSE_EINVAL = 0x04,
  73         PROTOCOL_BINARY_RESPONSE_NOT_STORED = 0x05,
  74         PROTOCOL_BINARY_RESPONSE_DELTA_BADVAL = 0x06,
  75         PROTOCOL_BINARY_RESPONSE_AUTH_ERROR = 0x20,
  76         PROTOCOL_BINARY_RESPONSE_AUTH_CONTINUE = 0x21,
  77         PROTOCOL_BINARY_RESPONSE_UNKNOWN_COMMAND = 0x81,
  78         PROTOCOL_BINARY_RESPONSE_ENOMEM = 0x82,
  79
  80         PROTOCOL_BINARY_RESPONSE_PAUSE = 0xfe00,
  81         PROTOCOL_BINARY_RESPONSE_EIO = 0xff00
  82
  83     } protocol_binary_response_status;
  84
  85     /**
  86      * Defintion of the different command opcodes.
  87      * See section 3.3 Command Opcodes
  88      */
  89     typedef enum {
  90         PROTOCOL_BINARY_CMD_GET = 0x00,
  91         PROTOCOL_BINARY_CMD_SET = 0x01,
  92         PROTOCOL_BINARY_CMD_ADD = 0x02,
  93         PROTOCOL_BINARY_CMD_REPLACE = 0x03,
  94         PROTOCOL_BINARY_CMD_DELETE = 0x04,
  95         PROTOCOL_BINARY_CMD_INCREMENT = 0x05,
  96         PROTOCOL_BINARY_CMD_DECREMENT = 0x06,
  97         PROTOCOL_BINARY_CMD_QUIT = 0x07,
  98         PROTOCOL_BINARY_CMD_FLUSH = 0x08,
  99         PROTOCOL_BINARY_CMD_GETQ = 0x09,
 100         PROTOCOL_BINARY_CMD_NOOP = 0x0a,
 101         PROTOCOL_BINARY_CMD_VERSION = 0x0b,
 102         PROTOCOL_BINARY_CMD_GETK = 0x0c,
 103         PROTOCOL_BINARY_CMD_GETKQ = 0x0d,
 104         PROTOCOL_BINARY_CMD_APPEND = 0x0e,
 105         PROTOCOL_BINARY_CMD_PREPEND = 0x0f,
 106         PROTOCOL_BINARY_CMD_STAT = 0x10,
 107         PROTOCOL_BINARY_CMD_SETQ = 0x11,
 108         PROTOCOL_BINARY_CMD_ADDQ = 0x12,
 109         PROTOCOL_BINARY_CMD_REPLACEQ = 0x13,
 110         PROTOCOL_BINARY_CMD_DELETEQ = 0x14,
 111         PROTOCOL_BINARY_CMD_INCREMENTQ = 0x15,
 112         PROTOCOL_BINARY_CMD_DECREMENTQ = 0x16,
 113         PROTOCOL_BINARY_CMD_QUITQ = 0x17,
 114         PROTOCOL_BINARY_CMD_FLUSHQ = 0x18,
 115         PROTOCOL_BINARY_CMD_APPENDQ = 0x19,
 116         PROTOCOL_BINARY_CMD_PREPENDQ = 0x1a,
 117
 118         PROTOCOL_BINARY_CMD_SASL_LIST_MECHS = 0x20,
 119         PROTOCOL_BINARY_CMD_SASL_AUTH = 0x21,
 120         PROTOCOL_BINARY_CMD_SASL_STEP = 0x22,
 121
 122         /* These commands are used for range operations and exist within
 123          * this header for use in other projects.  Range operations are
 124          * not expected to be implemented in the memcached server itself.
 125          */
 126         PROTOCOL_BINARY_CMD_RGET      = 0x30,
 127         PROTOCOL_BINARY_CMD_RSET      = 0x31,
 128         PROTOCOL_BINARY_CMD_RSETQ     = 0x32,
 129         PROTOCOL_BINARY_CMD_RAPPEND   = 0x33,
 130         PROTOCOL_BINARY_CMD_RAPPENDQ  = 0x34,
 131         PROTOCOL_BINARY_CMD_RPREPEND  = 0x35,
 132         PROTOCOL_BINARY_CMD_RPREPENDQ = 0x36,
 133         PROTOCOL_BINARY_CMD_RDELETE   = 0x37,
 134         PROTOCOL_BINARY_CMD_RDELETEQ  = 0x38,
 135         PROTOCOL_BINARY_CMD_RINCR     = 0x39,
 136         PROTOCOL_BINARY_CMD_RINCRQ    = 0x3a,
 137         PROTOCOL_BINARY_CMD_RDECR     = 0x3b,
 138         PROTOCOL_BINARY_CMD_RDECRQ    = 0x3c
 139         /* End Range operations */
 140
 141     } protocol_binary_command;
 142
 143     /**
 144      * Definition of the data types in the packet
 145      * See section 3.4 Data Types
 146      */
 147     typedef enum {
 148         PROTOCOL_BINARY_RAW_BYTES = 0x00
 149     } protocol_binary_datatypes;
 150
 151     /**
 152      * Definition of the header structure for a request packet.
 153      * See section 2
 154      */
 155     typedef union {
 156         struct {
 157             uint8_t magic;
 158             uint8_t opcode;
 159             uint16_t keylen;
 160             uint8_t extlen;
 161             uint8_t datatype;
 162             uint16_t reserved;
 163             uint32_t bodylen;
 164             uint32_t opaque;
 165             uint64_t cas;
 166         } request;
 167         uint8_t bytes[24];
 168     } protocol_binary_request_header;
 169
 170     /**
 171      * Definition of the header structure for a response packet.
 172      * See section 2
 173      */
 174     typedef union {
 175         struct {
 176             uint8_t magic;
 177             uint8_t opcode;
 178             uint16_t keylen;
 179             uint8_t extlen;
 180             uint8_t datatype;
 181             uint16_t status;
 182             uint32_t bodylen;
 183             uint32_t opaque;
 184             uint64_t cas;
 185         } response;
 186         uint8_t bytes[24];
 187     } protocol_binary_response_header;
 188
 189     /**
 190      * Definition of a request-packet containing no extras
 191      */
 192     typedef union {
 193         struct {
 194             protocol_binary_request_header header;
 195         } message;
 196         uint8_t bytes[sizeof(protocol_binary_request_header)];
 197     } protocol_binary_request_no_extras;
 198
 199     /**
 200      * Definition of a response-packet containing no extras
 201      */
 202     typedef union {
 203         struct {
 204             protocol_binary_response_header header;
 205         } message;
 206         uint8_t bytes[sizeof(protocol_binary_response_header)];
 207     } protocol_binary_response_no_extras;
 208
 209     /**
 210      * Definition of the packet used by the get, getq, getk and getkq command.
 211      * See section 4
 212      */
 213     typedef protocol_binary_request_no_extras protocol_binary_request_get;
 214     typedef protocol_binary_request_no_extras protocol_binary_request_getq;
 215     typedef protocol_binary_request_no_extras protocol_binary_request_getk;
 216     typedef protocol_binary_request_no_extras protocol_binary_request_getkq;
 217
 218     /**
 219      * Definition of the packet returned from a successful get, getq, getk and
 220      * getkq.
 221      * See section 4
 222      */
 223     typedef union {
 224         struct {
 225             protocol_binary_response_header header;
 226             struct {
 227                 uint32_t flags;
 228             } body;
 229         } message;
 230         uint8_t bytes[sizeof(protocol_binary_response_header) + 4];
 231     } protocol_binary_response_get;
 232
 233     typedef protocol_binary_response_get protocol_binary_response_getq;
 234     typedef protocol_binary_response_get protocol_binary_response_getk;
 235     typedef protocol_binary_response_get protocol_binary_response_getkq;
 236
 237     /**
 238      * Definition of the packet used by the delete command
 239      * See section 4
 240      */
 241     typedef protocol_binary_request_no_extras protocol_binary_request_delete;
 242
 243     /**
 244      * Definition of the packet returned by the delete command
 245      * See section 4
 246      */
 247     typedef protocol_binary_response_no_extras protocol_binary_response_delete;
 248
 249     /**
 250      * Definition of the packet used by the flush command
 251      * See section 4
 252      * Please note that the expiration field is optional, so remember to see
 253      * check the header.bodysize to see if it is present.
 254      */
 255     typedef union {
 256         struct {
 257             protocol_binary_request_header header;
 258             struct {
 259                 uint32_t expiration;
 260             } body;
 261         } message;
 262         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 263     } protocol_binary_request_flush;
 264
 265     /**
 266      * Definition of the packet returned by the flush command
 267      * See section 4
 268      */
 269     typedef protocol_binary_response_no_extras protocol_binary_response_flush;
 270
 271     /**
 272      * Definition of the packet used by set, add and replace
 273      * See section 4
 274      */
 275     typedef union {
 276         struct {
 277             protocol_binary_request_header header;
 278             struct {
 279                 uint32_t flags;
 280                 uint32_t expiration;
 281             } body;
 282         } message;
 283         uint8_t bytes[sizeof(protocol_binary_request_header) + 8];
 284     } protocol_binary_request_set;
 285     typedef protocol_binary_request_set protocol_binary_request_add;
 286     typedef protocol_binary_request_set protocol_binary_request_replace;
 287
 288     /**
 289      * Definition of the packet returned by set, add and replace
 290      * See section 4
 291      */
 292     typedef protocol_binary_response_no_extras protocol_binary_response_set;
 293     typedef protocol_binary_response_no_extras protocol_binary_response_add;
 294     typedef protocol_binary_response_no_extras protocol_binary_response_replace;
 295
 296     /**
 297      * Definition of the noop packet
 298      * See section 4
 299      */
 300     typedef protocol_binary_request_no_extras protocol_binary_request_noop;
 301
 302     /**
 303      * Definition of the packet returned by the noop command
 304      * See section 4
 305      */
 306     typedef protocol_binary_response_no_extras protocol_binary_response_noop;
 307
 308     /**
 309      * Definition of the structure used by the increment and decrement
 310      * command.
 311      * See section 4
 312      */
 313     typedef union {
 314         struct {
 315             protocol_binary_request_header header;
 316             struct {
 317                 uint64_t delta;
 318                 uint64_t initial;
 319                 uint32_t expiration;
 320             } body;
 321         } message;
 322         uint8_t bytes[sizeof(protocol_binary_request_header) + 20];
 323     } protocol_binary_request_incr;
 324     typedef protocol_binary_request_incr protocol_binary_request_decr;
 325
 326     /**
 327      * Definition of the response from an incr or decr command
 328      * command.
 329      * See section 4
 330      */
 331     typedef union {
 332         struct {
 333             protocol_binary_response_header header;
 334             struct {
 335                 uint64_t value;
 336             } body;
 337         } message;
 338         uint8_t bytes[sizeof(protocol_binary_response_header) + 8];
 339     } protocol_binary_response_incr;
 340     typedef protocol_binary_response_incr protocol_binary_response_decr;
 341
 342     /**
 343      * Definition of the quit
 344      * See section 4
 345      */
 346     typedef protocol_binary_request_no_extras protocol_binary_request_quit;
 347
 348     /**
 349      * Definition of the packet returned by the quit command
 350      * See section 4
 351      */
 352     typedef protocol_binary_response_no_extras protocol_binary_response_quit;
 353
 354     /**
 355      * Definition of the packet used by append and prepend command
 356      * See section 4
 357      */
 358     typedef protocol_binary_request_no_extras protocol_binary_request_append;
 359     typedef protocol_binary_request_no_extras protocol_binary_request_prepend;
 360
 361     /**
 362      * Definition of the packet returned from a successful append or prepend
 363      * See section 4
 364      */
 365     typedef protocol_binary_response_no_extras protocol_binary_response_append;
 366     typedef protocol_binary_response_no_extras protocol_binary_response_prepend;
 367
 368     /**
 369      * Definition of the packet used by the version command
 370      * See section 4
 371      */
 372     typedef protocol_binary_request_no_extras protocol_binary_request_version;
 373
 374     /**
 375      * Definition of the packet returned from a successful version command
 376      * See section 4
 377      */
 378     typedef protocol_binary_response_no_extras protocol_binary_response_version;
 379
 380
 381     /**
 382      * Definition of the packet used by the stats command.
 383      * See section 4
 384      */
 385     typedef protocol_binary_request_no_extras protocol_binary_request_stats;
 386
 387     /**
 388      * Definition of the packet returned from a successful stats command
 389      * See section 4
 390      */
 391     typedef protocol_binary_response_no_extras protocol_binary_response_stats;
 392
 393     /**
 394      * Definition of a request for a range operation.
 395      * See http://code.google.com/p/memcached/wiki/RangeOps
 396      *
 397      * These types are used for range operations and exist within
 398      * this header for use in other projects.  Range operations are
 399      * not expected to be implemented in the memcached server itself.
 400      */
 401     typedef union {
 402         struct {
 403             protocol_binary_response_header header;
 404             struct {
 405                 uint16_t size;
 406                 uint8_t  reserved;
 407                 uint8_t  flags;
 408                 uint32_t max_results;
 409             } body;
 410         } message;
 411         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 412     } protocol_binary_request_rangeop;
 413
 414     typedef protocol_binary_request_rangeop protocol_binary_request_rget;
 415     typedef protocol_binary_request_rangeop protocol_binary_request_rset;
 416     typedef protocol_binary_request_rangeop protocol_binary_request_rsetq;
 417     typedef protocol_binary_request_rangeop protocol_binary_request_rappend;
 418     typedef protocol_binary_request_rangeop protocol_binary_request_rappendq;
 419     typedef protocol_binary_request_rangeop protocol_binary_request_rprepend;
 420     typedef protocol_binary_request_rangeop protocol_binary_request_rprependq;
 421     typedef protocol_binary_request_rangeop protocol_binary_request_rdelete;
 422     typedef protocol_binary_request_rangeop protocol_binary_request_rdeleteq;
 423     typedef protocol_binary_request_rangeop protocol_binary_request_rincr;
 424     typedef protocol_binary_request_rangeop protocol_binary_request_rincrq;
 425     typedef protocol_binary_request_rangeop protocol_binary_request_rdecr;
 426     typedef protocol_binary_request_rangeop protocol_binary_request_rdecrq;
 427
 428     /**
 429      * @}
 430      */
 431
 432 #ifdef __cplusplus
 433 }
 434 #endif
 435 #endif /* PROTOCOL_BINARY_H */