2 This file is part of GNUnet.
3 Copyright (C) 2013 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Gabor X Toth
25 * Client manager; higher level client API with transmission queue
26 * and message handler registration.
28 * @defgroup client-manager Client manager library
29 * Higher level client-side communication with services.
31 * Provides a higher level client API
32 * with transmission queue and message handler registration.
35 #ifndef GNUNET_CLIENT_MANAGER_LIB_H
36 #define GNUNET_CLIENT_MANAGER_LIB_H
41 #if 0 /* keep Emacsens' auto-indent happy */
48 * Client manager connection handle.
50 struct GNUNET_CLIENT_MANAGER_Connection;
54 * Functions with this signature are called whenever a message is
58 * @param client identification of the client
59 * @param message the actual message
62 (*GNUNET_CLIENT_MANAGER_MessageCallback) (void *cls,
63 struct GNUNET_CLIENT_MANAGER_Connection *mgr,
64 const struct GNUNET_MessageHeader *msg);
68 * Message handler. Each struct specifies how to handle on particular
69 * type of message received.
71 struct GNUNET_CLIENT_MANAGER_MessageHandler
74 * Function to call for messages of @a type.
76 GNUNET_CLIENT_MANAGER_MessageCallback callback;
79 * Closure argument for @a callback.
84 * Type of the message this handler covers.
85 * Use 0 to handle loss of connection.
90 * Expected size of messages of this type. Use 0 to skip size check.
91 * If non-zero, messages of the given type will be discarded
92 * (and the connection closed) if they do not have the right size.
94 uint16_t expected_size;
97 * #GNUNET_NO for fixed-size messages.
98 * #GNUNET_YES if the message size can vary.
99 * In this case @a expected_size is treated as minimum size.
101 uint8_t is_variable_size;
106 * Connect to a service.
109 * Configuration to use.
110 * @param service_name
111 * Service name to connect to.
115 * @return Client manager connection handle.
117 struct GNUNET_CLIENT_MANAGER_Connection *
118 GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
119 const char *service_name,
121 GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
125 * Disconnect from the service.
128 * Client manager connection.
129 * @param transmit_queue
130 * Transmit pending messages in queue before disconnecting.
131 * @param disconnect_cb
132 * Function called after disconnected from the service.
134 * Closure for @a disconnect_cb.
137 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
139 GNUNET_ContinuationCallback disconnect_cb,
144 * Reschedule connect to the service using exponential back-off.
147 * Client manager connection.
150 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
154 * Add a message to the end of the transmission queue.
157 * Client manager connection.
159 * Message to transmit, should be allocated with GNUNET_malloc() or
160 * GNUNET_new(), as it is freed with GNUNET_free() after transmission.
163 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
164 struct GNUNET_MessageHeader *msg);
168 * Add a message to the beginning of the transmission queue.
171 * Client manager connection.
173 * Message to transmit, should be allocated with GNUNET_malloc() or
174 * GNUNET_new(), as it is freed with GNUNET_free() after transmission.
177 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
178 struct GNUNET_MessageHeader *msg);
182 * Drop all queued messages.
185 * Client manager connection.
188 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
192 * Obtain client connection handle.
195 * Client manager connection.
197 * @return Client connection handle.
199 struct GNUNET_CLIENT_Connection *
200 GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
204 * Return user context associated with the given client manager.
205 * Note: you should probably use the macro (call without the underscore).
208 * Client manager connection.
210 * Number of bytes in user context struct (for verification only).
213 GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
218 * Set user context to be associated with the given client manager.
219 * Note: you should probably use the macro (call without the underscore).
222 * Client manager connection.
226 * Number of bytes in user context struct (for verification only).
229 GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
235 * Return user context associated with the given client manager.
238 * Client manager connection.
240 * Type of context (for size verification).
242 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type) \
243 (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
247 * Set user context to be associated with the given client manager.
250 * Client manager connection.
252 * Pointer to user context.
254 #define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx) \
255 GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
259 * Get a unique operation ID to distinguish between asynchronous requests.
262 * Client manager connection.
264 * @return Operation ID to use.
267 GNUNET_CLIENT_MANAGER_op_get_next_id (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
271 * Find operation by ID.
274 * Client manager connection.
276 * Operation ID to look up.
277 * @param[out] result_cb
278 * If an operation was found, its result callback is returned here.
280 * If an operation was found, its closure is returned here.
282 * @return #GNUNET_YES if an operation was found,
283 * #GNUNET_NO if not found.
286 GNUNET_CLIENT_MANAGER_op_find (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
288 GNUNET_ResultCallback *result_cb,
293 * Add a new operation.
296 * Client manager connection.
298 * Function to call with the result of the operation.
300 * Closure for @a result_cb.
302 * @return ID of the new operation.
305 GNUNET_CLIENT_MANAGER_op_add (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
306 GNUNET_ResultCallback result_cb,
311 * Call the result callback and remove the operation.
314 * Client manager connection.
318 * Result of the operation.
320 * Data result of the operation.
324 * @return #GNUNET_YES if the operation was found and removed,
325 * #GNUNET_NO if the operation was not found.
328 GNUNET_CLIENT_MANAGER_op_result (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
329 uint64_t op_id, int64_t result_code,
330 const void *data, uint16_t data_size);
334 * Cancel an operation.
337 * Client manager connection.
341 * @return #GNUNET_YES if the operation was found and removed,
342 * #GNUNET_NO if the operation was not found.
345 GNUNET_CLIENT_MANAGER_op_cancel (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
349 #if 0 /* keep Emacsens' auto-indent happy */
356 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
359 /** @} */ /* end of group */