2 This file is part of GNUnet.
3 (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.
102 * @param cfg Configuration to use.
103 * @param service_name Service name to connect to.
104 * @param connect_msg FIXME
105 * @param connection_lost_cb x
108 * @return Client manager connection handle.
110 struct GNUNET_CLIENT_MANAGER_Connection *
111 GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
112 const char *service_name,
114 GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
118 * Disconnect from the service.
120 * @param mgr Client manager connection.
121 * @param transmit_queue Transmit pending messages in queue before disconnecting.
124 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
129 * Reschedule connect to the service using exponential back-off.
131 * @param mgr Client manager connection.
134 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
138 * Add a message to the end of the transmission queue.
140 * @param mgr Client manager connection.
141 * @param msg Message to transmit. It is free()'d after transmission.
144 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
145 struct GNUNET_MessageHeader *msg);
149 * Add a message to the beginning of the transmission queue.
151 * @param mgr Client manager connection.
152 * @param msg Message to transmit. It is free()'d after transmission.
155 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
156 struct GNUNET_MessageHeader *msg);
160 * Drop all queued messages.
162 * @param mgr Client manager connection.
165 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
169 * Obtain client connection handle.
171 * @param mgr Client manager connection handle.
173 * @return Client connection handle.
175 struct GNUNET_CLIENT_Connection *
176 GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
180 * Return user context associated with the given client manager.
181 * Note: you should probably use the macro (call without the underscore).
183 * @param mgr Client manager connection.
184 * @param size Number of bytes in user context struct (for verification only).
185 * @return User context.
188 GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
193 * Set user context to be associated with the given client manager.
194 * Note: you should probably use the macro (call without the underscore).
196 * @param mgr Client manager connection.
197 * @param ctx User context.
198 * @param size Number of bytes in user context struct (for verification only).
201 GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
207 * Return user context associated with the given client manager.
209 * @param mgr Client manager connection.
210 * @param type Expected return type (i.e. 'struct Foo')
211 * @return Pointer to user context of type 'type *'.
213 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type) \
214 (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
218 * Set user context to be associated with the given client manager.
220 * @param mgr Client manager connection.
221 * @param ctx Pointer to user context.
223 #define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx) \
224 GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
227 #if 0 /* keep Emacsens' auto-indent happy */
234 /** @} */ /* end of group client_manager */
236 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
238 /* end of gnunet_client_manager_lib.h */