Merge in additional test for increment with namespace key.
[awesomized/libmemcached] / libmemcached / protocol / callback.h
1 /*
2 * Summary: Definition of the callback interface
3 *
4 * Copy: See Copyright for the status of this software.
5 *
6 * Author: Trond Norbye
7 */
8 #ifndef LIBMEMCACHEDPROTOCOL_CALLBACK_H
9 #define LIBMEMCACHEDPROTOCOL_CALLBACK_H
10
11 /**
12 * Callback to send data back from a successful GET/GETQ/GETK/GETKQ command
13 *
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
21 * if you don't care)
22 */
23 typedef protocol_binary_response_status
24 (*memcached_binary_protocol_get_response_handler)(const void *cookie,
25 const void *key,
26 uint16_t keylen,
27 const void *body,
28 uint32_t bodylen,
29 uint32_t flags,
30 uint64_t cas);
31 /**
32 * Callback to send data back from a STAT command
33 *
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
39 */
40 typedef protocol_binary_response_status
41 (*memcached_binary_protocol_stat_response_handler)(const void *cookie,
42 const void *key,
43 uint16_t keylen,
44 const void *body,
45 uint32_t bodylen);
46 /**
47 * Callback to send data back from a VERSION command
48 *
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
52 */
53 typedef protocol_binary_response_status
54 (*memcached_binary_protocol_version_response_handler)(const void *cookie,
55 const void *text,
56 uint32_t length);
57
58
59 /**
60 * In the low level interface you need to format the response
61 * packet yourself (giving you complete freedom :-)
62 *
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
66 *
67 */
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);
71
72 /**
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
80 */
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);
84
85 /**
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
88 * com code.
89 */
90 typedef struct {
91 memcached_binary_protocol_command_handler comcode[256];
92 } memcached_binary_protocol_callback_v0_st;
93
94
95 /**
96 * The first version of the callback struct containing all of the
97 * documented commands in the initial release of the binary protocol
98 * (aka. memcached 1.4.0).
99 *
100 * You might miss the Q commands (addq etc) but the response function
101 * knows how to deal with them so you don't need to worry about that :-)
102 */
103 typedef struct {
104 /**
105 * Add an item to the cache
106 * @param cookie id of the client receiving the command
107 * @param key the key to add
108 * @param len the length of the key
109 * @param val the value to store for the key (may be NIL)
110 * @param vallen the length of the data
111 * @param flags the flags to store with the key
112 * @param exptime the expiry time for the key-value pair
113 * @param cas the resulting cas for the add operation (if success)
114 */
115 protocol_binary_response_status (*add)(const void *cookie,
116 const void *key,
117 uint16_t keylen,
118 const void* val,
119 uint32_t vallen,
120 uint32_t flags,
121 uint32_t exptime,
122 uint64_t *cas);
123
124 /**
125 * Append data to an <b>existing</b> key-value pair.
126 *
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
134 *
135 */
136 protocol_binary_response_status (*append)(const void *cookie,
137 const void *key,
138 uint16_t keylen,
139 const void* val,
140 uint32_t vallen,
141 uint64_t cas,
142 uint64_t *result_cas);
143
144 /**
145 * Decrement the value for a key
146 *
147 * @param cookie id of the client receiving the command
148 * @param key the key to decrement the value for
149 * @param len the length of the key
150 * @param delta the amount to decrement
151 * @param initial initial value to store (if the key doesn't exist)
152 * @param expiration expiration time for the object (if the key doesn't exist)
153 * @param cas the CAS in the request
154 * @param result the result from the decrement
155 * @param result_cas the cas of the item
156 *
157 */
158 protocol_binary_response_status (*decrement)(const void *cookie,
159 const void *key,
160 uint16_t keylen,
161 uint64_t delta,
162 uint64_t initial,
163 uint32_t expiration,
164 uint64_t *result,
165 uint64_t *result_cas);
166
167 /**
168 * Delete an existing key
169 *
170 * @param cookie id of the client receiving the command
171 * @param key the key to delete
172 * @param len the length of the key
173 * @param cas the CAS in the request
174 */
175 protocol_binary_response_status (*delete)(const void *cookie,
176 const void *key,
177 uint16_t keylen,
178 uint64_t cas);
179
180
181 /**
182 * Flush the cache
183 *
184 * @param cookie id of the client receiving the command
185 * @param when when the cache should be flushed (0 == immediately)
186 */
187 protocol_binary_response_status (*flush)(const void *cookie,
188 uint32_t when);
189
190
191
192 /**
193 * Get a key-value pair
194 *
195 * @param cookie id of the client receiving the command
196 * @param key the key to get
197 * @param len the length of the key
198 * @param response_handler to send the result back to the client
199 */
200 protocol_binary_response_status (*get)(const void *cookie,
201 const void *key,
202 uint16_t keylen,
203 memcached_binary_protocol_get_response_handler response_handler);
204
205 /**
206 * Increment the value for a key
207 *
208 * @param cookie id of the client receiving the command
209 * @param key the key to increment the value on
210 * @param len the length of the key
211 * @param delta the amount to increment
212 * @param initial initial value to store (if the key doesn't exist)
213 * @param expiration expiration time for the object (if the key doesn't exist)
214 * @param cas the CAS in the request
215 * @param result the result from the decrement
216 * @param result_cas the cas of the item
217 *
218 */
219 protocol_binary_response_status (*increment)(const void *cookie,
220 const void *key,
221 uint16_t keylen,
222 uint64_t delta,
223 uint64_t initial,
224 uint32_t expiration,
225 uint64_t *result,
226 uint64_t *result_cas);
227
228 /**
229 * The noop command was received. This is just a notification callback (the
230 * response is automatically created).
231 *
232 * @param cookie id of the client receiving the command
233 */
234 protocol_binary_response_status (*noop)(const void *cookie);
235
236 /**
237 * Prepend data to an <b>existing</b> key-value pair.
238 *
239 * @param cookie id of the client receiving the command
240 * @param key the key to prepend data to
241 * @param len the length of the key
242 * @param val the value to prepend to the value
243 * @param vallen the length of the data
244 * @param cas the CAS in the request
245 * @param result-cas the cas id of the item
246 *
247 */
248 protocol_binary_response_status (*prepend)(const void *cookie,
249 const void *key,
250 uint16_t keylen,
251 const void* val,
252 uint32_t vallen,
253 uint64_t cas,
254 uint64_t *result_cas);
255
256 /**
257 * The quit command was received. This is just a notification callback (the
258 * response is automatically created).
259 *
260 * @param cookie id of the client receiving the command
261 */
262 protocol_binary_response_status (*quit)(const void *cookie);
263
264
265 /**
266 * Replace an <b>existing</b> item to the cache
267 *
268 * @param cookie id of the client receiving the command
269 * @param key the key to replace the content for
270 * @param len the length of the key
271 * @param val the value to store for the key (may be NIL)
272 * @param vallen the length of the data
273 * @param flags the flags to store with the key
274 * @param exptime the expiry time for the key-value pair
275 * @param cas the cas id in the request
276 * @param result_cas the cas id of the item
277 */
278 protocol_binary_response_status (*replace)(const void *cookie,
279 const void *key,
280 uint16_t keylen,
281 const void* val,
282 uint32_t vallen,
283 uint32_t flags,
284 uint32_t exptime,
285 uint64_t cas,
286 uint64_t *result_cas);
287
288
289 /**
290 * Set a key-value pair in the cache
291 *
292 * @param cookie id of the client receiving the command
293 * @param key the key to insert
294 * @param len the length of the key
295 * @param val the value to store for the key (may be NIL)
296 * @param vallen the length of the data
297 * @param flags the flags to store with the key
298 * @param exptime the expiry time for the key-value pair
299 * @param cas the cas id in the request
300 * @param result_cas the cas id of the new item
301 */
302 protocol_binary_response_status (*set)(const void *cookie,
303 const void *key,
304 uint16_t keylen,
305 const void* val,
306 uint32_t vallen,
307 uint32_t flags,
308 uint32_t exptime,
309 uint64_t cas,
310 uint64_t *result_cas);
311
312 /**
313 * Get status information
314 *
315 * @param cookie id of the client receiving the command
316 * @param key the key to get status for (or NIL to request all status).
317 * Remember to insert the terminating packet if multiple
318 * packets should be returned.
319 * @param keylen the length of the key
320 * @param response_handler to send the result back to the client, but
321 * don't send reply on success!
322 *
323 */
324 protocol_binary_response_status (*stat)(const void *cookie,
325 const void *key,
326 uint16_t keylen,
327 memcached_binary_protocol_stat_response_handler response_handler);
328
329 /**
330 * Get the version information
331 *
332 * @param cookie id of the client receiving the command
333 * @param response_handler to send the result back to the client, but
334 * don't send reply on success!
335 *
336 */
337 protocol_binary_response_status (*version)(const void *cookie,
338 memcached_binary_protocol_version_response_handler response_handler);
339 } memcached_binary_protocol_callback_v1_st;
340
341
342 /**
343 * The version numbers for the different callback structures.
344 */
345 typedef enum {
346 /** Version 0 is a lowlevel interface that tries to maximize your freedom */
347 MEMCACHED_PROTOCOL_HANDLER_V0= 0,
348 /**
349 * Version 1 abstracts more of the protocol details, and let you work at
350 * a logical level
351 */
352 MEMCACHED_PROTOCOL_HANDLER_V1= 1,
353 } memcached_protocol_interface_version_t;
354
355 /**
356 * Definition of the protocol callback structure.
357 */
358 typedef struct {
359 /**
360 * The interface version you provide callbacks for.
361 */
362 memcached_protocol_interface_version_t interface_version;
363
364 /**
365 * Callback fired just before the command will be executed.
366 *
367 * @param cookie id of the client receiving the command
368 * @param header the command header as received on the wire. If you look
369 * at the content you <b>must</b> ensure that you don't
370 * try to access beyond the end of the message.
371 */
372 void (*pre_execute)(const void *cookie,
373 protocol_binary_request_header *header);
374 /**
375 * Callback fired just after the command was exected (please note
376 * that the data transfer back to the client is not finished at this
377 * time).
378 *
379 * @param cookie id of the client receiving the command
380 * @param header the command header as received on the wire. If you look
381 * at the content you <b>must</b> ensure that you don't
382 * try to access beyond the end of the message.
383 */
384 void (*post_execute)(const void *cookie,
385 protocol_binary_request_header *header);
386
387 /**
388 * Callback fired if no specialized callback is registered for this
389 * specific command code.
390 *
391 * @param cookie id of the client receiving the command
392 * @param header the command header as received on the wire. You <b>must</b>
393 * ensure that you don't try to access beyond the end of the
394 * message.
395 * @param response_handler The response handler to send data back.
396 */
397 protocol_binary_response_status (*unknown)(const void *cookie,
398 protocol_binary_request_header *header,
399 memcached_binary_protocol_raw_response_handler response_handler);
400
401 /**
402 * The different interface levels we support. A pointer is used so the
403 * size of the structure is fixed. You must ensure that the memory area
404 * passed as the pointer is valid as long as you use the protocol handler.
405 */
406 union {
407 memcached_binary_protocol_callback_v0_st v0;
408
409 /**
410 * The first version of the callback struct containing all of the
411 * documented commands in the initial release of the binary protocol
412 * (aka. memcached 1.4.0).
413 */
414 memcached_binary_protocol_callback_v1_st v1;
415 } interface;
416 } memcached_binary_protocol_callback_st;
417
418 #endif