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 +--------------------------------------------------------------------+
30 * Callback to send data back from a successful GET/GETQ/GETK/GETKQ command
32 * @param cookie Just pass along the cookie supplied in the callback
33 * @param key What to insert as key in the reply
34 * @param keylen The length of the key
35 * @param body What to store in the body of the package
36 * @param bodylen The number of bytes of the body
37 * @param flags The flags stored with the item
38 * @param cas The CAS value to insert into the response (should be 0
41 typedef protocol_binary_response_status (*memcached_binary_protocol_get_response_handler
)(
42 const void *cookie
, const void *key
, uint16_t keylen
, const void *body
, uint32_t bodylen
,
43 uint32_t flags
, uint64_t cas
);
45 * Callback to send data back from a STAT command
47 * @param cookie Just pass along the cookie supplied in the callback
48 * @param key What to insert as key in the reply
49 * @param keylen The length of the key
50 * @param body What to store in the body of the package
51 * @param bodylen The number of bytes of the body
53 typedef protocol_binary_response_status (*memcached_binary_protocol_stat_response_handler
)(
54 const void *cookie
, const void *key
, uint16_t keylen
, const void *body
, uint32_t bodylen
);
56 * Callback to send data back from a VERSION command
58 * @param cookie Just pass along the cookie supplied in the callback
59 * @param text The version string
60 * @param length The number of bytes in the version string
62 typedef protocol_binary_response_status (*memcached_binary_protocol_version_response_handler
)(
63 const void *cookie
, const void *text
, uint32_t length
);
66 * In the low level interface you need to format the response
67 * packet yourself (giving you complete freedom :-)
69 * @param cookie Just pass along the cookie supplied in the callback
70 * @param request Pointer to the request packet you are sending a reply to
71 * @param response Pointer to the response packet to send
74 typedef protocol_binary_response_status (*memcached_binary_protocol_raw_response_handler
)(
75 const void *cookie
, protocol_binary_request_header
*request
,
76 protocol_binary_response_header
*response
);
79 * In the low lever interface you have to do most of the work by
80 * yourself, but it also gives you a lot of freedom :-)
81 * @param cookie identification for this connection, just pass it along to
82 * the response handler
83 * @param header the command received over the wire. Never try to access
84 * <u>anything</u> outside the command.
85 * @param resonse_handler call this function to send data back to the client
87 typedef protocol_binary_response_status (*memcached_binary_protocol_command_handler
)(
88 const void *cookie
, protocol_binary_request_header
*header
,
89 memcached_binary_protocol_raw_response_handler response_handler
);
92 * The raw interface to the packets is implemented in version 0. It contains
93 * just an array with command handlers. The inxed in the array is the
97 memcached_binary_protocol_command_handler comcode
[256];
98 } memcached_binary_protocol_callback_v0_st
;
101 * The first version of the callback struct containing all of the
102 * documented commands in the initial release of the binary protocol
103 * (aka. memcached 1.4.0).
105 * You might miss the Q commands (addq etc) but the response function
106 * knows how to deal with them so you don't need to worry about that :-)
110 * Add an item to the cache
111 * @param cookie id of the client receiving the command
112 * @param key the key to add
113 * @param len the length of the key
114 * @param val the value to store for the key (may be NIL)
115 * @param vallen the length of the data
116 * @param flags the flags to store with the key
117 * @param exptime the expiry time for the key-value pair
118 * @param cas the resulting cas for the add operation (if success)
120 protocol_binary_response_status (*add
)(const void *cookie
, const void *key
, uint16_t keylen
,
121 const void *val
, uint32_t vallen
, uint32_t flags
,
122 uint32_t exptime
, uint64_t *cas
);
125 * Append data to an <b>existing</b> key-value pair.
127 * @param cookie id of the client receiving the command
128 * @param key the key to add data to
129 * @param len the length of the key
130 * @param val the value to append to the value
131 * @param vallen the length of the data
132 * @param cas the CAS in the request
133 * @param result_cas the resulting cas for the append operation
136 protocol_binary_response_status (*append
)(const void *cookie
, const void *key
, uint16_t keylen
,
137 const void *val
, uint32_t vallen
, uint64_t cas
,
138 uint64_t *result_cas
);
141 * Decrement the value for a key
143 * @param cookie id of the client receiving the command
144 * @param key the key to decrement the value for
145 * @param len the length of the key
146 * @param delta the amount to decrement
147 * @param initial initial value to store (if the key doesn't exist)
148 * @param expiration expiration time for the object (if the key doesn't exist)
149 * @param cas the CAS in the request
150 * @param result the result from the decrement
151 * @param result_cas the cas of the item
154 protocol_binary_response_status (*decrement
)(const void *cookie
, const void *key
, uint16_t keylen
,
155 uint64_t delta
, uint64_t initial
,
156 uint32_t expiration
, uint64_t *result
,
157 uint64_t *result_cas
);
160 * Delete an existing key
162 * @param cookie id of the client receiving the command
163 * @param key the key to delete_object
164 * @param len the length of the key
165 * @param cas the CAS in the request
167 protocol_binary_response_status (*delete_object
)(const void *cookie
, const void *key
,
168 uint16_t keylen
, uint64_t cas
);
173 * @param cookie id of the client receiving the command
174 * @param when when the cache should be flushed (0 == immediately)
176 protocol_binary_response_status (*flush_object
)(const void *cookie
, uint32_t when
);
179 * Get a key-value pair
181 * @param cookie id of the client receiving the command
182 * @param key the key to get
183 * @param len the length of the key
184 * @param response_handler to send the result back to the client
186 protocol_binary_response_status (*get
)(
187 const void *cookie
, const void *key
, uint16_t keylen
,
188 memcached_binary_protocol_get_response_handler response_handler
);
191 * Increment the value for a key
193 * @param cookie id of the client receiving the command
194 * @param key the key to increment the value on
195 * @param len the length of the key
196 * @param delta the amount to increment
197 * @param initial initial value to store (if the key doesn't exist)
198 * @param expiration expiration time for the object (if the key doesn't exist)
199 * @param cas the CAS in the request
200 * @param result the result from the decrement
201 * @param result_cas the cas of the item
204 protocol_binary_response_status (*increment
)(const void *cookie
, const void *key
, uint16_t keylen
,
205 uint64_t delta
, uint64_t initial
,
206 uint32_t expiration
, uint64_t *result
,
207 uint64_t *result_cas
);
210 * The noop command was received. This is just a notification callback (the
211 * response is automatically created).
213 * @param cookie id of the client receiving the command
215 protocol_binary_response_status (*noop
)(const void *cookie
);
218 * Prepend data to an <b>existing</b> key-value pair.
220 * @param cookie id of the client receiving the command
221 * @param key the key to prepend data to
222 * @param len the length of the key
223 * @param val the value to prepend to the value
224 * @param vallen the length of the data
225 * @param cas the CAS in the request
226 * @param result-cas the cas id of the item
229 protocol_binary_response_status (*prepend
)(const void *cookie
, const void *key
, uint16_t keylen
,
230 const void *val
, uint32_t vallen
, uint64_t cas
,
231 uint64_t *result_cas
);
234 * The quit command was received. This is just a notification callback (the
235 * response is automatically created).
237 * @param cookie id of the client receiving the command
239 protocol_binary_response_status (*quit
)(const void *cookie
);
242 * Replace an <b>existing</b> item to the cache
244 * @param cookie id of the client receiving the command
245 * @param key the key to replace the content for
246 * @param len the length of the key
247 * @param val the value to store for the key (may be NIL)
248 * @param vallen the length of the data
249 * @param flags the flags to store with the key
250 * @param exptime the expiry time for the key-value pair
251 * @param cas the cas id in the request
252 * @param result_cas the cas id of the item
254 protocol_binary_response_status (*replace
)(const void *cookie
, const void *key
, uint16_t keylen
,
255 const void *val
, uint32_t vallen
, uint32_t flags
,
256 uint32_t exptime
, uint64_t cas
, uint64_t *result_cas
);
259 * Set a key-value pair in the cache
261 * @param cookie id of the client receiving the command
262 * @param key the key to insert
263 * @param len the length of the key
264 * @param val the value to store for the key (may be NIL)
265 * @param vallen the length of the data
266 * @param flags the flags to store with the key
267 * @param exptime the expiry time for the key-value pair
268 * @param cas the cas id in the request
269 * @param result_cas the cas id of the new item
271 protocol_binary_response_status (*set
)(const void *cookie
, const void *key
, uint16_t keylen
,
272 const void *val
, uint32_t vallen
, uint32_t flags
,
273 uint32_t exptime
, uint64_t cas
, uint64_t *result_cas
);
276 * Get status information
278 * @param cookie id of the client receiving the command
279 * @param key the key to get status for (or NIL to request all status).
280 * Remember to insert the terminating packet if multiple
281 * packets should be returned.
282 * @param keylen the length of the key
283 * @param response_handler to send the result back to the client, but
284 * don't send reply on success!
287 protocol_binary_response_status (*stat
)(
288 const void *cookie
, const void *key
, uint16_t keylen
,
289 memcached_binary_protocol_stat_response_handler response_handler
);
292 * Get the version information
294 * @param cookie id of the client receiving the command
295 * @param response_handler to send the result back to the client, but
296 * don't send reply on success!
299 protocol_binary_response_status (*version
)(
300 const void *cookie
, memcached_binary_protocol_version_response_handler response_handler
);
301 } memcached_binary_protocol_callback_v1_st
;
304 * The version numbers for the different callback structures.
307 /** Version 0 is a lowlevel interface that tries to maximize your freedom */
308 MEMCACHED_PROTOCOL_HANDLER_V0
= 0,
310 * Version 1 abstracts more of the protocol details, and let you work at
313 MEMCACHED_PROTOCOL_HANDLER_V1
= 1
314 } memcached_protocol_interface_version_t
;
317 * Definition of the protocol callback structure.
321 * The interface version you provide callbacks for.
323 memcached_protocol_interface_version_t interface_version
;
326 * Callback fired just before the command will be executed.
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 (*pre_execute
)(const void *cookie
, protocol_binary_request_header
*header
);
335 * Callback fired just after the command was exected (please note
336 * that the data transfer back to the client is not finished at this
339 * @param cookie id of the client receiving the command
340 * @param header the command header as received on the wire. If you look
341 * at the content you <b>must</b> ensure that you don't
342 * try to access beyond the end of the message.
344 void (*post_execute
)(const void *cookie
, protocol_binary_request_header
*header
);
347 * Callback fired if no specialized callback is registered for this
348 * specific command code.
350 * @param cookie id of the client receiving the command
351 * @param header the command header as received on the wire. You <b>must</b>
352 * ensure that you don't try to access beyond the end of the
354 * @param response_handler The response handler to send data back.
356 protocol_binary_response_status (*unknown
)(
357 const void *cookie
, protocol_binary_request_header
*header
,
358 memcached_binary_protocol_raw_response_handler response_handler
);
361 * The different interface levels we support. A pointer is used so the
362 * size of the structure is fixed. You must ensure that the memory area
363 * passed as the pointer is valid as long as you use the protocol handler.
366 memcached_binary_protocol_callback_v0_st v0
;
369 * The first version of the callback struct containing all of the
370 * documented commands in the initial release of the binary protocol
371 * (aka. memcached 1.4.0).
373 memcached_binary_protocol_callback_v1_st v1
;
375 } memcached_binary_protocol_callback_st
;