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 +--------------------------------------------------------------------+
19 * Callback to send data back from a successful GET/GETQ/GETK/GETKQ command
21 * @param cookie Just pass along the cookie supplied in the callback
22 * @param key What to insert as key in the reply
23 * @param keylen The length of the key
24 * @param body What to store in the body of the package
25 * @param bodylen The number of bytes of the body
26 * @param flags The flags stored with the item
27 * @param cas The CAS value to insert into the response (should be 0
30 typedef protocol_binary_response_status (*memcached_binary_protocol_get_response_handler
)(
31 const void *cookie
, const void *key
, uint16_t keylen
, const void *body
, uint32_t bodylen
,
32 uint32_t flags
, uint64_t cas
);
34 * Callback to send data back from a STAT command
36 * @param cookie Just pass along the cookie supplied in the callback
37 * @param key What to insert as key in the reply
38 * @param keylen The length of the key
39 * @param body What to store in the body of the package
40 * @param bodylen The number of bytes of the body
42 typedef protocol_binary_response_status (*memcached_binary_protocol_stat_response_handler
)(
43 const void *cookie
, const void *key
, uint16_t keylen
, const void *body
, uint32_t bodylen
);
45 * Callback to send data back from a VERSION command
47 * @param cookie Just pass along the cookie supplied in the callback
48 * @param text The version string
49 * @param length The number of bytes in the version string
51 typedef protocol_binary_response_status (*memcached_binary_protocol_version_response_handler
)(
52 const void *cookie
, const void *text
, uint32_t length
);
55 * In the low level interface you need to format the response
56 * packet yourself (giving you complete freedom :-)
58 * @param cookie Just pass along the cookie supplied in the callback
59 * @param request Pointer to the request packet you are sending a reply to
60 * @param response Pointer to the response packet to send
63 typedef protocol_binary_response_status (*memcached_binary_protocol_raw_response_handler
)(
64 const void *cookie
, protocol_binary_request_header
*request
,
65 protocol_binary_response_header
*response
);
68 * In the low lever interface you have to do most of the work by
69 * yourself, but it also gives you a lot of freedom :-)
70 * @param cookie identification for this connection, just pass it along to
71 * the response handler
72 * @param header the command received over the wire. Never try to access
73 * <u>anything</u> outside the command.
74 * @param resonse_handler call this function to send data back to the client
76 typedef protocol_binary_response_status (*memcached_binary_protocol_command_handler
)(
77 const void *cookie
, protocol_binary_request_header
*header
,
78 memcached_binary_protocol_raw_response_handler response_handler
);
81 * The raw interface to the packets is implemented in version 0. It contains
82 * just an array with command handlers. The inxed in the array is the
86 memcached_binary_protocol_command_handler comcode
[256];
87 } memcached_binary_protocol_callback_v0_st
;
90 * The first version of the callback struct containing all of the
91 * documented commands in the initial release of the binary protocol
92 * (aka. memcached 1.4.0).
94 * You might miss the Q commands (addq etc) but the response function
95 * knows how to deal with them so you don't need to worry about that :-)
99 * Add an item to the cache
100 * @param cookie id of the client receiving the command
101 * @param key the key to add
102 * @param len the length of the key
103 * @param val the value to store for the key (may be NIL)
104 * @param vallen the length of the data
105 * @param flags the flags to store with the key
106 * @param exptime the expiry time for the key-value pair
107 * @param cas the resulting cas for the add operation (if success)
109 protocol_binary_response_status (*add
)(const void *cookie
, const void *key
, uint16_t keylen
,
110 const void *val
, uint32_t vallen
, uint32_t flags
,
111 uint32_t exptime
, uint64_t *cas
);
114 * Append data to an <b>existing</b> key-value pair.
116 * @param cookie id of the client receiving the command
117 * @param key the key to add data to
118 * @param len the length of the key
119 * @param val the value to append to the value
120 * @param vallen the length of the data
121 * @param cas the CAS in the request
122 * @param result_cas the resulting cas for the append operation
125 protocol_binary_response_status (*append
)(const void *cookie
, const void *key
, uint16_t keylen
,
126 const void *val
, uint32_t vallen
, uint64_t cas
,
127 uint64_t *result_cas
);
130 * Decrement the value for a key
132 * @param cookie id of the client receiving the command
133 * @param key the key to decrement the value for
134 * @param len the length of the key
135 * @param delta the amount to decrement
136 * @param initial initial value to store (if the key doesn't exist)
137 * @param expiration expiration time for the object (if the key doesn't exist)
138 * @param cas the CAS in the request
139 * @param result the result from the decrement
140 * @param result_cas the cas of the item
143 protocol_binary_response_status (*decrement
)(const void *cookie
, const void *key
, uint16_t keylen
,
144 uint64_t delta
, uint64_t initial
,
145 uint32_t expiration
, uint64_t *result
,
146 uint64_t *result_cas
);
149 * Delete an existing key
151 * @param cookie id of the client receiving the command
152 * @param key the key to delete_object
153 * @param len the length of the key
154 * @param cas the CAS in the request
156 protocol_binary_response_status (*delete_object
)(const void *cookie
, const void *key
,
157 uint16_t keylen
, uint64_t cas
);
162 * @param cookie id of the client receiving the command
163 * @param when when the cache should be flushed (0 == immediately)
165 protocol_binary_response_status (*flush_object
)(const void *cookie
, uint32_t when
);
168 * Get a key-value pair
170 * @param cookie id of the client receiving the command
171 * @param key the key to get
172 * @param len the length of the key
173 * @param response_handler to send the result back to the client
175 protocol_binary_response_status (*get
)(
176 const void *cookie
, const void *key
, uint16_t keylen
,
177 memcached_binary_protocol_get_response_handler response_handler
);
180 * Increment the value for a key
182 * @param cookie id of the client receiving the command
183 * @param key the key to increment the value on
184 * @param len the length of the key
185 * @param delta the amount to increment
186 * @param initial initial value to store (if the key doesn't exist)
187 * @param expiration expiration time for the object (if the key doesn't exist)
188 * @param cas the CAS in the request
189 * @param result the result from the decrement
190 * @param result_cas the cas of the item
193 protocol_binary_response_status (*increment
)(const void *cookie
, const void *key
, uint16_t keylen
,
194 uint64_t delta
, uint64_t initial
,
195 uint32_t expiration
, uint64_t *result
,
196 uint64_t *result_cas
);
199 * The noop command was received. This is just a notification callback (the
200 * response is automatically created).
202 * @param cookie id of the client receiving the command
204 protocol_binary_response_status (*noop
)(const void *cookie
);
207 * Prepend data to an <b>existing</b> key-value pair.
209 * @param cookie id of the client receiving the command
210 * @param key the key to prepend data to
211 * @param len the length of the key
212 * @param val the value to prepend to the value
213 * @param vallen the length of the data
214 * @param cas the CAS in the request
215 * @param result-cas the cas id of the item
218 protocol_binary_response_status (*prepend
)(const void *cookie
, const void *key
, uint16_t keylen
,
219 const void *val
, uint32_t vallen
, uint64_t cas
,
220 uint64_t *result_cas
);
223 * The quit command was received. This is just a notification callback (the
224 * response is automatically created).
226 * @param cookie id of the client receiving the command
228 protocol_binary_response_status (*quit
)(const void *cookie
);
231 * Replace an <b>existing</b> item to the cache
233 * @param cookie id of the client receiving the command
234 * @param key the key to replace the content for
235 * @param len the length of the key
236 * @param val the value to store for the key (may be NIL)
237 * @param vallen the length of the data
238 * @param flags the flags to store with the key
239 * @param exptime the expiry time for the key-value pair
240 * @param cas the cas id in the request
241 * @param result_cas the cas id of the item
243 protocol_binary_response_status (*replace
)(const void *cookie
, const void *key
, uint16_t keylen
,
244 const void *val
, uint32_t vallen
, uint32_t flags
,
245 uint32_t exptime
, uint64_t cas
, uint64_t *result_cas
);
248 * Set a key-value pair in the cache
250 * @param cookie id of the client receiving the command
251 * @param key the key to insert
252 * @param len the length of the key
253 * @param val the value to store for the key (may be NIL)
254 * @param vallen the length of the data
255 * @param flags the flags to store with the key
256 * @param exptime the expiry time for the key-value pair
257 * @param cas the cas id in the request
258 * @param result_cas the cas id of the new item
260 protocol_binary_response_status (*set
)(const void *cookie
, const void *key
, uint16_t keylen
,
261 const void *val
, uint32_t vallen
, uint32_t flags
,
262 uint32_t exptime
, uint64_t cas
, uint64_t *result_cas
);
265 * Get status information
267 * @param cookie id of the client receiving the command
268 * @param key the key to get status for (or NIL to request all status).
269 * Remember to insert the terminating packet if multiple
270 * packets should be returned.
271 * @param keylen the length of the key
272 * @param response_handler to send the result back to the client, but
273 * don't send reply on success!
276 protocol_binary_response_status (*stat
)(
277 const void *cookie
, const void *key
, uint16_t keylen
,
278 memcached_binary_protocol_stat_response_handler response_handler
);
281 * Get the version information
283 * @param cookie id of the client receiving the command
284 * @param response_handler to send the result back to the client, but
285 * don't send reply on success!
288 protocol_binary_response_status (*version
)(
289 const void *cookie
, memcached_binary_protocol_version_response_handler response_handler
);
290 } memcached_binary_protocol_callback_v1_st
;
293 * The version numbers for the different callback structures.
296 /** Version 0 is a lowlevel interface that tries to maximize your freedom */
297 MEMCACHED_PROTOCOL_HANDLER_V0
= 0,
299 * Version 1 abstracts more of the protocol details, and let you work at
302 MEMCACHED_PROTOCOL_HANDLER_V1
= 1
303 } memcached_protocol_interface_version_t
;
306 * Definition of the protocol callback structure.
310 * The interface version you provide callbacks for.
312 memcached_protocol_interface_version_t interface_version
;
315 * Callback fired just before the command will be executed.
317 * @param cookie id of the client receiving the command
318 * @param header the command header as received on the wire. If you look
319 * at the content you <b>must</b> ensure that you don't
320 * try to access beyond the end of the message.
322 void (*pre_execute
)(const void *cookie
, protocol_binary_request_header
*header
);
324 * Callback fired just after the command was exected (please note
325 * that the data transfer back to the client is not finished at this
328 * @param cookie id of the client receiving the command
329 * @param header the command header as received on the wire. If you look
330 * at the content you <b>must</b> ensure that you don't
331 * try to access beyond the end of the message.
333 void (*post_execute
)(const void *cookie
, protocol_binary_request_header
*header
);
336 * Callback fired if no specialized callback is registered for this
337 * specific command code.
339 * @param cookie id of the client receiving the command
340 * @param header the command header as received on the wire. You <b>must</b>
341 * ensure that you don't try to access beyond the end of the
343 * @param response_handler The response handler to send data back.
345 protocol_binary_response_status (*unknown
)(
346 const void *cookie
, protocol_binary_request_header
*header
,
347 memcached_binary_protocol_raw_response_handler response_handler
);
350 * The different interface levels we support. A pointer is used so the
351 * size of the structure is fixed. You must ensure that the memory area
352 * passed as the pointer is valid as long as you use the protocol handler.
355 memcached_binary_protocol_callback_v0_st v0
;
358 * The first version of the callback struct containing all of the
359 * documented commands in the initial release of the binary protocol
360 * (aka. memcached 1.4.0).
362 memcached_binary_protocol_callback_v1_st v1
;
364 } memcached_binary_protocol_callback_st
;