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