2 +--------------------------------------------------------------------+
3 | libmemcached-awesome - C/C++ Client Library for memcached |
4 +--------------------------------------------------------------------+
5 | Redistribution and use in source and binary forms, with or without |
6 | modification, are permitted under the terms of the BSD license. |
7 | You should have received a copy of the license in a bundled file |
8 | named LICENSE; in case you did not receive a copy you can review |
9 | the terms online at: https://opensource.org/licenses/BSD-3-Clause |
10 +--------------------------------------------------------------------+
11 | Copyright (c) 2006-2014 Brian Aker https://datadifferential.com/ |
12 | Copyright (c) 2020-2021 Michael Wallner https://awesome.co/ |
13 +--------------------------------------------------------------------+
18 #include "libmemcachedprotocol-0.0/configure.h"
19 #include <sys/types.h>
21 typedef long int ssize_t
;
32 #include "libmemcached-1.0/visibility.h"
33 #include "libmemcached-1.0/platform.h"
34 #include "libmemcachedprotocol-0.0/binary.h"
35 #include "libmemcachedprotocol-0.0/callback.h"
37 /* Forward declarations */
39 * You should only access memcached_protocol_st from one thread!,
40 * and never assume anything about the internal layout / sizes of the
43 typedef struct memcached_protocol_st memcached_protocol_st
;
44 typedef struct memcached_protocol_client_st memcached_protocol_client_st
;
51 * Function the protocol handler should call to receive data.
52 * This function should behave exactly like read(2)
54 * @param cookie a cookie used to represent a given client
55 * @param fd the filedescriptor associated with the client
56 * @param buf destination buffer
57 * @param nbuf number of bytes to receive
58 * @return the number of bytes copied into buf
59 * or -1 upon error (errno should contain more information)
61 typedef ssize_t (*memcached_protocol_recv_func
)(const void *cookie
, memcached_socket_t fd
,
62 void *buf
, size_t nbuf
);
65 * Function the protocol handler should call to send data.
66 * This function should behave exactly like write(2)
68 * @param cookie a cookie used to represent a given client
69 * @param fd the filedescriptor associated with the client
70 * @param buf the source buffer
71 * @param nbuf number of bytes to send
72 * @return the number of bytes sent
73 * or -1 upon error (errno should contain more information)
75 typedef ssize_t (*memcached_protocol_send_func
)(const void *cookie
, memcached_socket_t fd
,
76 const void *buf
, size_t nbuf
);
79 * Create an instance of the protocol handler
81 * @return NULL if allocation of an instance fails
84 memcached_protocol_st
*memcached_protocol_create_instance(void);
87 * Get the callbacks associated with a protocol handler instance
88 * @return the callbacks currently used
91 memcached_binary_protocol_callback_st
*
92 memcached_binary_protocol_get_callbacks(memcached_protocol_st
*instance
);
95 * Set the callbacks to be used by the given protocol handler instance
96 * @param instance the instance to update
97 * @param callback the callbacks to use
100 void memcached_binary_protocol_set_callbacks(memcached_protocol_st
*instance
,
101 memcached_binary_protocol_callback_st
*callback
);
104 * Should the library inspect the packages being sent and received and verify
105 * that they are according to the specification? If it encounters an invalid
106 * packet, it will return an EINVAL packet.
108 * @param instance the instance to update
109 * @param enable true if you want the library to check packages, false otherwise
112 void memcached_binary_protocol_set_pedantic(memcached_protocol_st
*instance
, bool enable
);
115 * Is the library inpecting each package?
116 * @param instance the instance to check
117 * @return true it the library is inspecting each package, false otherwise
120 bool memcached_binary_protocol_get_pedantic(memcached_protocol_st
*instance
);
123 * Destroy an instance of the protocol handler
125 * @param instance The instance to destroy
128 void memcached_protocol_destroy_instance(memcached_protocol_st
*instance
);
131 * Set the IO functions used by the instance to send and receive data. The
132 * functions should behave like recv(3socket) and send(3socket).
134 * @param instance the instance to specify the IO functions for
135 * @param recv the function to call for reciving data
136 * @param send the function to call for sending data
139 void memached_protocol_set_io_functions(memcached_protocol_st
*instance
,
140 memcached_protocol_recv_func recv
,
141 memcached_protocol_send_func send
);
144 * Create a new client instance and associate it with a socket
145 * @param instance the protocol instance to bind the client to
146 * @param sock the client socket
147 * @return NULL if allocation fails, otherwise an instance
150 memcached_protocol_client_st
*memcached_protocol_create_client(memcached_protocol_st
*instance
,
151 memcached_socket_t sock
);
154 * Destroy a client handle.
155 * The caller needs to close the socket accociated with the client
156 * <b>before</b> calling this function. This function invalidates the
157 * client memory area.
159 * @param client the client to destroy
162 void memcached_protocol_client_destroy(memcached_protocol_client_st
*client
);
165 void memcached_protocol_client_set_verbose(struct memcached_protocol_client_st
*client
, bool arg
);
168 * Error event means that the client encountered an error with the
169 * connection so you should shut it down
171 #define MEMCACHED_PROTOCOL_ERROR_EVENT 1
173 * Please notify when there is more data available to read
175 #define MEMCACHED_PROTOCOL_READ_EVENT 2
177 * Please notify when it is possible to send more data
179 #define MEMCACHED_PROTOCOL_WRITE_EVENT 4
181 * Backed paused the execution for this client
183 #define MEMCACHED_PROTOCOL_PAUSE_EVENT 8
186 * The different events the client is interested in. This is a bitmask of
187 * the constants defined above.
189 typedef uint32_t memcached_protocol_event_t
;
192 * Let the client do some work. This might involve reading / sending data
193 * to/from the client, or perform callbacks to execute a command.
194 * @param client the client structure to work on
195 * @return The next event the protocol handler will be notified for
198 memcached_protocol_event_t
memcached_protocol_client_work(memcached_protocol_client_st
*client
);
201 * Get the socket attached to a client handle
202 * @param client the client to query
203 * @return the socket handle
206 memcached_socket_t
memcached_protocol_client_get_socket(memcached_protocol_client_st
*client
);
209 * Get the error id socket attached to a client handle
210 * @param client the client to query for an error code
211 * @return the OS error code from the client
214 int memcached_protocol_client_get_errno(memcached_protocol_client_st
*client
);
217 * Get a raw response handler for the given cookie
218 * @param cookie the cookie passed along into the callback
219 * @return the raw reponse handler you may use if you find
220 * the generic callback too limiting
223 memcached_binary_protocol_raw_response_handler
224 memcached_binary_protocol_get_raw_response_handler(const void *cookie
);