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