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