Partial patch on pass through to fix issues with trigger writers not
[m6w6/libmemcached] / libmemcached / protocol_handler.h
1 /* LibMemcached
2 * Copyright (C) 2006-2009 Brian Aker
3 * All rights reserved.
4 *
5 * Use and distribution licensed under the BSD license. See
6 * the COPYING file in the parent directory for full text.
7 *
8 * Summary: Definition of the callback interface to the protocol handler
9 *
10 * Author: Trond Norbye
11 *
12 */
13
14 #ifndef MEMCACHED_PROTOCOL_H
15 #define MEMCACHED_PROTOCOL_H
16
17 #include <sys/types.h>
18 #if !defined(__cplusplus)
19 # include <stdbool.h>
20 #endif
21
22 #include <libmemcached/memcached/protocol_binary.h>
23 #include <libmemcached/visibility.h>
24 #include <libmemcached/protocol/callback.h>
25
26 /* Forward declarations */
27 /*
28 * You should only access memcached_protocol_st from one thread!,
29 * and never assume anything about the internal layout / sizes of the
30 * structures.
31 */
32 typedef struct memcached_protocol_st memcached_protocol_st;
33 typedef struct memcached_protocol_client_st memcached_protocol_client_st;
34
35 /**
36 * Function the protocol handler should call to receive data.
37 * This function should behave exactly like read(2)
38 *
39 * @param cookie a cookie used to represent a given client
40 * @param fd the filedescriptor associated with the client
41 * @param buf destination buffer
42 * @param nbuf number of bytes to receive
43 * @return the number of bytes copied into buf
44 * or -1 upon error (errno should contain more information)
45 */
46 typedef ssize_t (*memcached_protocol_recv_func)(const void *cookie,
47 int fd,
48 void *buf,
49 size_t nbuf);
50
51 /**
52 * Function the protocol handler should call to send data.
53 * This function should behave exactly like write(2)
54 *
55 * @param cookie a cookie used to represent a given client
56 * @param fd the filedescriptor associated with the client
57 * @param buf the source buffer
58 * @param nbuf number of bytes to send
59 * @return the number of bytes sent
60 * or -1 upon error (errno should contain more information)
61 */
62 typedef ssize_t (*memcached_protocol_send_func)(const void *cookie,
63 int fd,
64 const void *buf,
65 size_t nbuf);
66
67 /**
68 * Create an instance of the protocol handler
69 *
70 * @return NULL if allocation of an instance fails
71 */
72 LIBMEMCACHED_API
73 memcached_protocol_st *memcached_protocol_create_instance(void);
74
75 /**
76 * Get the callbacks associated with a protocol handler instance
77 * @return the callbacks currently used
78 */
79 LIBMEMCACHED_API
80 memcached_binary_protocol_callback_st *memcached_binary_protocol_get_callbacks(memcached_protocol_st *instance);
81
82 /**
83 * Set the callbacks to be used by the given protocol handler instance
84 * @param instance the instance to update
85 * @param callback the callbacks to use
86 */
87 LIBMEMCACHED_API
88 void memcached_binary_protocol_set_callbacks(memcached_protocol_st *instance, memcached_binary_protocol_callback_st *callback);
89
90 /**
91 * Should the library inspect the packages being sent and received and verify
92 * that they are according to the specification? If it encounters an invalid
93 * packet, it will return an EINVAL packet.
94 *
95 * @param instance the instance to update
96 * @param enable true if you want the library to check packages, false otherwise
97 */
98 LIBMEMCACHED_API
99 void memcached_binary_protocol_set_pedantic(memcached_protocol_st *instance, bool enable);
100
101 /**
102 * Is the library inpecting each package?
103 * @param instance the instance to check
104 * @return true it the library is inspecting each package, false otherwise
105 */
106 LIBMEMCACHED_API
107 bool memcached_binary_protocol_get_pedantic(memcached_protocol_st *instance);
108
109 /**
110 * Destroy an instance of the protocol handler
111 *
112 * @param instance The instance to destroy
113 */
114 LIBMEMCACHED_API
115 void memcached_protocol_destroy_instance(memcached_protocol_st *instance);
116
117 /**
118 * Set the IO functions used by the instance to send and receive data. The
119 * functions should behave like recv(3socket) and send(3socket).
120 *
121 * @param instance the instance to specify the IO functions for
122 * @param recv the function to call for reciving data
123 * @param send the function to call for sending data
124 */
125 LIBMEMCACHED_API
126 void memached_protocol_set_io_functions(memcached_protocol_st *instance,
127 memcached_protocol_recv_func recv,
128 memcached_protocol_send_func send);
129
130
131 /**
132 * Create a new client instance and associate it with a socket
133 * @param instance the protocol instance to bind the client to
134 * @param sock the client socket
135 * @return NULL if allocation fails, otherwise an instance
136 */
137 LIBMEMCACHED_API
138 memcached_protocol_client_st *memcached_protocol_create_client(memcached_protocol_st *instance, int sock);
139
140 /**
141 * Destroy a client handle.
142 * The caller needs to close the socket accociated with the client
143 * <b>before</b> calling this function. This function invalidates the
144 * client memory area.
145 *
146 * @param client the client to destroy
147 */
148 LIBMEMCACHED_API
149 void memcached_protocol_client_destroy(memcached_protocol_client_st *client);
150
151 /**
152 * Error event means that the client encountered an error with the
153 * connection so you should shut it down
154 */
155 #define MEMCACHED_PROTOCOL_ERROR_EVENT 1
156 /**
157 * Please notify when there is more data available to read
158 */
159 #define MEMCACHED_PROTOCOL_READ_EVENT 2
160 /**
161 * Please notify when it is possible to send more data
162 */
163 #define MEMCACHED_PROTOCOL_WRITE_EVENT 4
164 /**
165 * Backed paused the execution for this client
166 */
167 #define MEMCACHED_PROTOCOL_PAUSE_EVENT 8
168
169 /**
170 * The different events the client is interested in. This is a bitmask of
171 * the constants defined above.
172 */
173 typedef uint32_t memcached_protocol_event_t;
174
175 /**
176 * Let the client do some work. This might involve reading / sending data
177 * to/from the client, or perform callbacks to execute a command.
178 * @param client the client structure to work on
179 * @return The next event the protocol handler will be notified for
180 */
181 LIBMEMCACHED_API
182 memcached_protocol_event_t memcached_protocol_client_work(memcached_protocol_client_st *client);
183
184 /**
185 * Get the socket attached to a client handle
186 * @param client the client to query
187 * @return the socket handle
188 */
189 LIBMEMCACHED_API
190 int memcached_protocol_client_get_socket(memcached_protocol_client_st *client);
191
192 /**
193 * Get the error id socket attached to a client handle
194 * @param client the client to query for an error code
195 * @return the OS error code from the client
196 */
197 LIBMEMCACHED_API
198 int memcached_protocol_client_get_errno(memcached_protocol_client_st *client);
199
200 /**
201 * Get a raw response handler for the given cookie
202 * @param cookie the cookie passed along into the callback
203 * @return the raw reponse handler you may use if you find
204 * the generic callback too limiting
205 */
206 LIBMEMCACHED_API
207 memcached_binary_protocol_raw_response_handler memcached_binary_protocol_get_raw_response_handler(const void *cookie);
208 #endif