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