git.m6w6.name Git - m6w6/libmemcached/blob - clients/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 /*
  29  * Summary: Constants used by to implement the binary protocol.
  30  *
  31  * Copy: See Copyright for the status of this software.
  32  *
  33  * Author: Trond Norbye <trond.norbye@sun.com>
  34  */
  35
  36 #ifndef PROTOCOL_BINARY_H
  37 #define PROTOCOL_BINARY_H
  38
  39 #include <stdint.h>
  40
  41 /**
  42  * This file contains definitions of the constants and packet formats
  43  * defined in the binary specification. Please note that you _MUST_ remember
  44  * to convert each multibyte field to / from network byte order to / from
  45  * host order.
  46  */
  47 #ifdef __cplusplus
  48 extern "C"
  49 {
  50 #endif
  51
  52 /**
  53  * Definition of the legal "magic" values used in a packet.
  54  * See section 3.1 Magic byte
  55  */
  56 typedef enum
  57 {
  58   PROTOCOL_BINARY_REQ= 0x80,
  59   PROTOCOL_BINARY_RES= 0x81
  60 } protocol_binary_magic;
  61
  62 /**
  63  * Definition of the valid response status numbers.
  64  * See section 3.2 Response Status
  65  */
  66 typedef enum
  67 {
  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_UNKNOWN_COMMAND= 0x81,
  75   PROTOCOL_BINARY_RESPONSE_ENOMEM= 0x82
  76 } protocol_binary_response_status;
  77
  78 /**
  79  * Defintion of the different command opcodes.
  80  * See section 3.3 Command Opcodes
  81  */
  82 typedef enum
  83 {
  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 } protocol_binary_command;
 112
 113 /**
 114  * Definition of the data types in the packet
 115  * See section 3.4 Data Types
 116  */
 117 typedef enum
 118 {
 119   PROTOCOL_BINARY_RAW_BYTES= 0x00
 120 } protocol_binary_datatypes;
 121
 122 /**
 123  * Definition of the header structure for a request packet.
 124  * See section 2
 125  */
 126 typedef union
 127 {
 128   struct
 129   {
 130     uint8_t magic;
 131     uint8_t opcode;
 132     uint16_t keylen;
 133     uint8_t extlen;
 134     uint8_t datatype;
 135     uint16_t reserved;
 136     uint32_t bodylen;
 137     uint32_t opaque;
 138     uint64_t cas;
 139   } request;
 140   uint8_t bytes[24];
 141 } protocol_binary_request_header;
 142
 143 /**
 144  * Definition of the header structure for a response packet.
 145  * See section 2
 146  */
 147 typedef union
 148 {
 149   struct
 150   {
 151     uint8_t magic;
 152     uint8_t opcode;
 153     uint16_t keylen;
 154     uint8_t extlen;
 155     uint8_t datatype;
 156     uint16_t status;
 157     uint32_t bodylen;
 158     uint32_t opaque;
 159     uint64_t cas;
 160   } response;
 161   uint8_t bytes[24];
 162 } protocol_binary_response_header;
 163
 164 /**
 165  * Definition of a request-packet containing no extras
 166  */
 167 typedef union
 168 {
 169   struct
 170   {
 171     protocol_binary_request_header header;
 172   } message;
 173   uint8_t bytes[sizeof(protocol_binary_request_header)];
 174 } protocol_binary_request_no_extras;
 175
 176 /**
 177  * Definition of a response-packet containing no extras
 178  */
 179 typedef union
 180 {
 181   struct
 182   {
 183     protocol_binary_response_header header;
 184   } message;
 185   uint8_t bytes[sizeof(protocol_binary_response_header)];
 186 } protocol_binary_response_no_extras;
 187
 188 /**
 189  * Definition of the packet used by the get, getq, getk and getkq command.
 190  * See section 4
 191  */
 192 typedef protocol_binary_request_no_extras   protocol_binary_request_get;
 193 typedef protocol_binary_request_no_extras   protocol_binary_request_getq;
 194 typedef protocol_binary_request_no_extras   protocol_binary_request_getk;
 195 typedef protocol_binary_request_no_extras   protocol_binary_request_getkq;
 196
 197 /**
 198  * Definition of the packet returned from a successful get, getq, getk and
 199  * getkq.
 200  * See section 4
 201  */
 202 typedef union
 203 {
 204   struct
 205   {
 206     protocol_binary_response_header header;
 207     struct
 208     {
 209       uint32_t flags;
 210     } body;
 211   } message;
 212   uint8_t bytes[sizeof(protocol_binary_response_header) + 4];
 213 } protocol_binary_response_get;
 214
 215 typedef protocol_binary_response_get        protocol_binary_response_getq;
 216 typedef protocol_binary_response_get        protocol_binary_response_getk;
 217 typedef protocol_binary_response_get        protocol_binary_response_getkq;
 218
 219 /**
 220  * Definition of the packet used by the delete command
 221  * See section 4
 222  */
 223 typedef protocol_binary_request_no_extras   protocol_binary_request_delete;
 224
 225 /**
 226  * Definition of the packet returned by the delete command
 227  * See section 4
 228  */
 229 typedef protocol_binary_response_no_extras
 230 protocol_binary_response_delete;
 231
 232 /**
 233  * Definition of the packet used by the flush command
 234  * See section 4
 235  * Please note that the expiration field is optional, so remember to see
 236  * check the header.bodysize to see if it is present.
 237  */
 238 typedef union
 239 {
 240   struct
 241   {
 242     protocol_binary_request_header header;
 243     struct
 244     {
 245       uint32_t expiration;
 246     } body;
 247   } message;
 248   uint8_t bytes[sizeof(protocol_binary_request_header) + 4];
 249 } protocol_binary_request_flush;
 250
 251 /**
 252  * Definition of the packet returned by the flush command
 253  * See section 4
 254  */
 255 typedef protocol_binary_response_no_extras   protocol_binary_response_flush;
 256
 257 /**
 258  * Definition of the packet used by set, add and replace
 259  * See section 4
 260  */
 261 typedef union
 262 {
 263   struct
 264   {
 265     protocol_binary_request_header header;
 266     struct
 267     {
 268       uint32_t flags;
 269       uint32_t expiration;
 270     } body;
 271   } message;
 272   uint8_t bytes[sizeof(protocol_binary_request_header) + 8];
 273 } protocol_binary_request_set;
 274 typedef protocol_binary_request_set          protocol_binary_request_add;
 275 typedef protocol_binary_request_set
 276 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
 285 protocol_binary_response_replace;
 286
 287 /**
 288  * Definition of the noop packet
 289  * See section 4
 290  */
 291 typedef protocol_binary_request_no_extras    protocol_binary_request_noop;
 292
 293 /**
 294  * Definition of the packet returned by the noop command
 295  * See section 4
 296  */
 297 typedef protocol_binary_response_no_extras   protocol_binary_response_noop;
 298
 299 /**
 300  * Definition of the structure used by the increment and decrement
 301  * command.
 302  * See section 4
 303  */
 304 typedef union
 305 {
 306   struct
 307   {
 308     protocol_binary_request_header header;
 309     struct
 310     {
 311       uint64_t delta;
 312       uint64_t initial;
 313       uint32_t expiration;
 314     } body;
 315   } message;
 316   uint8_t bytes[sizeof(protocol_binary_request_header) + 20];
 317 } protocol_binary_request_incr;
 318 typedef protocol_binary_request_incr   protocol_binary_request_decr;
 319
 320 /**
 321  * Definition of the response from an incr or decr command
 322  * command.
 323  * See section 4
 324  */
 325 typedef union
 326 {
 327   struct
 328   {
 329     protocol_binary_response_header header;
 330     struct
 331     {
 332       uint64_t value;
 333     } body;
 334   } message;
 335   uint8_t bytes[sizeof(protocol_binary_response_header) + 8];
 336 } protocol_binary_response_incr;
 337 typedef protocol_binary_response_incr        protocol_binary_response_decr;
 338
 339 /**
 340  * Definition of the quit
 341  * See section 4
 342  */
 343 typedef protocol_binary_request_no_extras    protocol_binary_request_quit;
 344
 345 /**
 346  * Definition of the packet returned by the quit command
 347  * See section 4
 348  */
 349 typedef protocol_binary_response_no_extras   protocol_binary_response_quit;
 350
 351 /**
 352  * Definition of the packet used by append and prepend command
 353  * See section 4
 354  */
 355 typedef protocol_binary_request_no_extras    protocol_binary_request_append;
 356 typedef protocol_binary_request_no_extras
 357 protocol_binary_request_prepend;
 358
 359 /**
 360  * Definition of the packet returned from a successful append or prepend
 361  * See section 4
 362  */
 363 typedef protocol_binary_response_no_extras
 364 protocol_binary_response_append;
 365 typedef protocol_binary_response_no_extras
 366 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
 373 protocol_binary_request_version;
 374
 375 /**
 376  * Definition of the packet returned from a successful version command
 377  * See section 4
 378  */
 379 typedef protocol_binary_response_no_extras
 380 protocol_binary_response_version;
 381
 382
 383 /**
 384  * Definition of the packet used by the stats command.
 385  * See section 4
 386  */
 387 typedef protocol_binary_request_no_extras    protocol_binary_request_stats;
 388
 389 /**
 390  * Definition of the packet returned from a successful stats command
 391  * See section 4
 392  */
 393 typedef protocol_binary_response_no_extras   protocol_binary_response_stats;
 394 #ifdef __cplusplus
 395 }
 396 #endif
 397 #endif /* PROTOCOL_BINARY_H */