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