aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_client_manager_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_client_manager_lib.h')
-rw-r--r--src/include/gnunet_client_manager_lib.h359
1 files changed, 0 insertions, 359 deletions
diff --git a/src/include/gnunet_client_manager_lib.h b/src/include/gnunet_client_manager_lib.h
deleted file mode 100644
index fc4f65570..000000000
--- a/src/include/gnunet_client_manager_lib.h
+++ /dev/null
@@ -1,359 +0,0 @@
1/*
2 This file is part of GNUnet.
3 Copyright (C) 2013 GNUnet e.V.
4
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.
9
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.
14
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.
19*/
20
21/**
22 * @author Gabor X Toth
23 *
24 * @file
25 * Client manager; higher level client API with transmission queue
26 * and message handler registration.
27 *
28 * @defgroup client-manager Client manager library
29 * Higher level client-side communication with services.
30 *
31 * Provides a higher level client API
32 * with transmission queue and message handler registration.
33 * @{
34 */
35#ifndef GNUNET_CLIENT_MANAGER_LIB_H
36#define GNUNET_CLIENT_MANAGER_LIB_H
37
38#ifdef __cplusplus
39extern "C"
40{
41#if 0 /* keep Emacsens' auto-indent happy */
42}
43#endif
44#endif
45
46
47/**
48 * Client manager connection handle.
49 */
50struct GNUNET_CLIENT_MANAGER_Connection;
51
52
53/**
54 * Functions with this signature are called whenever a message is
55 * received.
56 *
57 * @param cls closure
58 * @param client identification of the client
59 * @param message the actual message
60 */
61typedef void
62(*GNUNET_CLIENT_MANAGER_MessageCallback) (void *cls,
63 struct GNUNET_CLIENT_MANAGER_Connection *mgr,
64 const struct GNUNET_MessageHeader *msg);
65
66
67/**
68 * Message handler. Each struct specifies how to handle on particular
69 * type of message received.
70 */
71struct GNUNET_CLIENT_MANAGER_MessageHandler
72{
73 /**
74 * Function to call for messages of @a type.
75 */
76 GNUNET_CLIENT_MANAGER_MessageCallback callback;
77
78 /**
79 * Closure argument for @a callback.
80 */
81 void *callback_cls;
82
83 /**
84 * Type of the message this handler covers.
85 * Use 0 to handle loss of connection.
86 */
87 uint16_t type;
88
89 /**
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.
93 */
94 uint16_t expected_size;
95
96 /**
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.
100 */
101 uint8_t is_variable_size;
102};
103
104
105/**
106 * Connect to a service.
107 *
108 * @param cfg
109 * Configuration to use.
110 * @param service_name
111 * Service name to connect to.
112 * @param handlers
113 * Message handlers.
114 *
115 * @return Client manager connection handle.
116 */
117struct GNUNET_CLIENT_MANAGER_Connection *
118GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
119 const char *service_name,
120 const struct
121 GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
122
123
124/**
125 * Disconnect from the service.
126 *
127 * @param mgr
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.
133 * @param cls
134 * Closure for @a disconnect_cb.
135 */
136void
137GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
138 int transmit_queue,
139 GNUNET_ContinuationCallback disconnect_cb,
140 void *cls);
141
142
143/**
144 * Reschedule connect to the service using exponential back-off.
145 *
146 * @param mgr
147 * Client manager connection.
148 */
149void
150GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
151
152
153/**
154 * Add a message to the end of the transmission queue.
155 *
156 * @param mgr
157 * Client manager connection.
158 * @param msg
159 * Message to transmit, should be allocated with GNUNET_malloc() or
160 * GNUNET_new(), as it is freed with GNUNET_free() after transmission.
161 */
162void
163GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
164 struct GNUNET_MessageHeader *msg);
165
166
167/**
168 * Add a message to the beginning of the transmission queue.
169 *
170 * @param mgr
171 * Client manager connection.
172 * @param msg
173 * Message to transmit, should be allocated with GNUNET_malloc() or
174 * GNUNET_new(), as it is freed with GNUNET_free() after transmission.
175 */
176void
177GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
178 struct GNUNET_MessageHeader *msg);
179
180
181/**
182 * Drop all queued messages.
183 *
184 * @param mgr
185 * Client manager connection.
186 */
187void
188GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
189
190
191/**
192 * Obtain client connection handle.
193 *
194 * @param mgr
195 * Client manager connection.
196 *
197 * @return Client connection handle.
198 */
199struct GNUNET_CLIENT_Connection *
200GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
201
202
203/**
204 * Return user context associated with the given client manager.
205 * Note: you should probably use the macro (call without the underscore).
206 *
207 * @param mgr
208 * Client manager connection.
209 * @param size
210 * Number of bytes in user context struct (for verification only).
211 */
212void *
213GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
214 size_t size);
215
216
217/**
218 * Set user context to be associated with the given client manager.
219 * Note: you should probably use the macro (call without the underscore).
220 *
221 * @param mgr
222 * Client manager connection.
223 * @param ctx
224 * User context.
225 * @param size
226 * Number of bytes in user context struct (for verification only).
227 */
228void
229GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
230 void *ctx,
231 size_t size);
232
233
234/**
235 * Return user context associated with the given client manager.
236 *
237 * @param mgr
238 * Client manager connection.
239 * @param type
240 * Type of context (for size verification).
241 */
242#define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type) \
243 (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
244
245
246/**
247 * Set user context to be associated with the given client manager.
248 *
249 * @param mgr
250 * Client manager connection.
251 * @param ctx
252 * Pointer to user context.
253 */
254#define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx) \
255 GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
256
257
258/**
259 * Get a unique operation ID to distinguish between asynchronous requests.
260 *
261 * @param mgr
262 * Client manager connection.
263 *
264 * @return Operation ID to use.
265 */
266uint64_t
267GNUNET_CLIENT_MANAGER_op_get_next_id (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
268
269
270/**
271 * Find operation by ID.
272 *
273 * @param mgr
274 * Client manager connection.
275 * @param op_id
276 * Operation ID to look up.
277 * @param[out] result_cb
278 * If an operation was found, its result callback is returned here.
279 * @param[out] cls
280 * If an operation was found, its closure is returned here.
281 *
282 * @return #GNUNET_YES if an operation was found,
283 * #GNUNET_NO if not found.
284 */
285int
286GNUNET_CLIENT_MANAGER_op_find (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
287 uint64_t op_id,
288 GNUNET_ResultCallback *result_cb,
289 void **cls);
290
291
292/**
293 * Add a new operation.
294 *
295 * @param mgr
296 * Client manager connection.
297 * @param result_cb
298 * Function to call with the result of the operation.
299 * @param cls
300 * Closure for @a result_cb.
301 *
302 * @return ID of the new operation.
303 */
304uint64_t
305GNUNET_CLIENT_MANAGER_op_add (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
306 GNUNET_ResultCallback result_cb,
307 void *cls);
308
309
310/**
311 * Call the result callback and remove the operation.
312 *
313 * @param mgr
314 * Client manager connection.
315 * @param op_id
316 * Operation ID.
317 * @param result_code
318 * Result of the operation.
319 * @param data
320 * Data result of the operation.
321 * @param data_size
322 * Size of @a data.
323 *
324 * @return #GNUNET_YES if the operation was found and removed,
325 * #GNUNET_NO if the operation was not found.
326 */
327int
328GNUNET_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);
331
332
333/**
334 * Cancel an operation.
335 *
336 * @param mgr
337 * Client manager connection.
338 * @param op_id
339 * Operation ID.
340 *
341 * @return #GNUNET_YES if the operation was found and removed,
342 * #GNUNET_NO if the operation was not found.
343 */
344int
345GNUNET_CLIENT_MANAGER_op_cancel (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
346 uint64_t op_id);
347
348
349#if 0 /* keep Emacsens' auto-indent happy */
350{
351#endif
352#ifdef __cplusplus
353}
354#endif
355
356/* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
357#endif
358
359/** @} */ /* end of group */
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-22 05:00:49 +0000