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