git.m6w6.name Git - m6w6/libmemcached/blob - 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  * This file contains definitions of the constants and packet formats
  40  * defined in the binary specification. Please note that you _MUST_ remember
  41  * to convert each multibyte field to / from network byte order to / from
  42  * host order.
  43  */
  44 #ifdef __cplusplus
  45 extern "C"
  46 {
  47 #endif
  48
  49     /**
  50      * Definition of the legal "magic" values used in a packet.
  51      * See section 3.1 Magic byte
  52      */
  53     typedef enum {
  54         PROTOCOL_BINARY_REQ = 0x80,
  55         PROTOCOL_BINARY_RES = 0x81
  56     } protocol_binary_magic;
  57
  58     /**
  59      * Definition of the valid response status numbers.
  60      * See section 3.2 Response Status
  61      */
  62     typedef enum {
  63         PROTOCOL_BINARY_RESPONSE_SUCCESS = 0x00,
  64         PROTOCOL_BINARY_RESPONSE_KEY_ENOENT = 0x01,
  65         PROTOCOL_BINARY_RESPONSE_KEY_EEXISTS = 0x02,
  66         PROTOCOL_BINARY_RESPONSE_E2BIG = 0x03,
  67         PROTOCOL_BINARY_RESPONSE_EINVAL = 0x04,
  68         PROTOCOL_BINARY_RESPONSE_NOT_STORED = 0x05,
  69         PROTOCOL_BINARY_RESPONSE_DELTA_BADVAL = 0x06,
  70         PROTOCOL_BINARY_RESPONSE_AUTH_ERROR = 0x20,
  71         PROTOCOL_BINARY_RESPONSE_AUTH_CONTINUE = 0x21,
  72         PROTOCOL_BINARY_RESPONSE_UNKNOWN_COMMAND = 0x81,
  73         PROTOCOL_BINARY_RESPONSE_ENOMEM = 0x82
  74     } protocol_binary_response_status;
  75
  76     /**
  77      * Defintion of the different command opcodes.
  78      * See section 3.3 Command Opcodes
  79      */
  80     typedef enum {
  81         PROTOCOL_BINARY_CMD_GET = 0x00,
  82         PROTOCOL_BINARY_CMD_SET = 0x01,
  83         PROTOCOL_BINARY_CMD_ADD = 0x02,
  84         PROTOCOL_BINARY_CMD_REPLACE = 0x03,
  85         PROTOCOL_BINARY_CMD_DELETE = 0x04,
  86         PROTOCOL_BINARY_CMD_INCREMENT = 0x05,
  87         PROTOCOL_BINARY_CMD_DECREMENT = 0x06,
  88         PROTOCOL_BINARY_CMD_QUIT = 0x07,
  89         PROTOCOL_BINARY_CMD_FLUSH = 0x08,
  90         PROTOCOL_BINARY_CMD_GETQ = 0x09,
  91         PROTOCOL_BINARY_CMD_NOOP = 0x0a,
  92         PROTOCOL_BINARY_CMD_VERSION = 0x0b,
  93         PROTOCOL_BINARY_CMD_GETK = 0x0c,
  94         PROTOCOL_BINARY_CMD_GETKQ = 0x0d,
  95         PROTOCOL_BINARY_CMD_APPEND = 0x0e,
  96         PROTOCOL_BINARY_CMD_PREPEND = 0x0f,
  97         PROTOCOL_BINARY_CMD_STAT = 0x10,
  98         PROTOCOL_BINARY_CMD_SETQ = 0x11,
  99         PROTOCOL_BINARY_CMD_ADDQ = 0x12,
 100         PROTOCOL_BINARY_CMD_REPLACEQ = 0x13,
 101         PROTOCOL_BINARY_CMD_DELETEQ = 0x14,
 102         PROTOCOL_BINARY_CMD_INCREMENTQ = 0x15,
 103         PROTOCOL_BINARY_CMD_DECREMENTQ = 0x16,
 104         PROTOCOL_BINARY_CMD_QUITQ = 0x17,
 105         PROTOCOL_BINARY_CMD_FLUSHQ = 0x18,
 106         PROTOCOL_BINARY_CMD_APPENDQ = 0x19,
 107         PROTOCOL_BINARY_CMD_PREPENDQ = 0x1a,
 108         PROTOCOL_BINARY_CMD_TOUCH = 0x1c,
 109         PROTOCOL_BINARY_CMD_GAT = 0x1d,
 110         PROTOCOL_BINARY_CMD_GATQ = 0x1e,
 111         PROTOCOL_BINARY_CMD_GATK = 0x23,
 112         PROTOCOL_BINARY_CMD_GATKQ = 0x24,
 113
 114         PROTOCOL_BINARY_CMD_SASL_LIST_MECHS = 0x20,
 115         PROTOCOL_BINARY_CMD_SASL_AUTH = 0x21,
 116         PROTOCOL_BINARY_CMD_SASL_STEP = 0x22,
 117
 118         /* These commands are used for range operations and exist within
 119          * this header for use in other projects.  Range operations are
 120          * not expected to be implemented in the memcached server itself.
 121          */
 122         PROTOCOL_BINARY_CMD_RGET      = 0x30,
 123         PROTOCOL_BINARY_CMD_RSET      = 0x31,
 124         PROTOCOL_BINARY_CMD_RSETQ     = 0x32,
 125         PROTOCOL_BINARY_CMD_RAPPEND   = 0x33,
 126         PROTOCOL_BINARY_CMD_RAPPENDQ  = 0x34,
 127         PROTOCOL_BINARY_CMD_RPREPEND  = 0x35,
 128         PROTOCOL_BINARY_CMD_RPREPENDQ = 0x36,
 129         PROTOCOL_BINARY_CMD_RDELETE   = 0x37,
 130         PROTOCOL_BINARY_CMD_RDELETEQ  = 0x38,
 131         PROTOCOL_BINARY_CMD_RINCR     = 0x39,
 132         PROTOCOL_BINARY_CMD_RINCRQ    = 0x3a,
 133         PROTOCOL_BINARY_CMD_RDECR     = 0x3b,
 134         PROTOCOL_BINARY_CMD_RDECRQ    = 0x3c
 135         /* End Range operations */
 136
 137     } protocol_binary_command;
 138
 139     /**
 140      * Definition of the data types in the packet
 141      * See section 3.4 Data Types
 142      */
 143     typedef enum {
 144         PROTOCOL_BINARY_RAW_BYTES = 0x00
 145     } protocol_binary_datatypes;
 146
 147     /**
 148      * Definition of the header structure for a request packet.
 149      * See section 2
 150      */
 151     typedef union {
 152         struct {
 153             uint8_t magic;
 154             uint8_t opcode;
 155             uint16_t keylen;
 156             uint8_t extlen;
 157             uint8_t datatype;
 158             uint16_t reserved;
 159             uint32_t bodylen;
 160             uint32_t opaque;
 161             uint64_t cas;
 162         } request;
 163         uint8_t bytes[24];
 164     } protocol_binary_request_header;
 165
 166     /**
 167      * Definition of the header structure for a response packet.
 168      * See section 2
 169      */
 170     typedef union {
 171         struct {
 172             uint8_t magic;
 173             uint8_t opcode;
 174             uint16_t keylen;
 175             uint8_t extlen;
 176             uint8_t datatype;
 177             uint16_t status;
 178             uint32_t bodylen;
 179             uint32_t opaque;
 180             uint64_t cas;
 181         } response;
 182         uint8_t bytes[24];
 183     } protocol_binary_response_header;
 184
 185     /**
 186      * Definition of a request-packet containing no extras
 187      */
 188     typedef union {
 189         struct {
 190             protocol_binary_request_header header;
 191         } message;
 192         uint8_t bytes[sizeof(protocol_binary_request_header)];
 193     } protocol_binary_request_no_extras;
 194
 195     /**
 196      * Definition of a response-packet containing no extras
 197      */
 198     typedef union {
 199         struct {
 200             protocol_binary_response_header header;
 201         } message;
 202         uint8_t bytes[sizeof(protocol_binary_response_header)];
 203     } protocol_binary_response_no_extras;
 204
 205     /**
 206      * Definition of the packet used by the get, getq, getk and getkq command.
 207      * See section 4
 208      */
 209     typedef protocol_binary_request_no_extras protocol_binary_request_get;
 210     typedef protocol_binary_request_no_extras protocol_binary_request_getq;
 211     typedef protocol_binary_request_no_extras protocol_binary_request_getk;
 212     typedef protocol_binary_request_no_extras protocol_binary_request_getkq;
 213
 214     /**
 215      * Definition of the packet returned from a successful get, getq, getk and
 216      * getkq.
 217      * See section 4
 218      */
 219     typedef union {
 220         struct {
 221             protocol_binary_response_header header;
 222             struct {
 223                 uint32_t flags;
 224             } body;
 225         } message;
 226         uint8_t bytes[sizeof(protocol_binary_response_header) + 4];
 227     } protocol_binary_response_get;
 228
 229     typedef protocol_binary_response_get protocol_binary_response_getq;
 230     typedef protocol_binary_response_get protocol_binary_response_getk;
 231     typedef protocol_binary_response_get protocol_binary_response_getkq;
 232
 233     /**
 234      * Definition of the packet used by the delete command
 235      * See section 4
 236      */
 237     typedef protocol_binary_request_no_extras protocol_binary_request_delete;
 238
 239     /**
 240      * Definition of the packet returned by the delete command
 241      * See section 4
 242      */
 243     typedef protocol_binary_response_no_extras protocol_binary_response_delete;
 244
 245     /**
 246      * Definition of the packet used by the flush command
 247      * See section 4
 248      * Please note that the expiration field is optional, so remember to see
 249      * check the header.bodysize to see if it is present.
 250      */
 251     typedef union {
 252         struct {
 253             protocol_binary_request_header header;
 254             struct {
 255                 uint32_t expiration;
 256             } body;
 257         } message;
 258         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 259     } protocol_binary_request_flush;
 260
 261     /**
 262      * Definition of the packet returned by the flush command
 263      * See section 4
 264      */
 265     typedef protocol_binary_response_no_extras protocol_binary_response_flush;
 266
 267     /**
 268      * Definition of the packet used by set, add and replace
 269      * See section 4
 270      */
 271     typedef union {
 272         struct {
 273             protocol_binary_request_header header;
 274             struct {
 275                 uint32_t flags;
 276                 uint32_t expiration;
 277             } body;
 278         } message;
 279         uint8_t bytes[sizeof(protocol_binary_request_header) + 8];
 280     } protocol_binary_request_set;
 281     typedef protocol_binary_request_set protocol_binary_request_add;
 282     typedef protocol_binary_request_set protocol_binary_request_replace;
 283
 284     /**
 285      * Definition of the packet returned by set, add and replace
 286      * See section 4
 287      */
 288     typedef protocol_binary_response_no_extras protocol_binary_response_set;
 289     typedef protocol_binary_response_no_extras protocol_binary_response_add;
 290     typedef protocol_binary_response_no_extras protocol_binary_response_replace;
 291
 292     /**
 293      * Definition of the noop packet
 294      * See section 4
 295      */
 296     typedef protocol_binary_request_no_extras protocol_binary_request_noop;
 297
 298     /**
 299      * Definition of the packet returned by the noop command
 300      * See section 4
 301      */
 302     typedef protocol_binary_response_no_extras protocol_binary_response_noop;
 303
 304     /**
 305      * Definition of the structure used by the increment and decrement
 306      * command.
 307      * See section 4
 308      */
 309     typedef union {
 310         struct {
 311             protocol_binary_request_header header;
 312             struct {
 313                 uint64_t delta;
 314                 uint64_t initial;
 315                 uint32_t expiration;
 316             } body;
 317         } message;
 318         uint8_t bytes[sizeof(protocol_binary_request_header) + 20];
 319     } protocol_binary_request_incr;
 320     typedef protocol_binary_request_incr protocol_binary_request_decr;
 321
 322     /**
 323      * Definition of the response from an incr or decr command
 324      * command.
 325      * See section 4
 326      */
 327     typedef union {
 328         struct {
 329             protocol_binary_response_header header;
 330             struct {
 331                 uint64_t value;
 332             } body;
 333         } message;
 334         uint8_t bytes[sizeof(protocol_binary_response_header) + 8];
 335     } protocol_binary_response_incr;
 336     typedef protocol_binary_response_incr protocol_binary_response_decr;
 337
 338     /**
 339      * Definition of the quit
 340      * See section 4
 341      */
 342     typedef protocol_binary_request_no_extras protocol_binary_request_quit;
 343
 344     /**
 345      * Definition of the packet returned by the quit command
 346      * See section 4
 347      */
 348     typedef protocol_binary_response_no_extras protocol_binary_response_quit;
 349
 350     /**
 351      * Definition of the packet used by append and prepend command
 352      * See section 4
 353      */
 354     typedef protocol_binary_request_no_extras protocol_binary_request_append;
 355     typedef protocol_binary_request_no_extras protocol_binary_request_prepend;
 356
 357     /**
 358      * Definition of the packet returned from a successful append or prepend
 359      * See section 4
 360      */
 361     typedef protocol_binary_response_no_extras protocol_binary_response_append;
 362     typedef protocol_binary_response_no_extras protocol_binary_response_prepend;
 363
 364     /**
 365      * Definition of the packet used by the version command
 366      * See section 4
 367      */
 368     typedef protocol_binary_request_no_extras protocol_binary_request_version;
 369
 370     /**
 371      * Definition of the packet returned from a successful version command
 372      * See section 4
 373      */
 374     typedef protocol_binary_response_no_extras protocol_binary_response_version;
 375
 376
 377     /**
 378      * Definition of the packet used by the stats command.
 379      * See section 4
 380      */
 381     typedef protocol_binary_request_no_extras protocol_binary_request_stats;
 382
 383     /**
 384      * Definition of the packet returned from a successful stats command
 385      * See section 4
 386      */
 387     typedef protocol_binary_response_no_extras protocol_binary_response_stats;
 388
 389     /**
 390      * Definition of the packet used by the touch command.
 391      */
 392     typedef union {
 393         struct {
 394             protocol_binary_request_header header;
 395             struct {
 396                 uint32_t expiration;
 397             } body;
 398         } message;
 399         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 400     } protocol_binary_request_touch;
 401
 402     /**
 403      * Definition of the packet returned from the touch command
 404      */
 405     typedef protocol_binary_response_no_extras protocol_binary_response_touch;
 406
 407     /**
 408      * Definition of the packet used by the GAT(Q) command.
 409      */
 410     typedef union {
 411         struct {
 412             protocol_binary_request_header header;
 413             struct {
 414                 uint32_t expiration;
 415             } body;
 416         } message;
 417         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 418     } protocol_binary_request_gat;
 419
 420     typedef protocol_binary_request_gat protocol_binary_request_gatq;
 421     typedef protocol_binary_request_gat protocol_binary_request_gatk;
 422     typedef protocol_binary_request_gat protocol_binary_request_gatkq;
 423
 424     /**
 425      * Definition of the packet returned from the GAT(Q)
 426      */
 427     typedef protocol_binary_response_get protocol_binary_response_gat;
 428     typedef protocol_binary_response_get protocol_binary_response_gatq;
 429     typedef protocol_binary_response_get protocol_binary_response_gatk;
 430     typedef protocol_binary_response_get protocol_binary_response_gatkq;
 431
 432     /**
 433      * Definition of a request for a range operation.
 434      * See http://code.google.com/p/memcached/wiki/RangeOps
 435      *
 436      * These types are used for range operations and exist within
 437      * this header for use in other projects.  Range operations are
 438      * not expected to be implemented in the memcached server itself.
 439      */
 440     typedef union {
 441         struct {
 442             protocol_binary_response_header header;
 443             struct {
 444                 uint16_t size;
 445                 uint8_t  reserved;
 446                 uint8_t  flags;
 447                 uint32_t max_results;
 448             } body;
 449         } message;
 450         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 451     } protocol_binary_request_rangeop;
 452
 453     typedef protocol_binary_request_rangeop protocol_binary_request_rget;
 454     typedef protocol_binary_request_rangeop protocol_binary_request_rset;
 455     typedef protocol_binary_request_rangeop protocol_binary_request_rsetq;
 456     typedef protocol_binary_request_rangeop protocol_binary_request_rappend;
 457     typedef protocol_binary_request_rangeop protocol_binary_request_rappendq;
 458     typedef protocol_binary_request_rangeop protocol_binary_request_rprepend;
 459     typedef protocol_binary_request_rangeop protocol_binary_request_rprependq;
 460     typedef protocol_binary_request_rangeop protocol_binary_request_rdelete;
 461     typedef protocol_binary_request_rangeop protocol_binary_request_rdeleteq;
 462     typedef protocol_binary_request_rangeop protocol_binary_request_rincr;
 463     typedef protocol_binary_request_rangeop protocol_binary_request_rincrq;
 464     typedef protocol_binary_request_rangeop protocol_binary_request_rdecr;
 465     typedef protocol_binary_request_rangeop protocol_binary_request_rdecrq;
 466
 467 #ifdef __cplusplus
 468 }
 469 #endif
 470 #endif /* PROTOCOL_BINARY_H */