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