2 * Summary: Definition of the callback interface
4 * Copy: See Copyright for the status of this software.
8 #ifndef LIBMEMCACHEDPROTOCOL_CALLBACK_H
9 #define LIBMEMCACHEDPROTOCOL_CALLBACK_H
12 * Callback to send data back from a successful GET/GETQ/GETK/GETKQ command
14 * @param cookie Just pass along the cookie supplied in the callback
15 * @param key What to insert as key in the reply
16 * @param keylen The length of the key
17 * @param body What to store in the body of the package
18 * @param bodylen The number of bytes of the body
19 * @param flags The flags stored with the item
20 * @param cas The CAS value to insert into the response (should be 0
23 typedef protocol_binary_response_status
24 (*memcached_binary_protocol_get_response_handler
)(const void *cookie
,
32 * Callback to send data back from a STAT command
34 * @param cookie Just pass along the cookie supplied in the callback
35 * @param key What to insert as key in the reply
36 * @param keylen The length of the key
37 * @param body What to store in the body of the package
38 * @param bodylen The number of bytes of the body
40 typedef protocol_binary_response_status
41 (*memcached_binary_protocol_stat_response_handler
)(const void *cookie
,
47 * Callback to send data back from a VERSION command
49 * @param cookie Just pass along the cookie supplied in the callback
50 * @param text The version string
51 * @param length The number of bytes in the version string
53 typedef protocol_binary_response_status
54 (*memcached_binary_protocol_version_response_handler
)(const void *cookie
,
60 * In the low level interface you need to format the response
61 * packet yourself (giving you complete freedom :-)
63 * @param cookie Just pass along the cookie supplied in the callback
64 * @param request Pointer to the request packet you are sending a reply to
65 * @param response Pointer to the response packet to send
68 typedef protocol_binary_response_status (*memcached_binary_protocol_raw_response_handler
)(const void *cookie
,
69 protocol_binary_request_header
*request
,
70 protocol_binary_response_header
*response
);
73 * In the low lever interface you have to do most of the work by
74 * yourself, but it also gives you a lot of freedom :-)
75 * @param cookie identification for this connection, just pass it along to
76 * the response handler
77 * @param header the command received over the wire. Never try to access
78 * <u>anything</u> outside the command.
79 * @param resonse_handler call this function to send data back to the client
81 typedef protocol_binary_response_status (*memcached_binary_protocol_command_handler
)(const void *cookie
,
82 protocol_binary_request_header
*header
,
83 memcached_binary_protocol_raw_response_handler response_handler
);
86 * The raw interface to the packets is implemented in version 0. It contains
87 * just an array with command handlers. The inxed in the array is the
90 struct memcached_binary_protocol_callback_v0_st
{
91 memcached_binary_protocol_command_handler comcode
[256];
95 * The first version of the callback struct containing all of the
96 * documented commands in the initial release of the binary protocol
97 * (aka. memcached 1.4.0).
99 * You might miss the Q commands (addq etc) but the response function
100 * knows how to deal with them so you don't need to worry about that :-)
102 struct memcached_binary_protocol_callback_v1_st
{
104 * Add an item to the cache
105 * @param cookie id of the client receiving the command
106 * @param key the key to add
107 * @param len the length of the key
108 * @param val the value to store for the key (may be NIL)
109 * @param vallen the length of the data
110 * @param flags the flags to store with the key
111 * @param exptime the expiry time for the key-value pair
112 * @param cas the resulting cas for the add operation (if success)
114 protocol_binary_response_status (*add
)(const void *cookie
,
124 * Append data to an <b>existing</b> key-value pair.
126 * @param cookie id of the client receiving the command
127 * @param key the key to add data to
128 * @param len the length of the key
129 * @param val the value to append to the value
130 * @param vallen the length of the data
131 * @param cas the CAS in the request
132 * @param result_cas the resulting cas for the append operation
135 protocol_binary_response_status (*append
)(const void *cookie
,
141 uint64_t *result_cas
);
144 * Decrement the value for a key
146 * @param cookie id of the client receiving the command
147 * @param key the key to decrement the value for
148 * @param len the length of the key
149 * @param delta the amount to decrement
150 * @param initial initial value to store (if the key doesn't exist)
151 * @param expiration expiration time for the object (if the key doesn't exist)
152 * @param cas the CAS in the request
153 * @param result the result from the decrement
154 * @param result_cas the cas of the item
157 protocol_binary_response_status (*decrement
)(const void *cookie
,
164 uint64_t *result_cas
);
167 * Delete an existing key
169 * @param cookie id of the client receiving the command
170 * @param key the key to delete
171 * @param len the length of the key
172 * @param cas the CAS in the request
174 protocol_binary_response_status (*delete)(const void *cookie
,
183 * @param cookie id of the client receiving the command
184 * @param when when the cache should be flushed (0 == immediately)
186 protocol_binary_response_status (*flush
)(const void *cookie
,
192 * Get a key-value pair
194 * @param cookie id of the client receiving the command
195 * @param key the key to get
196 * @param len the length of the key
197 * @param response_handler to send the result back to the client
199 protocol_binary_response_status (*get
)(const void *cookie
,
202 memcached_binary_protocol_get_response_handler response_handler
);
205 * Increment the value for a key
207 * @param cookie id of the client receiving the command
208 * @param key the key to increment the value on
209 * @param len the length of the key
210 * @param delta the amount to increment
211 * @param initial initial value to store (if the key doesn't exist)
212 * @param expiration expiration time for the object (if the key doesn't exist)
213 * @param cas the CAS in the request
214 * @param result the result from the decrement
215 * @param result_cas the cas of the item
218 protocol_binary_response_status (*increment
)(const void *cookie
,
225 uint64_t *result_cas
);
228 * The noop command was received. This is just a notification callback (the
229 * response is automatically created).
231 * @param cookie id of the client receiving the command
233 protocol_binary_response_status (*noop
)(const void *cookie
);
236 * Prepend data to an <b>existing</b> key-value pair.
238 * @param cookie id of the client receiving the command
239 * @param key the key to prepend data to
240 * @param len the length of the key
241 * @param val the value to prepend to the value
242 * @param vallen the length of the data
243 * @param cas the CAS in the request
244 * @param result-cas the cas id of the item
247 protocol_binary_response_status (*prepend
)(const void *cookie
,
253 uint64_t *result_cas
);
256 * The quit command was received. This is just a notification callback (the
257 * response is automatically created).
259 * @param cookie id of the client receiving the command
261 protocol_binary_response_status (*quit
)(const void *cookie
);
265 * Replace an <b>existing</b> item to the cache
267 * @param cookie id of the client receiving the command
268 * @param key the key to replace the content for
269 * @param len the length of the key
270 * @param val the value to store for the key (may be NIL)
271 * @param vallen the length of the data
272 * @param flags the flags to store with the key
273 * @param exptime the expiry time for the key-value pair
274 * @param cas the cas id in the request
275 * @param result_cas the cas id of the item
277 protocol_binary_response_status (*replace
)(const void *cookie
,
285 uint64_t *result_cas
);
289 * Set a key-value pair in the cache
291 * @param cookie id of the client receiving the command
292 * @param key the key to insert
293 * @param len the length of the key
294 * @param val the value to store for the key (may be NIL)
295 * @param vallen the length of the data
296 * @param flags the flags to store with the key
297 * @param exptime the expiry time for the key-value pair
298 * @param cas the cas id in the request
299 * @param result_cas the cas id of the new item
301 protocol_binary_response_status (*set
)(const void *cookie
,
309 uint64_t *result_cas
);
312 * Get status information
314 * @param cookie id of the client receiving the command
315 * @param key the key to get status for (or NIL to request all status).
316 * Remember to insert the terminating packet if multiple
317 * packets should be returned.
318 * @param keylen the length of the key
319 * @param response_handler to send the result back to the client, but
320 * don't send reply on success!
323 protocol_binary_response_status (*stat
)(const void *cookie
,
326 memcached_binary_protocol_stat_response_handler response_handler
);
329 * Get the version information
331 * @param cookie id of the client receiving the command
332 * @param response_handler to send the result back to the client, but
333 * don't send reply on success!
336 protocol_binary_response_status (*version
)(const void *cookie
,
337 memcached_binary_protocol_version_response_handler response_handler
);
343 struct memcached_binary_protocol_callback_st
{
345 * The interface version used (set to 0 if you don't have any specialized
348 uint64_t interface_version
;
351 * Callback fired just before the command will be executed.
353 * @param cookie id of the client receiving the command
354 * @param header the command header as received on the wire. If you look
355 * at the content you <b>must</b> ensure that you don't
356 * try to access beyond the end of the message.
358 void (*pre_execute
)(const void *cookie
,
359 protocol_binary_request_header
*header
);
361 * Callback fired just after the command was exected (please note
362 * that the data transfer back to the client is not finished at this
365 * @param cookie id of the client receiving the command
366 * @param header the command header as received on the wire. If you look
367 * at the content you <b>must</b> ensure that you don't
368 * try to access beyond the end of the message.
370 void (*post_execute
)(const void *cookie
,
371 protocol_binary_request_header
*header
);
374 * Callback fired if no specialized callback is registered for this
375 * specific command code.
377 * @param cookie id of the client receiving the command
378 * @param header the command header as received on the wire. You <b>must</b>
379 * ensure that you don't try to access beyond the end of the
381 * @param response_handler The response handler to send data back.
383 protocol_binary_response_status (*unknown
)(const void *cookie
,
384 protocol_binary_request_header
*header
,
385 memcached_binary_protocol_raw_response_handler response_handler
);
388 * The different interface levels we support. A pointer is used so the
389 * size of the structure is fixed. You must ensure that the memory area
390 * passed as the pointer is valid as long as you use the protocol handler.
393 struct memcached_binary_protocol_callback_v0_st v0
;
396 * The first version of the callback struct containing all of the
397 * documented commands in the initial release of the binary protocol
398 * (aka. memcached 1.4.0).
400 struct memcached_binary_protocol_callback_v1_st v1
;