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