2 +--------------------------------------------------------------------+
3 | libmemcached - C/C++ Client Library for memcached |
4 +--------------------------------------------------------------------+
5 | Redistribution and use in source and binary forms, with or without |
6 | modification, are permitted under the terms of the BSD license. |
7 | You should have received a copy of the license in a bundled file |
8 | named LICENSE; in case you did not receive a copy you can review |
9 | the terms online at: https://opensource.org/licenses/BSD-3-Clause |
10 +--------------------------------------------------------------------+
11 | Copyright (c) 2006-2014 Brian Aker https://datadifferential.com/ |
12 | Copyright (c) 2020 Michael Wallner <mike@php.net> |
13 +--------------------------------------------------------------------+
16 #ifndef PROTOCOL_BINARY_H
17 #define PROTOCOL_BINARY_H
19 #include "libmemcachedprotocol-0.0/vbucket.h"
22 * \addtogroup Protocol
27 * This file contains definitions of the constants and packet formats
28 * defined in the binary specification. Please note that you _MUST_ remember
29 * to convert each multibyte field to / from network byte order to / from
37 * Definition of the legal "magic" values used in a packet.
38 * See section 3.1 Magic byte
40 typedef enum { PROTOCOL_BINARY_REQ
= 0x80, PROTOCOL_BINARY_RES
= 0x81 } protocol_binary_magic
;
43 * Definition of the valid response status numbers.
44 * See section 3.2 Response Status
47 PROTOCOL_BINARY_RESPONSE_SUCCESS
= 0x00,
48 PROTOCOL_BINARY_RESPONSE_KEY_ENOENT
= 0x01,
49 PROTOCOL_BINARY_RESPONSE_KEY_EEXISTS
= 0x02,
50 PROTOCOL_BINARY_RESPONSE_E2BIG
= 0x03,
51 PROTOCOL_BINARY_RESPONSE_EINVAL
= 0x04,
52 PROTOCOL_BINARY_RESPONSE_NOT_STORED
= 0x05,
53 PROTOCOL_BINARY_RESPONSE_DELTA_BADVAL
= 0x06,
54 PROTOCOL_BINARY_RESPONSE_NOT_MY_VBUCKET
= 0x07,
55 PROTOCOL_BINARY_RESPONSE_AUTH_ERROR
= 0x20,
56 PROTOCOL_BINARY_RESPONSE_AUTH_CONTINUE
= 0x21,
57 PROTOCOL_BINARY_RESPONSE_UNKNOWN_COMMAND
= 0x81,
58 PROTOCOL_BINARY_RESPONSE_ENOMEM
= 0x82,
59 PROTOCOL_BINARY_RESPONSE_NOT_SUPPORTED
= 0x83,
60 PROTOCOL_BINARY_RESPONSE_EINTERNAL
= 0x84,
61 PROTOCOL_BINARY_RESPONSE_EBUSY
= 0x85,
62 PROTOCOL_BINARY_RESPONSE_ETMPFAIL
= 0x86
63 } protocol_binary_response_status
;
66 * Defintion of the different command opcodes.
67 * See section 3.3 Command Opcodes
70 PROTOCOL_BINARY_CMD_GET
= 0x00,
71 PROTOCOL_BINARY_CMD_SET
= 0x01,
72 PROTOCOL_BINARY_CMD_ADD
= 0x02,
73 PROTOCOL_BINARY_CMD_REPLACE
= 0x03,
74 PROTOCOL_BINARY_CMD_DELETE
= 0x04,
75 PROTOCOL_BINARY_CMD_INCREMENT
= 0x05,
76 PROTOCOL_BINARY_CMD_DECREMENT
= 0x06,
77 PROTOCOL_BINARY_CMD_QUIT
= 0x07,
78 PROTOCOL_BINARY_CMD_FLUSH
= 0x08,
79 PROTOCOL_BINARY_CMD_GETQ
= 0x09,
80 PROTOCOL_BINARY_CMD_NOOP
= 0x0a,
81 PROTOCOL_BINARY_CMD_VERSION
= 0x0b,
82 PROTOCOL_BINARY_CMD_GETK
= 0x0c,
83 PROTOCOL_BINARY_CMD_GETKQ
= 0x0d,
84 PROTOCOL_BINARY_CMD_APPEND
= 0x0e,
85 PROTOCOL_BINARY_CMD_PREPEND
= 0x0f,
86 PROTOCOL_BINARY_CMD_STAT
= 0x10,
87 PROTOCOL_BINARY_CMD_SETQ
= 0x11,
88 PROTOCOL_BINARY_CMD_ADDQ
= 0x12,
89 PROTOCOL_BINARY_CMD_REPLACEQ
= 0x13,
90 PROTOCOL_BINARY_CMD_DELETEQ
= 0x14,
91 PROTOCOL_BINARY_CMD_INCREMENTQ
= 0x15,
92 PROTOCOL_BINARY_CMD_DECREMENTQ
= 0x16,
93 PROTOCOL_BINARY_CMD_QUITQ
= 0x17,
94 PROTOCOL_BINARY_CMD_FLUSHQ
= 0x18,
95 PROTOCOL_BINARY_CMD_APPENDQ
= 0x19,
96 PROTOCOL_BINARY_CMD_PREPENDQ
= 0x1a,
97 PROTOCOL_BINARY_CMD_VERBOSITY
= 0x1b,
98 PROTOCOL_BINARY_CMD_TOUCH
= 0x1c,
99 PROTOCOL_BINARY_CMD_GAT
= 0x1d,
100 PROTOCOL_BINARY_CMD_GATQ
= 0x1e,
101 PROTOCOL_BINARY_CMD_GATK
= 0x23,
102 PROTOCOL_BINARY_CMD_GATKQ
= 0x24,
104 PROTOCOL_BINARY_CMD_SASL_LIST_MECHS
= 0x20,
105 PROTOCOL_BINARY_CMD_SASL_AUTH
= 0x21,
106 PROTOCOL_BINARY_CMD_SASL_STEP
= 0x22,
108 /* These commands are used for range operations and exist within
109 * this header for use in other projects. Range operations are
110 * not expected to be implemented in the memcached server itself.
112 PROTOCOL_BINARY_CMD_RGET
= 0x30,
113 PROTOCOL_BINARY_CMD_RSET
= 0x31,
114 PROTOCOL_BINARY_CMD_RSETQ
= 0x32,
115 PROTOCOL_BINARY_CMD_RAPPEND
= 0x33,
116 PROTOCOL_BINARY_CMD_RAPPENDQ
= 0x34,
117 PROTOCOL_BINARY_CMD_RPREPEND
= 0x35,
118 PROTOCOL_BINARY_CMD_RPREPENDQ
= 0x36,
119 PROTOCOL_BINARY_CMD_RDELETE
= 0x37,
120 PROTOCOL_BINARY_CMD_RDELETEQ
= 0x38,
121 PROTOCOL_BINARY_CMD_RINCR
= 0x39,
122 PROTOCOL_BINARY_CMD_RINCRQ
= 0x3a,
123 PROTOCOL_BINARY_CMD_RDECR
= 0x3b,
124 PROTOCOL_BINARY_CMD_RDECRQ
= 0x3c,
125 /* End Range operations */
127 /* VBucket commands */
128 PROTOCOL_BINARY_CMD_SET_VBUCKET
= 0x3d,
129 PROTOCOL_BINARY_CMD_GET_VBUCKET
= 0x3e,
130 PROTOCOL_BINARY_CMD_DEL_VBUCKET
= 0x3f,
131 /* End VBucket commands */
134 PROTOCOL_BINARY_CMD_TAP_CONNECT
= 0x40,
135 PROTOCOL_BINARY_CMD_TAP_MUTATION
= 0x41,
136 PROTOCOL_BINARY_CMD_TAP_DELETE
= 0x42,
137 PROTOCOL_BINARY_CMD_TAP_FLUSH
= 0x43,
138 PROTOCOL_BINARY_CMD_TAP_OPAQUE
= 0x44,
139 PROTOCOL_BINARY_CMD_TAP_VBUCKET_SET
= 0x45,
140 PROTOCOL_BINARY_CMD_TAP_CHECKPOINT_START
= 0x46,
141 PROTOCOL_BINARY_CMD_TAP_CHECKPOINT_END
= 0x47,
144 PROTOCOL_BINARY_CMD_LAST_RESERVED
= 0xef,
147 PROTOCOL_BINARY_CMD_SCRUB
= 0xf0
148 } protocol_binary_command
;
151 * Definition of the data types in the packet
152 * See section 3.4 Data Types
154 typedef enum { PROTOCOL_BINARY_RAW_BYTES
= 0x00 } protocol_binary_datatypes
;
157 * Definition of the header structure for a request packet.
173 } protocol_binary_request_header
;
176 * Definition of the header structure for a response packet.
192 } protocol_binary_response_header
;
195 * Definition of a request-packet containing no extras
197 union protocol_binary_request_no_extras
{
199 protocol_binary_request_header header
;
201 uint8_t bytes
[sizeof(protocol_binary_request_header
)];
203 typedef union protocol_binary_request_no_extras protocol_binary_request_no_extras
;
206 * Definition of a response-packet containing no extras
210 protocol_binary_response_header header
;
212 uint8_t bytes
[sizeof(protocol_binary_response_header
)];
213 } protocol_binary_response_no_extras
;
216 * Definition of the packet used by the get, getq, getk and getkq command.
219 typedef protocol_binary_request_no_extras protocol_binary_request_get
;
220 typedef protocol_binary_request_no_extras protocol_binary_request_getq
;
221 typedef protocol_binary_request_no_extras protocol_binary_request_getk
;
222 typedef protocol_binary_request_no_extras protocol_binary_request_getkq
;
225 * Definition of the packet returned from a successful get, getq, getk and
231 protocol_binary_response_header header
;
236 uint8_t bytes
[sizeof(protocol_binary_response_header
) + 4];
237 } protocol_binary_response_get
;
239 typedef protocol_binary_response_get protocol_binary_response_getq
;
240 typedef protocol_binary_response_get protocol_binary_response_getk
;
241 typedef protocol_binary_response_get protocol_binary_response_getkq
;
244 * Definition of the packet used by the delete command
247 typedef protocol_binary_request_no_extras protocol_binary_request_delete
;
250 * Definition of the packet returned by the delete command
253 typedef protocol_binary_response_no_extras protocol_binary_response_delete
;
256 * Definition of the packet used by the flush command
258 * Please note that the expiration field is optional, so remember to see
259 * check the header.bodysize to see if it is present.
263 protocol_binary_request_header header
;
268 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 4];
269 } protocol_binary_request_flush
;
272 * Definition of the packet returned by the flush command
275 typedef protocol_binary_response_no_extras protocol_binary_response_flush
;
278 * Definition of the packet used by set, add and replace
283 protocol_binary_request_header header
;
289 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 8];
290 } protocol_binary_request_set
;
291 typedef protocol_binary_request_set protocol_binary_request_add
;
292 typedef protocol_binary_request_set protocol_binary_request_replace
;
295 * Definition of the packet returned by set, add and replace
298 typedef protocol_binary_response_no_extras protocol_binary_response_set
;
299 typedef protocol_binary_response_no_extras protocol_binary_response_add
;
300 typedef protocol_binary_response_no_extras protocol_binary_response_replace
;
303 * Definition of the noop packet
306 typedef protocol_binary_request_no_extras protocol_binary_request_noop
;
309 * Definition of the packet returned by the noop command
312 typedef protocol_binary_response_no_extras protocol_binary_response_noop
;
315 * Definition of the structure used by the increment and decrement
321 protocol_binary_request_header header
;
328 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 20];
329 } protocol_binary_request_incr
;
330 typedef protocol_binary_request_incr protocol_binary_request_decr
;
333 * Definition of the response from an incr or decr command
339 protocol_binary_response_header header
;
344 uint8_t bytes
[sizeof(protocol_binary_response_header
) + 8];
345 } protocol_binary_response_incr
;
346 typedef protocol_binary_response_incr protocol_binary_response_decr
;
349 * Definition of the quit
352 typedef protocol_binary_request_no_extras protocol_binary_request_quit
;
355 * Definition of the packet returned by the quit command
358 typedef protocol_binary_response_no_extras protocol_binary_response_quit
;
361 * Definition of the packet used by append and prepend command
364 typedef protocol_binary_request_no_extras protocol_binary_request_append
;
365 typedef protocol_binary_request_no_extras protocol_binary_request_prepend
;
368 * Definition of the packet returned from a successful append or prepend
371 typedef protocol_binary_response_no_extras protocol_binary_response_append
;
372 typedef protocol_binary_response_no_extras protocol_binary_response_prepend
;
375 * Definition of the packet used by the version command
378 typedef protocol_binary_request_no_extras protocol_binary_request_version
;
381 * Definition of the packet returned from a successful version command
384 typedef protocol_binary_response_no_extras protocol_binary_response_version
;
387 * Definition of the packet used by the stats command.
390 typedef protocol_binary_request_no_extras protocol_binary_request_stats
;
393 * Definition of the packet returned from a successful stats command
396 typedef protocol_binary_response_no_extras protocol_binary_response_stats
;
399 * Definition of the packet used by the verbosity command
403 protocol_binary_request_header header
;
408 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 4];
409 } protocol_binary_request_verbosity
;
412 * Definition of the packet returned from the verbosity command
414 typedef protocol_binary_response_no_extras protocol_binary_response_verbosity
;
417 * Definition of the packet used by the touch command.
421 protocol_binary_request_header header
;
426 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 4];
427 } protocol_binary_request_touch
;
430 * Definition of the packet returned from the touch command
432 typedef protocol_binary_response_no_extras protocol_binary_response_touch
;
435 * Definition of the packet used by the GAT(Q) command.
439 protocol_binary_request_header header
;
444 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 4];
445 } protocol_binary_request_gat
;
447 typedef protocol_binary_request_gat protocol_binary_request_gatq
;
450 * Definition of the packet returned from the GAT(Q)
452 typedef protocol_binary_response_get protocol_binary_response_gat
;
453 typedef protocol_binary_response_get protocol_binary_response_gatq
;
456 * Definition of a request for a range operation.
457 * See http://code.google.com/p/memcached/wiki/RangeOps
459 * These types are used for range operations and exist within
460 * this header for use in other projects. Range operations are
461 * not expected to be implemented in the memcached server itself.
465 protocol_binary_response_header header
;
470 uint32_t max_results
;
473 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 4];
474 } protocol_binary_request_rangeop
;
476 typedef protocol_binary_request_rangeop protocol_binary_request_rget
;
477 typedef protocol_binary_request_rangeop protocol_binary_request_rset
;
478 typedef protocol_binary_request_rangeop protocol_binary_request_rsetq
;
479 typedef protocol_binary_request_rangeop protocol_binary_request_rappend
;
480 typedef protocol_binary_request_rangeop protocol_binary_request_rappendq
;
481 typedef protocol_binary_request_rangeop protocol_binary_request_rprepend
;
482 typedef protocol_binary_request_rangeop protocol_binary_request_rprependq
;
483 typedef protocol_binary_request_rangeop protocol_binary_request_rdelete
;
484 typedef protocol_binary_request_rangeop protocol_binary_request_rdeleteq
;
485 typedef protocol_binary_request_rangeop protocol_binary_request_rincr
;
486 typedef protocol_binary_request_rangeop protocol_binary_request_rincrq
;
487 typedef protocol_binary_request_rangeop protocol_binary_request_rdecr
;
488 typedef protocol_binary_request_rangeop protocol_binary_request_rdecrq
;
491 * Definition of tap commands
498 protocol_binary_request_header header
;
501 * flags is a bitmask used to set properties for the
502 * the connection. Please In order to be forward compatible
503 * you should set all undefined bits to 0.
505 * If the bit require extra userdata, it will be stored
506 * in the user-data field of the body (passed to the engine
507 * as enginespeciffic). That means that when you parse the
508 * flags and the engine-specific data, you have to work your
509 * way from bit 0 and upwards to find the correct offset for
518 * By using this flag you can limit the amount of data being
519 * transmitted. If you don't specify a backfill age, the
520 * server will transmit everything it contains.
522 * The first 8 bytes in the engine specific data contains
523 * the oldest entry (from epoc) you're interested in.
524 * Specifying a time in the future (for the server you are
525 * connecting to), will cause it to start streaming current
528 #define TAP_CONNECT_FLAG_BACKFILL 0x01
530 * Dump will cause the server to send the data stored on the
531 * server, but disconnect when the keys stored in the server
534 #define TAP_CONNECT_FLAG_DUMP 0x02
536 * The body contains a list of 16 bits words in network byte
537 * order specifying the vbucket ids to monitor. The first 16
538 * bit word contains the number of buckets. The number of 0
539 * means "all buckets"
541 #define TAP_CONNECT_FLAG_LIST_VBUCKETS 0x04
543 * The responsibility of the vbuckets is to be transferred
544 * over to the caller when all items are transferred.
546 #define TAP_CONNECT_FLAG_TAKEOVER_VBUCKETS 0x08
548 * The tap consumer supports ack'ing of tap messages
550 #define TAP_CONNECT_SUPPORT_ACK 0x10
552 * The tap consumer would prefer to just get the keys
553 * back. If the engine supports this it will set
554 * the TAP_FLAG_NO_VALUE flag in each of the
555 * tap packets returned.
557 #define TAP_CONNECT_REQUEST_KEYS_ONLY 0x20
559 * The body contains a list of (vbucket_id, last_checkpoint_id)
560 * pairs. This provides the checkpoint support in TAP streams.
561 * The last checkpoint id represents the last checkpoint that
562 * was successfully persisted.
564 #define TAP_CONNECT_CHECKPOINT 0x40
566 * The tap consumer is a registered tap client, which means that
567 * the tap server will maintain its checkpoint cursor permanently.
569 #define TAP_CONNECT_REGISTERED_CLIENT 0x80
572 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 4];
573 } protocol_binary_request_tap_connect
;
577 protocol_binary_request_header header
;
580 uint16_t enginespecific_length
;
582 * The flag section support the following flags
585 * Request that the consumer send a response packet
586 * for this packet. The opaque field must be preserved
589 #define TAP_FLAG_ACK 0x01
591 * The value for the key is not included in the packet
593 #define TAP_FLAG_NO_VALUE 0x02
606 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 16];
607 } protocol_binary_request_tap_mutation
;
611 protocol_binary_request_header header
;
614 uint16_t enginespecific_length
;
616 * See the definition of the flags for
617 * protocol_binary_request_tap_mutation for a description
618 * of the available flags.
628 uint8_t bytes
[sizeof(protocol_binary_request_header
) + 8];
629 } protocol_binary_request_tap_no_extras
;
631 typedef protocol_binary_request_tap_no_extras protocol_binary_request_tap_delete
;
632 typedef protocol_binary_request_tap_no_extras protocol_binary_request_tap_flush
;
633 typedef protocol_binary_request_tap_no_extras protocol_binary_request_tap_opaque
;
634 typedef protocol_binary_request_tap_no_extras protocol_binary_request_tap_vbucket_set
;
637 * Definition of the packet used by the scrub.
639 typedef protocol_binary_request_no_extras protocol_binary_request_scrub
;
642 * Definition of the packet returned from scrub.
644 typedef protocol_binary_response_no_extras protocol_binary_response_scrub
;
647 * Definition of the packet used by set vbucket
651 protocol_binary_request_header header
;
653 vbucket_state_t state
;
656 uint8_t bytes
[sizeof(protocol_binary_request_header
) + sizeof(vbucket_state_t
)];
657 } protocol_binary_request_set_vbucket
;
659 * Definition of the packet returned from set vbucket
661 typedef protocol_binary_response_no_extras protocol_binary_response_set_vbucket
;
663 * Definition of the packet used by del vbucket
665 typedef protocol_binary_request_no_extras protocol_binary_request_del_vbucket
;
667 * Definition of the packet returned from del vbucket
669 typedef protocol_binary_response_no_extras protocol_binary_response_del_vbucket
;
672 * Definition of the packet used by get vbucket
674 typedef protocol_binary_request_no_extras protocol_binary_request_get_vbucket
;
677 * Definition of the packet returned from get vbucket
681 protocol_binary_response_header header
;
683 vbucket_state_t state
;
686 uint8_t bytes
[sizeof(protocol_binary_response_header
) + sizeof(vbucket_state_t
)];
687 } protocol_binary_response_get_vbucket
;
696 #endif /* PROTOCOL_BINARY_H */