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