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