diff options
Diffstat (limited to 'src/include/gnunet_server_lib.h')
-rw-r--r-- | src/include/gnunet_server_lib.h | 887 |
1 files changed, 0 insertions, 887 deletions
diff --git a/src/include/gnunet_server_lib.h b/src/include/gnunet_server_lib.h deleted file mode 100644 index 5da31bcd7..000000000 --- a/src/include/gnunet_server_lib.h +++ /dev/null | |||
@@ -1,887 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2009-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 Christian Grothoff | ||
23 | * | ||
24 | * @file | ||
25 | * Library for building GNUnet network servers | ||
26 | |||
27 | * @defgroup server Server library | ||
28 | * Library for building GNUnet network servers | ||
29 | * | ||
30 | * Provides functions for a server that communicates with clients. | ||
31 | * | ||
32 | * @see [Documentation](https://gnunet.org/ipc) | ||
33 | * | ||
34 | * @{ | ||
35 | */ | ||
36 | |||
37 | #ifndef GNUNET_SERVER_LIB_H | ||
38 | #define GNUNET_SERVER_LIB_H | ||
39 | |||
40 | #ifdef __cplusplus | ||
41 | extern "C" | ||
42 | { | ||
43 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
44 | } | ||
45 | #endif | ||
46 | #endif | ||
47 | |||
48 | #include "gnunet_common.h" | ||
49 | #include "gnunet_connection_lib.h" | ||
50 | |||
51 | |||
52 | /** | ||
53 | * Largest supported message (to be precise, one byte more | ||
54 | * than the largest possible message, so tests involving | ||
55 | * this value should check for messages being smaller than | ||
56 | * this value). | ||
57 | */ | ||
58 | #define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536 | ||
59 | |||
60 | /** | ||
61 | * Smallest supported message. | ||
62 | */ | ||
63 | #define GNUNET_SERVER_MIN_BUFFER_SIZE sizeof (struct GNUNET_MessageHeader) | ||
64 | |||
65 | /** | ||
66 | * @brief handle for a server | ||
67 | */ | ||
68 | struct GNUNET_SERVER_Handle; | ||
69 | |||
70 | /** | ||
71 | * @brief opaque handle for a client of the server | ||
72 | */ | ||
73 | struct GNUNET_SERVER_Client; | ||
74 | |||
75 | /** | ||
76 | * @brief opaque handle server returns for aborting transmission to a client. | ||
77 | */ | ||
78 | struct GNUNET_SERVER_TransmitHandle; | ||
79 | |||
80 | |||
81 | /** | ||
82 | * Functions with this signature are called whenever a message is | ||
83 | * received. | ||
84 | * | ||
85 | * @param cls closure | ||
86 | * @param client identification of the client | ||
87 | * @param message the actual message | ||
88 | */ | ||
89 | typedef void | ||
90 | (*GNUNET_SERVER_MessageCallback) (void *cls, | ||
91 | struct GNUNET_SERVER_Client *client, | ||
92 | const struct GNUNET_MessageHeader *message); | ||
93 | |||
94 | |||
95 | /** | ||
96 | * Message handler. Each struct specifies how to handle on particular | ||
97 | * type of message received. | ||
98 | */ | ||
99 | struct GNUNET_SERVER_MessageHandler | ||
100 | { | ||
101 | /** | ||
102 | * Function to call for messages of "type". | ||
103 | */ | ||
104 | GNUNET_SERVER_MessageCallback callback; | ||
105 | |||
106 | /** | ||
107 | * Closure argument for @e callback. | ||
108 | */ | ||
109 | void *callback_cls; | ||
110 | |||
111 | /** | ||
112 | * Type of the message this handler covers. | ||
113 | */ | ||
114 | uint16_t type; | ||
115 | |||
116 | /** | ||
117 | * Expected size of messages of this type. Use 0 for | ||
118 | * variable-size. If non-zero, messages of the given | ||
119 | * type will be discarded (and the connection closed) | ||
120 | * if they do not have the right size. | ||
121 | */ | ||
122 | uint16_t expected_size; | ||
123 | |||
124 | }; | ||
125 | |||
126 | |||
127 | /** | ||
128 | * Create a new server. | ||
129 | * | ||
130 | * @param access_cb function for access control | ||
131 | * @param access_cb_cls closure for @a access_cb | ||
132 | * @param lsocks NULL-terminated array of listen sockets | ||
133 | * @param idle_timeout after how long should we timeout idle connections? | ||
134 | * @param require_found if #GNUNET_YES, connections sending messages of unknown type | ||
135 | * will be closed | ||
136 | * @return handle for the new server, NULL on error | ||
137 | * (typically, "port" already in use) | ||
138 | */ | ||
139 | struct GNUNET_SERVER_Handle * | ||
140 | GNUNET_SERVER_create_with_sockets (GNUNET_CONNECTION_AccessCheck access_cb, | ||
141 | void *access_cb_cls, | ||
142 | struct GNUNET_NETWORK_Handle **lsocks, | ||
143 | struct GNUNET_TIME_Relative idle_timeout, | ||
144 | int require_found); | ||
145 | |||
146 | /** | ||
147 | * Create a new server. | ||
148 | * | ||
149 | * @param access_cb function for access control | ||
150 | * @param access_cb_cls closure for @a access_cb | ||
151 | * @param server_addr address toes listen on (including port), NULL terminated array | ||
152 | * @param socklen lengths of respective @a server_addr | ||
153 | * @param idle_timeout after how long should we timeout idle connections? | ||
154 | * @param require_found if #GNUNET_YES, connections sending messages of unknown type | ||
155 | * will be closed | ||
156 | * @return handle for the new server, NULL on error | ||
157 | * (typically, "port" already in use) | ||
158 | */ | ||
159 | struct GNUNET_SERVER_Handle * | ||
160 | GNUNET_SERVER_create (GNUNET_CONNECTION_AccessCheck access_cb, | ||
161 | void *access_cb_cls, | ||
162 | struct sockaddr *const *server_addr, | ||
163 | const socklen_t *socklen, | ||
164 | struct GNUNET_TIME_Relative idle_timeout, | ||
165 | int require_found); | ||
166 | |||
167 | |||
168 | /** | ||
169 | * Suspend accepting connections from the listen socket temporarily. | ||
170 | * Resume activity using #GNUNET_SERVER_resume. | ||
171 | * | ||
172 | * @param server server to stop accepting connections. | ||
173 | */ | ||
174 | void | ||
175 | GNUNET_SERVER_suspend (struct GNUNET_SERVER_Handle *server); | ||
176 | |||
177 | |||
178 | /** | ||
179 | * Resume accepting connections from the listen socket. | ||
180 | * | ||
181 | * @param server server to resume accepting connections. | ||
182 | */ | ||
183 | void | ||
184 | GNUNET_SERVER_resume (struct GNUNET_SERVER_Handle *server); | ||
185 | |||
186 | |||
187 | /** | ||
188 | * Stop the listen socket and get ready to shutdown the server once | ||
189 | * only clients marked using #GNUNET_SERVER_client_mark_monitor are | ||
190 | * left. | ||
191 | * | ||
192 | * @param server server to stop listening on | ||
193 | */ | ||
194 | void | ||
195 | GNUNET_SERVER_stop_listening (struct GNUNET_SERVER_Handle *server); | ||
196 | |||
197 | |||
198 | /** | ||
199 | * Free resources held by this server. | ||
200 | * | ||
201 | * @param server server to destroy | ||
202 | */ | ||
203 | void | ||
204 | GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *server); | ||
205 | |||
206 | |||
207 | /** | ||
208 | * Add additional handlers to an existing server. | ||
209 | * | ||
210 | * @param server the server to add handlers to | ||
211 | * @param handlers array of message handlers for | ||
212 | * incoming messages; the last entry must | ||
213 | * have "NULL" for the "callback"; multiple | ||
214 | * entries for the same type are allowed, | ||
215 | * they will be called in order of occurence. | ||
216 | * These handlers can be removed later; | ||
217 | * the handlers array must exist until removed | ||
218 | * (or server is destroyed). | ||
219 | */ | ||
220 | void | ||
221 | GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server, | ||
222 | const struct GNUNET_SERVER_MessageHandler *handlers); | ||
223 | |||
224 | |||
225 | /** | ||
226 | * Notify us when the server has enough space to transmit | ||
227 | * a message of the given size to the given client. | ||
228 | * | ||
229 | * @param client client to transmit message to | ||
230 | * @param size requested amount of buffer space | ||
231 | * @param timeout after how long should we give up (and call | ||
232 | * notify with buf NULL and size 0)? | ||
233 | * @param callback function to call when space is available | ||
234 | * @param callback_cls closure for @a callback | ||
235 | * @return non-NULL if the notify callback was queued; can be used | ||
236 | * to cancel the request using | ||
237 | * #GNUNET_SERVER_notify_transmit_ready_cancel. | ||
238 | * NULL if we are already going to notify someone else (busy) | ||
239 | */ | ||
240 | struct GNUNET_SERVER_TransmitHandle * | ||
241 | GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client, | ||
242 | size_t size, | ||
243 | struct GNUNET_TIME_Relative timeout, | ||
244 | GNUNET_CONNECTION_TransmitReadyNotify callback, | ||
245 | void *callback_cls); | ||
246 | |||
247 | |||
248 | /** | ||
249 | * Abort transmission request. | ||
250 | * | ||
251 | * @param th request to abort | ||
252 | */ | ||
253 | void | ||
254 | GNUNET_SERVER_notify_transmit_ready_cancel (struct GNUNET_SERVER_TransmitHandle *th); | ||
255 | |||
256 | |||
257 | /** | ||
258 | * Set the 'monitor' flag on this client. Clients which have been | ||
259 | * marked as 'monitors' won't prevent the server from shutting down | ||
260 | * once #GNUNET_SERVER_stop_listening has been invoked. The idea is | ||
261 | * that for "normal" clients we likely want to allow them to process | ||
262 | * their requests; however, monitor-clients are likely to 'never' | ||
263 | * disconnect during shutdown and thus will not be considered when | ||
264 | * determining if the server should continue to exist after | ||
265 | * #GNUNET_SERVER_destroy has been called. | ||
266 | * | ||
267 | * @param client the client to set the 'monitor' flag on | ||
268 | */ | ||
269 | void | ||
270 | GNUNET_SERVER_client_mark_monitor (struct GNUNET_SERVER_Client *client); | ||
271 | |||
272 | |||
273 | /** | ||
274 | * Set the persistent flag on this client, used to setup client | ||
275 | * connection to only be killed when the process of the service it's | ||
276 | * connected to is actually dead. This API is used during shutdown | ||
277 | * signalling within ARM, and it is not expected that typical users | ||
278 | * of the API would need this function. | ||
279 | * | ||
280 | * @param client the client to set the persistent flag on | ||
281 | */ | ||
282 | void | ||
283 | GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client); | ||
284 | |||
285 | |||
286 | /** | ||
287 | * Resume receiving from this client, we are done processing the | ||
288 | * current request. This function must be called from within each | ||
289 | * #GNUNET_SERVER_MessageCallback (or its respective continuations). | ||
290 | * | ||
291 | * @param client client we were processing a message of | ||
292 | * @param success #GNUNET_OK to keep the connection open and | ||
293 | * continue to receive | ||
294 | * #GNUNET_NO to close the connection (normal behavior) | ||
295 | * #GNUNET_SYSERR to close the connection (signal | ||
296 | * serious error) | ||
297 | */ | ||
298 | void | ||
299 | GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, | ||
300 | int success); | ||
301 | |||
302 | |||
303 | /** | ||
304 | * Change the timeout for a particular client. Decreasing the timeout | ||
305 | * may not go into effect immediately (only after the previous timeout | ||
306 | * times out or activity happens on the socket). | ||
307 | * | ||
308 | * @param client the client to update | ||
309 | * @param timeout new timeout for activities on the socket | ||
310 | */ | ||
311 | void | ||
312 | GNUNET_SERVER_client_set_timeout (struct GNUNET_SERVER_Client *client, | ||
313 | struct GNUNET_TIME_Relative timeout); | ||
314 | |||
315 | |||
316 | /** | ||
317 | * Return user context associated with the given client. | ||
318 | * Note: you should probably use the macro (call without the underscore). | ||
319 | * | ||
320 | * @param client client to query | ||
321 | * @param size number of bytes in user context struct (for verification only) | ||
322 | * @return pointer to user context | ||
323 | */ | ||
324 | void * | ||
325 | GNUNET_SERVER_client_get_user_context_ (struct GNUNET_SERVER_Client *client, | ||
326 | size_t size); | ||
327 | |||
328 | |||
329 | /** | ||
330 | * Set user context to be associated with the given client. | ||
331 | * Note: you should probably use the macro (call without the underscore). | ||
332 | * | ||
333 | * @param client client to query | ||
334 | * @param ptr pointer to user context | ||
335 | * @param size number of bytes in user context struct (for verification only) | ||
336 | */ | ||
337 | void | ||
338 | GNUNET_SERVER_client_set_user_context_ (struct GNUNET_SERVER_Client *client, | ||
339 | void *ptr, | ||
340 | size_t size); | ||
341 | |||
342 | |||
343 | /** | ||
344 | * Return user context associated with the given client. | ||
345 | * | ||
346 | * @param client client to query | ||
347 | * @param type expected return type (i.e. 'struct Foo') | ||
348 | * @return pointer to user context of type 'type *'. | ||
349 | */ | ||
350 | #define GNUNET_SERVER_client_get_user_context(client,type) \ | ||
351 | (type *) GNUNET_SERVER_client_get_user_context_ (client, sizeof (type)) | ||
352 | |||
353 | /** | ||
354 | * Set user context to be associated with the given client. | ||
355 | * | ||
356 | * @param client client to query | ||
357 | * @param value pointer to user context | ||
358 | */ | ||
359 | #define GNUNET_SERVER_client_set_user_context(client,value) \ | ||
360 | GNUNET_SERVER_client_set_user_context_ (client, value, sizeof (*value)) | ||
361 | |||
362 | |||
363 | /** | ||
364 | * Disable the warning the server issues if a message is not acknowledged | ||
365 | * in a timely fashion. Use this call if a client is intentionally delayed | ||
366 | * for a while. Only applies to the current message. | ||
367 | * | ||
368 | * @param client client for which to disable the warning | ||
369 | */ | ||
370 | void | ||
371 | GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client | ||
372 | *client); | ||
373 | |||
374 | |||
375 | /** | ||
376 | * Inject a message into the server, pretend it came | ||
377 | * from the specified client. Delivery of the message | ||
378 | * will happen instantly (if a handler is installed; | ||
379 | * otherwise the call does nothing). | ||
380 | * | ||
381 | * @param server the server receiving the message | ||
382 | * @param sender the "pretended" sender of the message | ||
383 | * can be NULL! | ||
384 | * @param message message to transmit | ||
385 | * @return #GNUNET_OK if the message was OK and the | ||
386 | * connection can stay open | ||
387 | * #GNUNET_SYSERR if the connection to the | ||
388 | * client should be shut down | ||
389 | */ | ||
390 | int | ||
391 | GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server, | ||
392 | struct GNUNET_SERVER_Client *sender, | ||
393 | const struct GNUNET_MessageHeader *message); | ||
394 | |||
395 | |||
396 | /** | ||
397 | * Add a TCP socket-based connection to the set of handles managed by | ||
398 | * this server. Use this function for outgoing (P2P) connections that | ||
399 | * we initiated (and where this server should process incoming | ||
400 | * messages). | ||
401 | * | ||
402 | * @param server the server to use | ||
403 | * @param connection the connection to manage (client must | ||
404 | * stop using this connection from now on) | ||
405 | * @return the client handle | ||
406 | */ | ||
407 | struct GNUNET_SERVER_Client * | ||
408 | GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server, | ||
409 | struct GNUNET_CONNECTION_Handle *connection); | ||
410 | |||
411 | |||
412 | /** | ||
413 | * Notify the server that the given client handle should | ||
414 | * be kept (keeps the connection up if possible, increments | ||
415 | * the internal reference counter). | ||
416 | * | ||
417 | * @param client the client to keep | ||
418 | */ | ||
419 | void | ||
420 | GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client); | ||
421 | |||
422 | |||
423 | /** | ||
424 | * Notify the server that the given client handle is no | ||
425 | * longer required. Decrements the reference counter. If | ||
426 | * that counter reaches zero an inactive connection maybe | ||
427 | * closed. | ||
428 | * | ||
429 | * @param client the client to drop | ||
430 | */ | ||
431 | void | ||
432 | GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client); | ||
433 | |||
434 | |||
435 | /** | ||
436 | * Obtain the network address of the other party. | ||
437 | * | ||
438 | * @param client the client to get the address for | ||
439 | * @param addr where to store the address | ||
440 | * @param addrlen where to store the length of @a addr | ||
441 | * @return #GNUNET_OK on success | ||
442 | */ | ||
443 | int | ||
444 | GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client, | ||
445 | void **addr, size_t *addrlen); | ||
446 | |||
447 | |||
448 | /** | ||
449 | * Functions with this signature are called whenever a client | ||
450 | * is disconnected on the network level. | ||
451 | * | ||
452 | * @param cls closure | ||
453 | * @param client identification of the client; NULL | ||
454 | * for the last call when the server is destroyed | ||
455 | */ | ||
456 | typedef void | ||
457 | (*GNUNET_SERVER_DisconnectCallback) (void *cls, | ||
458 | struct GNUNET_SERVER_Client *client); | ||
459 | |||
460 | |||
461 | /** | ||
462 | * Functions with this signature are called whenever a client | ||
463 | * is connected on the network level. | ||
464 | * | ||
465 | * @param cls closure | ||
466 | * @param client identification of the client | ||
467 | */ | ||
468 | typedef void | ||
469 | (*GNUNET_SERVER_ConnectCallback) (void *cls, | ||
470 | struct GNUNET_SERVER_Client *client); | ||
471 | |||
472 | |||
473 | /** | ||
474 | * Ask the server to notify us whenever a client disconnects. | ||
475 | * This function is called whenever the actual network connection | ||
476 | * is closed; the reference count may be zero or larger than zero | ||
477 | * at this point. If the server is destroyed before this | ||
478 | * notification is explicitly cancelled, the 'callback' will | ||
479 | * once be called with a 'client' argument of NULL to indicate | ||
480 | * that the server itself is now gone (and that the callback | ||
481 | * won't be called anymore and also can no longer be cancelled). | ||
482 | * | ||
483 | * @param server the server manageing the clients | ||
484 | * @param callback function to call on disconnect | ||
485 | * @param callback_cls closure for @a callback | ||
486 | */ | ||
487 | void | ||
488 | GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server, | ||
489 | GNUNET_SERVER_DisconnectCallback callback, | ||
490 | void *callback_cls); | ||
491 | |||
492 | |||
493 | /** | ||
494 | * Ask the server to notify us whenever a client connects. | ||
495 | * This function is called whenever the actual network connection | ||
496 | * is opened. If the server is destroyed before this | ||
497 | * notification is explicitly cancelled, the @a callback will | ||
498 | * once be called with a 'client' argument of NULL to indicate | ||
499 | * that the server itself is now gone (and that the callback | ||
500 | * won't be called anymore and also can no longer be cancelled). | ||
501 | * | ||
502 | * @param server the server manageing the clients | ||
503 | * @param callback function to call on sconnect | ||
504 | * @param callback_cls closure for @a callback | ||
505 | */ | ||
506 | void | ||
507 | GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server, | ||
508 | GNUNET_SERVER_ConnectCallback callback, | ||
509 | void *callback_cls); | ||
510 | |||
511 | |||
512 | /** | ||
513 | * Ask the server to stop notifying us whenever a client disconnects. | ||
514 | * Arguments must match exactly those given to | ||
515 | * #GNUNET_SERVER_disconnect_notify. It is not necessary to call this | ||
516 | * function during shutdown of the server; in fact, most applications | ||
517 | * will never use this function. | ||
518 | * | ||
519 | * @param server the server manageing the clients | ||
520 | * @param callback function to call on disconnect | ||
521 | * @param callback_cls closure for @a callback | ||
522 | */ | ||
523 | void | ||
524 | GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server, | ||
525 | GNUNET_SERVER_DisconnectCallback callback, | ||
526 | void *callback_cls); | ||
527 | |||
528 | |||
529 | /** | ||
530 | * Ask the server to stop notifying us whenever a client connects. | ||
531 | * Arguments must match exactly those given to | ||
532 | * #GNUNET_SERVER_connect_notify. It is not necessary to call this | ||
533 | * function during shutdown of the server; in fact, most applications | ||
534 | * will never use this function. | ||
535 | * | ||
536 | * @param server the server manageing the clients | ||
537 | * @param callback function to call on connect | ||
538 | * @param callback_cls closure for @a callback | ||
539 | */ | ||
540 | void | ||
541 | GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server, | ||
542 | GNUNET_SERVER_ConnectCallback callback, | ||
543 | void *callback_cls); | ||
544 | |||
545 | |||
546 | /** | ||
547 | * Ask the server to disconnect from the given client. This is the | ||
548 | * same as passing #GNUNET_SYSERR to #GNUNET_SERVER_receive_done, | ||
549 | * except that it allows dropping of a client even when not handling a | ||
550 | * message from that client. | ||
551 | * | ||
552 | * @param client the client to disconnect from | ||
553 | */ | ||
554 | void | ||
555 | GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client); | ||
556 | |||
557 | |||
558 | /** | ||
559 | * Disable the "CORK" feature for communication with the given client, | ||
560 | * forcing the OS to immediately flush the buffer on transmission | ||
561 | * instead of potentially buffering multiple messages. | ||
562 | * | ||
563 | * @param client handle to the client | ||
564 | * @return #GNUNET_OK on success | ||
565 | */ | ||
566 | int | ||
567 | GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client); | ||
568 | |||
569 | |||
570 | /** | ||
571 | * The tansmit context is the key datastructure for a conveniance API | ||
572 | * used for transmission of complex results to the client followed | ||
573 | * ONLY by signaling receive_done with success or error | ||
574 | */ | ||
575 | struct GNUNET_SERVER_TransmitContext; | ||
576 | |||
577 | |||
578 | /** | ||
579 | * Create a new transmission context for the given client. | ||
580 | * | ||
581 | * @param client client to create the context for. | ||
582 | * @return NULL on error | ||
583 | */ | ||
584 | struct GNUNET_SERVER_TransmitContext * | ||
585 | GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client *client); | ||
586 | |||
587 | |||
588 | /** | ||
589 | * Append a message to the transmission context. | ||
590 | * All messages in the context will be sent by | ||
591 | * the #GNUNET_SERVER_transmit_context_run method. | ||
592 | * | ||
593 | * @param tc context to use | ||
594 | * @param data what to append to the result message | ||
595 | * @param length length of @a data | ||
596 | * @param type type of the message | ||
597 | */ | ||
598 | void | ||
599 | GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext *tc, | ||
600 | const void *data, | ||
601 | size_t length, uint16_t type); | ||
602 | |||
603 | |||
604 | /** | ||
605 | * Append a message to the transmission context. | ||
606 | * All messages in the context will be sent by | ||
607 | * the transmit_context_run method. | ||
608 | * | ||
609 | * @param tc context to use | ||
610 | * @param msg message to append | ||
611 | */ | ||
612 | void | ||
613 | GNUNET_SERVER_transmit_context_append_message (struct GNUNET_SERVER_TransmitContext *tc, | ||
614 | const struct GNUNET_MessageHeader *msg); | ||
615 | |||
616 | |||
617 | /** | ||
618 | * Execute a transmission context. If there is an error in the | ||
619 | * transmission, the receive_done method will be called with an error | ||
620 | * code (#GNUNET_SYSERR), otherwise with #GNUNET_OK. | ||
621 | * | ||
622 | * @param tc transmission context to use | ||
623 | * @param timeout when to time out and abort the transmission | ||
624 | */ | ||
625 | void | ||
626 | GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc, | ||
627 | struct GNUNET_TIME_Relative timeout); | ||
628 | |||
629 | |||
630 | /** | ||
631 | * Destroy a transmission context. This function must not be called | ||
632 | * after #GNUNET_SERVER_transmit_context_run. | ||
633 | * | ||
634 | * @param tc transmission context to destroy | ||
635 | * @param success code to give to #GNUNET_SERVER_receive_done for | ||
636 | * the client: #GNUNET_OK to keep the connection open and | ||
637 | * continue to receive | ||
638 | * #GNUNET_NO to close the connection (normal behavior) | ||
639 | * #GNUNET_SYSERR to close the connection (signal | ||
640 | * serious error) | ||
641 | */ | ||
642 | void | ||
643 | GNUNET_SERVER_transmit_context_destroy (struct GNUNET_SERVER_TransmitContext *tc, | ||
644 | int success); | ||
645 | |||
646 | |||
647 | /** | ||
648 | * The notification context is the key datastructure for a conveniance | ||
649 | * API used for transmission of notifications to the client until the | ||
650 | * client disconnects or is disconnected (or the notification context | ||
651 | * is destroyed, in which case we disconnect these clients). | ||
652 | * Essentially, all (notification) messages are queued up until the | ||
653 | * client is able to read them. | ||
654 | */ | ||
655 | struct GNUNET_SERVER_NotificationContext; | ||
656 | |||
657 | |||
658 | /** | ||
659 | * Create a new notification context. | ||
660 | * | ||
661 | * @param server server for which this function creates the context | ||
662 | * @param queue_length maximum number of messages to keep in | ||
663 | * the notification queue; optional messages are dropped | ||
664 | * if the queue gets longer than this number of messages | ||
665 | * @return handle to the notification context | ||
666 | */ | ||
667 | struct GNUNET_SERVER_NotificationContext * | ||
668 | GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server, | ||
669 | unsigned int queue_length); | ||
670 | |||
671 | |||
672 | /** | ||
673 | * Destroy the context, force disconnect for all clients. | ||
674 | * | ||
675 | * @param nc context to destroy. | ||
676 | */ | ||
677 | void | ||
678 | GNUNET_SERVER_notification_context_destroy (struct GNUNET_SERVER_NotificationContext *nc); | ||
679 | |||
680 | |||
681 | /** | ||
682 | * Add a client to the notification context. | ||
683 | * | ||
684 | * @param nc context to modify | ||
685 | * @param client client to add | ||
686 | */ | ||
687 | void | ||
688 | GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext *nc, | ||
689 | struct GNUNET_SERVER_Client *client); | ||
690 | |||
691 | |||
692 | /** | ||
693 | * Send a message to a particular client; must have | ||
694 | * already been added to the notification context. | ||
695 | * | ||
696 | * @param nc context to modify | ||
697 | * @param client client to transmit to | ||
698 | * @param msg message to send | ||
699 | * @param can_drop can this message be dropped due to queue length limitations | ||
700 | */ | ||
701 | void | ||
702 | GNUNET_SERVER_notification_context_unicast (struct GNUNET_SERVER_NotificationContext *nc, | ||
703 | struct GNUNET_SERVER_Client *client, | ||
704 | const struct GNUNET_MessageHeader *msg, | ||
705 | int can_drop); | ||
706 | |||
707 | |||
708 | /** | ||
709 | * Send a message to all clients of this context. | ||
710 | * | ||
711 | * @param nc context to modify | ||
712 | * @param msg message to send | ||
713 | * @param can_drop can this message be dropped due to queue length limitations | ||
714 | */ | ||
715 | void | ||
716 | GNUNET_SERVER_notification_context_broadcast (struct GNUNET_SERVER_NotificationContext *nc, | ||
717 | const struct GNUNET_MessageHeader *msg, | ||
718 | int can_drop); | ||
719 | |||
720 | |||
721 | /** | ||
722 | * Return active number of subscribers in this context. | ||
723 | * | ||
724 | * @param nc context to query | ||
725 | * @return number of current subscribers | ||
726 | */ | ||
727 | unsigned int | ||
728 | GNUNET_SERVER_notification_context_get_size (struct GNUNET_SERVER_NotificationContext *nc); | ||
729 | |||
730 | |||
731 | /** | ||
732 | * Create a message queue for a server's client. | ||
733 | * | ||
734 | * @param client the client | ||
735 | * @return the message queue | ||
736 | */ | ||
737 | struct GNUNET_MQ_Handle * | ||
738 | GNUNET_MQ_queue_for_server_client (struct GNUNET_SERVER_Client *client); | ||
739 | |||
740 | |||
741 | /** | ||
742 | * Handle to a message stream tokenizer. | ||
743 | */ | ||
744 | struct GNUNET_SERVER_MessageStreamTokenizer; | ||
745 | |||
746 | |||
747 | /** | ||
748 | * Functions with this signature are called whenever a | ||
749 | * complete message is received by the tokenizer. | ||
750 | * | ||
751 | * Do not call #GNUNET_SERVER_mst_destroy from within | ||
752 | * the scope of this callback. | ||
753 | * | ||
754 | * @param cls closure | ||
755 | * @param client identification of the client | ||
756 | * @param message the actual message | ||
757 | * @return #GNUNET_OK on success, #GNUNET_SYSERR to stop further processing | ||
758 | */ | ||
759 | typedef int | ||
760 | (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, | ||
761 | void *client, | ||
762 | const struct GNUNET_MessageHeader *message); | ||
763 | |||
764 | |||
765 | /** | ||
766 | * Create a message stream tokenizer. | ||
767 | * | ||
768 | * @param cb function to call on completed messages | ||
769 | * @param cb_cls closure for @a cb | ||
770 | * @return handle to tokenizer | ||
771 | */ | ||
772 | struct GNUNET_SERVER_MessageStreamTokenizer * | ||
773 | GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb, | ||
774 | void *cb_cls); | ||
775 | |||
776 | |||
777 | /** | ||
778 | * Add incoming data to the receive buffer and call the | ||
779 | * callback for all complete messages. | ||
780 | * | ||
781 | * @param mst tokenizer to use | ||
782 | * @param client_identity ID of client for which this is a buffer, | ||
783 | * can be NULL (will be passed back to 'cb') | ||
784 | * @param buf input data to add | ||
785 | * @param size number of bytes in @a buf | ||
786 | * @param purge should any excess bytes in the buffer be discarded | ||
787 | * (i.e. for packet-based services like UDP) | ||
788 | * @param one_shot only call callback once, keep rest of message in buffer | ||
789 | * @return #GNUNET_OK if we are done processing (need more data) | ||
790 | * #GNUNET_NO if one_shot was set and we have another message ready | ||
791 | * #GNUNET_SYSERR if the data stream is corrupt | ||
792 | */ | ||
793 | int | ||
794 | GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst, | ||
795 | void *client_identity, | ||
796 | const char *buf, size_t size, | ||
797 | int purge, int one_shot); | ||
798 | |||
799 | |||
800 | /** | ||
801 | * Destroys a tokenizer. | ||
802 | * | ||
803 | * @param mst tokenizer to destroy | ||
804 | */ | ||
805 | void | ||
806 | GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst); | ||
807 | |||
808 | |||
809 | /** | ||
810 | * Signature of a function to create a custom tokenizer. | ||
811 | * | ||
812 | * @param cls closure from #GNUNET_SERVER_set_callbacks | ||
813 | * @param client handle to client the tokenzier will be used for | ||
814 | * @return handle to custom tokenizer ('mst') | ||
815 | */ | ||
816 | typedef void* | ||
817 | (*GNUNET_SERVER_MstCreateCallback) (void *cls, | ||
818 | struct GNUNET_SERVER_Client *client); | ||
819 | |||
820 | |||
821 | /** | ||
822 | * Signature of a function to destroy a custom tokenizer. | ||
823 | * | ||
824 | * @param cls closure from #GNUNET_SERVER_set_callbacks | ||
825 | * @param mst custom tokenizer handle | ||
826 | */ | ||
827 | typedef void | ||
828 | (*GNUNET_SERVER_MstDestroyCallback) (void *cls, | ||
829 | void *mst); | ||
830 | |||
831 | |||
832 | /** | ||
833 | * Signature of a function to receive data for a custom tokenizer. | ||
834 | * | ||
835 | * @param cls closure from #GNUNET_SERVER_set_callbacks | ||
836 | * @param mst custom tokenizer handle | ||
837 | * @param client_identity ID of client for which this is a buffer, | ||
838 | * can be NULL (will be passed back to 'cb') | ||
839 | * @param buf input data to add | ||
840 | * @param size number of bytes in @a buf | ||
841 | * @param purge should any excess bytes in the buffer be discarded | ||
842 | * (i.e. for packet-based services like UDP) | ||
843 | * @param one_shot only call callback once, keep rest of message in buffer | ||
844 | * @return #GNUNET_OK if we are done processing (need more data) | ||
845 | * #GNUNET_NO if one_shot was set and we have another message ready | ||
846 | * #GNUNET_SYSERR if the data stream is corrupt | ||
847 | */ | ||
848 | typedef int | ||
849 | (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst, | ||
850 | struct GNUNET_SERVER_Client *client, | ||
851 | const char *buf, | ||
852 | size_t size, | ||
853 | int purge, | ||
854 | int one_shot); | ||
855 | |||
856 | |||
857 | /** | ||
858 | * Change functions used by the server to tokenize the message stream. | ||
859 | * (very rarely used). | ||
860 | * | ||
861 | * @param server server to modify | ||
862 | * @param create new tokenizer initialization function | ||
863 | * @param destroy new tokenizer destruction function | ||
864 | * @param receive new tokenizer receive function | ||
865 | * @param cls closure for @a create, @a receive and @a destroy | ||
866 | */ | ||
867 | void | ||
868 | GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server, | ||
869 | GNUNET_SERVER_MstCreateCallback create, | ||
870 | GNUNET_SERVER_MstDestroyCallback destroy, | ||
871 | GNUNET_SERVER_MstReceiveCallback receive, | ||
872 | void *cls); | ||
873 | |||
874 | |||
875 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
876 | { | ||
877 | #endif | ||
878 | #ifdef __cplusplus | ||
879 | } | ||
880 | #endif | ||
881 | |||
882 | /* ifndef GNUNET_SERVER_LIB_H */ | ||
883 | #endif | ||
884 | |||
885 | /** @} */ /* end of group server */ | ||
886 | |||
887 | /* end of gnunet_server_lib.h */ | ||