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     } 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
 109         /* These commands are used for range operations and exist within
 110          * this header for use in other projects.  Range operations are
 111          * not expected to be implemented in the memcached server itself.
 112          */
 113         PROTOCOL_BINARY_CMD_RGET      = 0x30,
 114         PROTOCOL_BINARY_CMD_RSET      = 0x31,
 115         PROTOCOL_BINARY_CMD_RSETQ     = 0x32,
 116         PROTOCOL_BINARY_CMD_RAPPEND   = 0x33,
 117         PROTOCOL_BINARY_CMD_RAPPENDQ  = 0x34,
 118         PROTOCOL_BINARY_CMD_RPREPEND  = 0x35,
 119         PROTOCOL_BINARY_CMD_RPREPENDQ = 0x36,
 120         PROTOCOL_BINARY_CMD_RDELETE   = 0x37,
 121         PROTOCOL_BINARY_CMD_RDELETEQ  = 0x38,
 122         PROTOCOL_BINARY_CMD_RINCR     = 0x39,
 123         PROTOCOL_BINARY_CMD_RINCRQ    = 0x3a,
 124         PROTOCOL_BINARY_CMD_RDECR     = 0x3b,
 125         PROTOCOL_BINARY_CMD_RDECRQ    = 0x3c
 126         /* End Range operations */
 127
 128     } protocol_binary_command;
 129
 130     /**
 131      * Definition of the data types in the packet
 132      * See section 3.4 Data Types
 133      */
 134     typedef enum {
 135         PROTOCOL_BINARY_RAW_BYTES = 0x00
 136     } protocol_binary_datatypes;
 137
 138     /**
 139      * Definition of the header structure for a request packet.
 140      * See section 2
 141      */
 142     typedef union {
 143         struct {
 144             uint8_t magic;
 145             uint8_t opcode;
 146             uint16_t keylen;
 147             uint8_t extlen;
 148             uint8_t datatype;
 149             uint16_t reserved;
 150             uint32_t bodylen;
 151             uint32_t opaque;
 152             uint64_t cas;
 153         } request;
 154         uint8_t bytes[24];
 155     } protocol_binary_request_header;
 156
 157     /**
 158      * Definition of the header structure for a response packet.
 159      * See section 2
 160      */
 161     typedef union {
 162         struct {
 163             uint8_t magic;
 164             uint8_t opcode;
 165             uint16_t keylen;
 166             uint8_t extlen;
 167             uint8_t datatype;
 168             uint16_t status;
 169             uint32_t bodylen;
 170             uint32_t opaque;
 171             uint64_t cas;
 172         } response;
 173         uint8_t bytes[24];
 174     } protocol_binary_response_header;
 175
 176     /**
 177      * Definition of a request-packet containing no extras
 178      */
 179     typedef union {
 180         struct {
 181             protocol_binary_request_header header;
 182         } message;
 183         uint8_t bytes[sizeof(protocol_binary_request_header)];
 184     } protocol_binary_request_no_extras;
 185
 186     /**
 187      * Definition of a response-packet containing no extras
 188      */
 189     typedef union {
 190         struct {
 191             protocol_binary_response_header header;
 192         } message;
 193         uint8_t bytes[sizeof(protocol_binary_response_header)];
 194     } protocol_binary_response_no_extras;
 195
 196     /**
 197      * Definition of the packet used by the get, getq, getk and getkq command.
 198      * See section 4
 199      */
 200     typedef protocol_binary_request_no_extras protocol_binary_request_get;
 201     typedef protocol_binary_request_no_extras protocol_binary_request_getq;
 202     typedef protocol_binary_request_no_extras protocol_binary_request_getk;
 203     typedef protocol_binary_request_no_extras protocol_binary_request_getkq;
 204
 205     /**
 206      * Definition of the packet returned from a successful get, getq, getk and
 207      * getkq.
 208      * See section 4
 209      */
 210     typedef union {
 211         struct {
 212             protocol_binary_response_header header;
 213             struct {
 214                 uint32_t flags;
 215             } body;
 216         } message;
 217         uint8_t bytes[sizeof(protocol_binary_response_header) + 4];
 218     } protocol_binary_response_get;
 219
 220     typedef protocol_binary_response_get protocol_binary_response_getq;
 221     typedef protocol_binary_response_get protocol_binary_response_getk;
 222     typedef protocol_binary_response_get protocol_binary_response_getkq;
 223
 224     /**
 225      * Definition of the packet used by the delete command
 226      * See section 4
 227      */
 228     typedef protocol_binary_request_no_extras protocol_binary_request_delete;
 229
 230     /**
 231      * Definition of the packet returned by the delete command
 232      * See section 4
 233      */
 234     typedef protocol_binary_response_no_extras protocol_binary_response_delete;
 235
 236     /**
 237      * Definition of the packet used by the flush command
 238      * See section 4
 239      * Please note that the expiration field is optional, so remember to see
 240      * check the header.bodysize to see if it is present.
 241      */
 242     typedef union {
 243         struct {
 244             protocol_binary_request_header header;
 245             struct {
 246                 uint32_t expiration;
 247             } body;
 248         } message;
 249         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 250     } protocol_binary_request_flush;
 251
 252     /**
 253      * Definition of the packet returned by the flush command
 254      * See section 4
 255      */
 256     typedef protocol_binary_response_no_extras protocol_binary_response_flush;
 257
 258     /**
 259      * Definition of the packet used by set, add and replace
 260      * See section 4
 261      */
 262     typedef union {
 263         struct {
 264             protocol_binary_request_header header;
 265             struct {
 266                 uint32_t flags;
 267                 uint32_t expiration;
 268             } body;
 269         } message;
 270         uint8_t bytes[sizeof(protocol_binary_request_header) + 8];
 271     } protocol_binary_request_set;
 272     typedef protocol_binary_request_set protocol_binary_request_add;
 273     typedef protocol_binary_request_set protocol_binary_request_replace;
 274
 275     /**
 276      * Definition of the packet returned by set, add and replace
 277      * See section 4
 278      */
 279     typedef protocol_binary_response_no_extras protocol_binary_response_set;
 280     typedef protocol_binary_response_no_extras protocol_binary_response_add;
 281     typedef protocol_binary_response_no_extras protocol_binary_response_replace;
 282
 283     /**
 284      * Definition of the noop packet
 285      * See section 4
 286      */
 287     typedef protocol_binary_request_no_extras protocol_binary_request_noop;
 288
 289     /**
 290      * Definition of the packet returned by the noop command
 291      * See section 4
 292      */
 293     typedef protocol_binary_response_no_extras protocol_binary_response_noop;
 294
 295     /**
 296      * Definition of the structure used by the increment and decrement
 297      * command.
 298      * See section 4
 299      */
 300     typedef union {
 301         struct {
 302             protocol_binary_request_header header;
 303             struct {
 304                 uint64_t delta;
 305                 uint64_t initial;
 306                 uint32_t expiration;
 307             } body;
 308         } message;
 309         uint8_t bytes[sizeof(protocol_binary_request_header) + 20];
 310     } protocol_binary_request_incr;
 311     typedef protocol_binary_request_incr protocol_binary_request_decr;
 312
 313     /**
 314      * Definition of the response from an incr or decr command
 315      * command.
 316      * See section 4
 317      */
 318     typedef union {
 319         struct {
 320             protocol_binary_response_header header;
 321             struct {
 322                 uint64_t value;
 323             } body;
 324         } message;
 325         uint8_t bytes[sizeof(protocol_binary_response_header) + 8];
 326     } protocol_binary_response_incr;
 327     typedef protocol_binary_response_incr protocol_binary_response_decr;
 328
 329     /**
 330      * Definition of the quit
 331      * See section 4
 332      */
 333     typedef protocol_binary_request_no_extras protocol_binary_request_quit;
 334
 335     /**
 336      * Definition of the packet returned by the quit command
 337      * See section 4
 338      */
 339     typedef protocol_binary_response_no_extras protocol_binary_response_quit;
 340
 341     /**
 342      * Definition of the packet used by append and prepend command
 343      * See section 4
 344      */
 345     typedef protocol_binary_request_no_extras protocol_binary_request_append;
 346     typedef protocol_binary_request_no_extras protocol_binary_request_prepend;
 347
 348     /**
 349      * Definition of the packet returned from a successful append or prepend
 350      * See section 4
 351      */
 352     typedef protocol_binary_response_no_extras protocol_binary_response_append;
 353     typedef protocol_binary_response_no_extras protocol_binary_response_prepend;
 354
 355     /**
 356      * Definition of the packet used by the version command
 357      * See section 4
 358      */
 359     typedef protocol_binary_request_no_extras protocol_binary_request_version;
 360
 361     /**
 362      * Definition of the packet returned from a successful version command
 363      * See section 4
 364      */
 365     typedef protocol_binary_response_no_extras protocol_binary_response_version;
 366
 367
 368     /**
 369      * Definition of the packet used by the stats command.
 370      * See section 4
 371      */
 372     typedef protocol_binary_request_no_extras protocol_binary_request_stats;
 373
 374     /**
 375      * Definition of the packet returned from a successful stats command
 376      * See section 4
 377      */
 378     typedef protocol_binary_response_no_extras protocol_binary_response_stats;
 379
 380     /**
 381      * Definition of a request for a range operation.
 382      * See http://code.google.com/p/memcached/wiki/RangeOps
 383      *
 384      * These types are used for range operations and exist within
 385      * this header for use in other projects.  Range operations are
 386      * not expected to be implemented in the memcached server itself.
 387      */
 388     typedef union {
 389         struct {
 390             protocol_binary_response_header header;
 391             struct {
 392                 uint16_t size;
 393                 uint8_t  reserved;
 394                 uint8_t  flags;
 395                 uint32_t max_results;
 396             } body;
 397         } message;
 398         uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 399     } protocol_binary_request_rangeop;
 400
 401     typedef protocol_binary_request_rangeop protocol_binary_request_rget;
 402     typedef protocol_binary_request_rangeop protocol_binary_request_rset;
 403     typedef protocol_binary_request_rangeop protocol_binary_request_rsetq;
 404     typedef protocol_binary_request_rangeop protocol_binary_request_rappend;
 405     typedef protocol_binary_request_rangeop protocol_binary_request_rappendq;
 406     typedef protocol_binary_request_rangeop protocol_binary_request_rprepend;
 407     typedef protocol_binary_request_rangeop protocol_binary_request_rprependq;
 408     typedef protocol_binary_request_rangeop protocol_binary_request_rdelete;
 409     typedef protocol_binary_request_rangeop protocol_binary_request_rdeleteq;
 410     typedef protocol_binary_request_rangeop protocol_binary_request_rincr;
 411     typedef protocol_binary_request_rangeop protocol_binary_request_rincrq;
 412     typedef protocol_binary_request_rangeop protocol_binary_request_rdecr;
 413     typedef protocol_binary_request_rangeop protocol_binary_request_rdecrq;
 414
 415 #ifdef __cplusplus
 416 }
 417 #endif
 418 #endif /* PROTOCOL_BINARY_H */