2 This file is part of GNUnet.
3 (C) 2009, 2010 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 2, 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_server_lib.h
23 * @brief library for building GNUnet network servers
25 * @author Christian Grothoff
28 #ifndef GNUNET_SERVER_LIB_H
29 #define GNUNET_SERVER_LIB_H
34 #if 0 /* keep Emacsens' auto-indent happy */
39 #include "gnunet_common.h"
40 #include "gnunet_connection_lib.h"
41 #include "gnunet_scheduler_lib.h"
45 * Largest supported message.
47 #define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536
50 * Largest supported message.
52 #define GNUNET_SERVER_MIN_BUFFER_SIZE sizeof (struct GNUNET_MessageHeader)
55 * @brief handle for a server
57 struct GNUNET_SERVER_Handle;
61 * @brief opaque handle for a client of the server
63 struct GNUNET_SERVER_Client;
67 * Functions with this signature are called whenever a message is
71 * @param client identification of the client
72 * @param message the actual message
74 typedef void (*GNUNET_SERVER_MessageCallback) (void *cls,
75 struct GNUNET_SERVER_Client *
78 GNUNET_MessageHeader *
84 * Message handler. Each struct specifies how to handle on particular
85 * type of message received.
87 struct GNUNET_SERVER_MessageHandler
90 * Function to call for messages of "type".
92 GNUNET_SERVER_MessageCallback callback;
95 * Closure argument for "callback".
100 * Type of the message this handler covers.
105 * Expected size of messages of this type. Use 0 for
106 * variable-size. If non-zero, messages of the given
107 * type will be discarded (and the connection closed)
108 * if they do not have the right size.
110 uint16_t expected_size;
116 * Create a new server.
118 * @param access function for access control
119 * @param access_cls closure for access
120 * @param lsocks NULL-terminated array of listen sockets
121 * @param idle_timeout after how long should we timeout idle connections?
122 * @param require_found if YES, connections sending messages of unknown type
124 * @return handle for the new server, NULL on error
125 * (typically, "port" already in use)
127 struct GNUNET_SERVER_Handle *
128 GNUNET_SERVER_create_with_sockets (GNUNET_CONNECTION_AccessCheck access, void *access_cls,
129 struct GNUNET_NETWORK_Handle **lsocks,
130 struct GNUNET_TIME_Relative
135 * Create a new server.
137 * @param access function for access control
138 * @param access_cls closure for access
139 * @param serverAddr address toes listen on (including port), NULL terminated array
140 * @param socklen lengths of respective serverAddr
141 * @param idle_timeout after how long should we timeout idle connections?
142 * @param require_found if YES, connections sending messages of unknown type
144 * @return handle for the new server, NULL on error
145 * (typically, "port" already in use)
147 struct GNUNET_SERVER_Handle *GNUNET_SERVER_create (GNUNET_CONNECTION_AccessCheck
148 access, void *access_cls,
149 struct sockaddr *const*serverAddr,
150 const socklen_t *socklen,
151 struct GNUNET_TIME_Relative
157 * Free resources held by this server.
159 * @param s server to destroy
161 void GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s);
165 * Add additional handlers to an existing server.
167 * @param server the server to add handlers to
168 * @param handlers array of message handlers for
169 * incoming messages; the last entry must
170 * have "NULL" for the "callback"; multiple
171 * entries for the same type are allowed,
172 * they will be called in order of occurence.
173 * These handlers can be removed later;
174 * the handlers array must exist until removed
175 * (or server is destroyed).
178 GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
179 const struct GNUNET_SERVER_MessageHandler
184 * Notify us when the server has enough space to transmit
185 * a message of the given size to the given client.
187 * @param client client to transmit message to
188 * @param size requested amount of buffer space
189 * @param timeout after how long should we give up (and call
190 * notify with buf NULL and size 0)?
191 * @param callback function to call when space is available
192 * @param callback_cls closure for callback
193 * @return non-NULL if the notify callback was queued; can be used
194 * to cancel the request using
195 * GNUNET_CONNECTION_notify_transmit_ready_cancel.
196 * NULL if we are already going to notify someone else (busy)
198 struct GNUNET_CONNECTION_TransmitHandle
199 *GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client,
201 struct GNUNET_TIME_Relative timeout,
202 GNUNET_CONNECTION_TransmitReadyNotify
203 callback, void *callback_cls);
207 * Set the persistent flag on this client, used to setup client connection
208 * to only be killed when the service it's connected to is actually dead.
210 * @param client the client to set the persistent flag on
213 GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client);
216 * Resume receiving from this client, we are done processing the
217 * current request. This function must be called from within each
218 * GNUNET_SERVER_MessageCallback (or its respective continuations).
220 * @param client client we were processing a message of
221 * @param success GNUNET_OK to keep the connection open and
222 * continue to receive
223 * GNUNET_NO to close the connection (normal behavior)
224 * GNUNET_SYSERR to close the connection (signal
228 GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success);
232 * Inject a message into the server, pretend it came
233 * from the specified client. Delivery of the message
234 * will happen instantly (if a handler is installed;
235 * otherwise the call does nothing).
237 * @param server the server receiving the message
238 * @param sender the "pretended" sender of the message
240 * @param message message to transmit
241 * @return GNUNET_OK if the message was OK and the
242 * connection can stay open
243 * GNUNET_SYSERR if the connection to the
244 * client should be shut down
247 GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
248 struct GNUNET_SERVER_Client *sender,
249 const struct GNUNET_MessageHeader *message);
253 * Add a TCP socket-based connection to the set of handles managed by
254 * this server. Use this function for outgoing (P2P) connections that
255 * we initiated (and where this server should process incoming
258 * @param server the server to use
259 * @param connection the connection to manage (client must
260 * stop using this connection from now on)
261 * @return the client handle (client should call
262 * "client_drop" on the return value eventually)
264 struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_socket (struct
268 GNUNET_CONNECTION_Handle
273 * Notify the server that the given client handle should
274 * be kept (keeps the connection up if possible, increments
275 * the internal reference counter).
277 * @param client the client to keep
279 void GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client);
283 * Notify the server that the given client handle is no
284 * longer required. Decrements the reference counter. If
285 * that counter reaches zero an inactive connection maybe
288 * @param client the client to drop
290 void GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);
294 * Obtain the network address of the other party.
296 * @param client the client to get the address for
297 * @param addr where to store the address
298 * @param addrlen where to store the length of the address
299 * @return GNUNET_OK on success
301 int GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
302 void **addr, size_t * addrlen);
306 * Functions with this signature are called whenever a client
307 * is disconnected on the network level.
310 * @param client identification of the client; NULL
311 * for the last call when the server is destroyed
313 typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
314 struct GNUNET_SERVER_Client
319 * Ask the server to notify us whenever a client disconnects.
320 * This function is called whenever the actual network connection
321 * is closed; the reference count may be zero or larger than zero
322 * at this point. If the server is destroyed before this
323 * notification is explicitly cancelled, the 'callback' will
324 * once be called with a 'client' argument of NULL to indicate
325 * that the server itself is now gone (and that the callback
326 * won't be called anymore and also can no longer be cancelled).
328 * @param server the server manageing the clients
329 * @param callback function to call on disconnect
330 * @param callback_cls closure for callback
332 void GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
333 GNUNET_SERVER_DisconnectCallback
334 callback, void *callback_cls);
338 * Ask the server to stop notifying us whenever a client disconnects.
340 * @param server the server manageing the clients
341 * @param callback function to call on disconnect
342 * @param callback_cls closure for callback
344 void GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
345 GNUNET_SERVER_DisconnectCallback
346 callback, void *callback_cls);
350 * Ask the server to disconnect from the given client.
351 * This is the same as returning GNUNET_SYSERR from a message
352 * handler, except that it allows dropping of a client even
353 * when not handling a message from that client.
355 * @param client the client to disconnect from
357 void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
361 * Configure this server's connections to continue handling client
362 * requests as usual even after we get a shutdown signal. The change
363 * only applies to clients that connect to the server from the outside
364 * using TCP after this call. Clients managed previously or those
365 * added using GNUNET_SERVER_connect_socket and
366 * GNUNET_SERVER_connect_callback are not affected by this option.
368 * @param h server handle
369 * @param do_ignore GNUNET_YES to ignore, GNUNET_NO to restore default
372 GNUNET_SERVER_ignore_shutdown (struct GNUNET_SERVER_Handle *h,
378 * The tansmit context is the key datastructure for a conveniance API
379 * used for transmission of complex results to the client followed
380 * ONLY by signaling receive_done with success or error
382 struct GNUNET_SERVER_TransmitContext;
386 * Create a new transmission context for the
389 * @param client client to create the context for.
390 * @return NULL on error
392 struct GNUNET_SERVER_TransmitContext
393 *GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client
398 * Append a message to the transmission context.
399 * All messages in the context will be sent by
400 * the transmit_context_run method.
402 * @param tc context to use
403 * @param data what to append to the result message
404 * @param length length of data
405 * @param type type of the message
408 GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext
409 *tc, const void *data, size_t length,
414 * Append a message to the transmission context.
415 * All messages in the context will be sent by
416 * the transmit_context_run method.
418 * @param tc context to use
419 * @param msg message to append
422 GNUNET_SERVER_transmit_context_append_message (struct GNUNET_SERVER_TransmitContext
423 *tc, const struct GNUNET_MessageHeader *msg);
427 * Execute a transmission context. If there is
428 * an error in the transmission, the receive_done
429 * method will be called with an error code (GNUNET_SYSERR),
430 * otherwise with GNUNET_OK.
432 * @param tc transmission context to use
433 * @param timeout when to time out and abort the transmission
436 GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
437 struct GNUNET_TIME_Relative timeout);
442 * The notification context is the key datastructure for a conveniance
443 * API used for transmission of notifications to the client until the
444 * client disconnects (or the notification context is destroyed, in
445 * which case we disconnect these clients). Essentially, all
446 * (notification) messages are queued up until the client is able to
449 struct GNUNET_SERVER_NotificationContext;
453 * Create a new notification context.
455 * @param server server for which this function creates the context
456 * @param queue_length maximum number of messages to keep in
457 * the notification queue; optional messages are dropped
458 * it the queue gets longer than this number of messages
459 * @return handle to the notification context
461 struct GNUNET_SERVER_NotificationContext *
462 GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server,
463 unsigned int queue_length);
467 * Destroy the context, force disconnect for all clients.
469 * @param nc context to destroy.
472 GNUNET_SERVER_notification_context_destroy (struct GNUNET_SERVER_NotificationContext *nc);
476 * Add a client to the notification context.
478 * @param nc context to modify
479 * @param client client to add
482 GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext *nc,
483 struct GNUNET_SERVER_Client *client);
487 * Send a message to a particular client; must have
488 * already been added to the notification context.
490 * @param nc context to modify
491 * @param client client to transmit to
492 * @param msg message to send
493 * @param can_drop can this message be dropped due to queue length limitations
496 GNUNET_SERVER_notification_context_unicast (struct GNUNET_SERVER_NotificationContext *nc,
497 struct GNUNET_SERVER_Client *client,
498 const struct GNUNET_MessageHeader *msg,
503 * Send a message to all clients of this context.
505 * @param nc context to modify
506 * @param msg message to send
507 * @param can_drop can this message be dropped due to queue length limitations
510 GNUNET_SERVER_notification_context_broadcast (struct GNUNET_SERVER_NotificationContext *nc,
511 const struct GNUNET_MessageHeader *msg,
517 * Handle to a message stream tokenizer.
519 struct GNUNET_SERVER_MessageStreamTokenizer;
522 * Functions with this signature are called whenever a
523 * complete message is received by the tokenizer.
526 * @param client identification of the client
527 * @param message the actual message
529 typedef void (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls,
532 GNUNET_MessageHeader *
537 * Create a message stream tokenizer.
539 * @param cb function to call on completed messages
540 * @param cb_cls closure for cb
541 * @return handle to tokenizer
543 struct GNUNET_SERVER_MessageStreamTokenizer *
544 GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb,
549 * Add incoming data to the receive buffer and call the
550 * callback for all complete messages.
552 * @param mst tokenizer to use
553 * @param client_identity ID of client for which this is a buffer,
554 * can be NULL (will be passed back to 'cb')
555 * @param buf input data to add
556 * @param size number of bytes in buf
557 * @param purge should any excess bytes in the buffer be discarded
558 * (i.e. for packet-based services like UDP)
559 * @param one_shot only call callback once, keep rest of message in buffer
560 * @return GNUNET_OK if we are done processing (need more data)
561 * GNUNET_NO if one_shot was set and we have another message ready
562 * GNUNET_SYSERR if the data stream is corrupt
565 GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
566 void *client_identity,
574 * Destroys a tokenizer.
576 * @param mst tokenizer to destroy
579 GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
582 #if 0 /* keep Emacsens' auto-indent happy */
590 /* ifndef GNUNET_SERVER_LIB_H */
592 /* end of gnunet_server_lib.h */