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