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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_client_manager_lib.h
23 * @brief Client manager; higher level client API with transmission queue
24 * and message handler registration.
25 * @author Gabor X Toth
26 * @defgroup client_manager Higher level client-side communication with services.
29 #ifndef GNUNET_CLIENT_MANAGER_LIB_H
30 #define GNUNET_CLIENT_MANAGER_LIB_H
35 #if 0 /* keep Emacsens' auto-indent happy */
42 * Client manager connection handle.
44 struct GNUNET_CLIENT_MANAGER_Connection;
48 * Functions with this signature are called whenever a message is
52 * @param client identification of the client
53 * @param message the actual message
56 (*GNUNET_CLIENT_MANAGER_MessageCallback) (void *cls,
57 struct GNUNET_CLIENT_MANAGER_Connection *mgr,
58 const struct GNUNET_MessageHeader *msg);
62 * Message handler. Each struct specifies how to handle on particular
63 * type of message received.
65 struct GNUNET_CLIENT_MANAGER_MessageHandler
68 * Function to call for messages of @a type.
70 GNUNET_CLIENT_MANAGER_MessageCallback callback;
73 * Closure argument for @a callback.
78 * Type of the message this handler covers.
79 * Use 0 to handle loss of connection.
84 * Expected size of messages of this type. Use 0 to skip size check.
85 * If non-zero, messages of the given type will be discarded
86 * (and the connection closed) if they do not have the right size.
88 uint16_t expected_size;
91 * #GNUNET_NO for fixed-size messages.
92 * #GNUNET_YES if the message size can vary.
93 * In this case @a expected_size is treated as minimum size.
95 uint8_t is_variable_size;
100 * Connect to a service.
103 * Configuration to use.
104 * @param service_name
105 * Service name to connect to.
109 * @return Client manager connection handle.
111 struct GNUNET_CLIENT_MANAGER_Connection *
112 GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
113 const char *service_name,
115 GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
119 * Disconnect from the service.
122 * Client manager connection.
123 * @param transmit_queue
124 * Transmit pending messages in queue before disconnecting.
125 * @param disconnect_cb
126 * Function called after disconnected from the service.
128 * Closure for @a disconnect_cb.
131 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
133 GNUNET_ContinuationCallback disconnect_cb,
138 * Reschedule connect to the service using exponential back-off.
141 * Client manager connection.
144 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
148 * Add a message to the end of the transmission queue.
151 * Client manager connection.
153 * Message to transmit, should be allocated with GNUNET_malloc() or
154 * GNUNET_new(), as it is freed with GNUNET_free() after transmission.
157 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
158 struct GNUNET_MessageHeader *msg);
162 * Add a message to the beginning of the transmission queue.
165 * Client manager connection.
167 * Message to transmit, should be allocated with GNUNET_malloc() or
168 * GNUNET_new(), as it is freed with GNUNET_free() after transmission.
171 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
172 struct GNUNET_MessageHeader *msg);
176 * Drop all queued messages.
179 * Client manager connection.
182 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
186 * Obtain client connection handle.
189 * Client manager connection.
191 * @return Client connection handle.
193 struct GNUNET_CLIENT_Connection *
194 GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
198 * Return user context associated with the given client manager.
199 * Note: you should probably use the macro (call without the underscore).
202 * Client manager connection.
204 * Number of bytes in user context struct (for verification only).
207 GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
212 * Set user context to be associated with the given client manager.
213 * Note: you should probably use the macro (call without the underscore).
216 * Client manager connection.
218 * Number of bytes in user context struct (for verification only).
221 GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
227 * Return user context associated with the given client manager.
230 * Client manager connection.
234 * Number of bytes in user context struct (for verification only).
236 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type) \
237 (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
241 * Set user context to be associated with the given client manager.
244 * Client manager connection.
246 * Pointer to user context.
248 #define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx) \
249 GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
252 #if 0 /* keep Emacsens' auto-indent happy */
259 /** @} */ /* end of group client_manager */
261 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
263 /* end of gnunet_client_manager_lib.h */