X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_server_lib.h;h=2856fd8388343495fa1ce21b1b03609df2f85d7c;hb=66ffc809472f27d69b9ad7361f8ba29c2674f716;hp=ecfead5ab84fd51e5e95b473f814ccd15923b0c8;hpb=ce4aeaac8ee95b33948fa195a92fc8e83554cea8;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_server_lib.h b/src/include/gnunet_server_lib.h index ecfead5ab..2856fd838 100644 --- a/src/include/gnunet_server_lib.h +++ b/src/include/gnunet_server_lib.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2009 Christian Grothoff (and other contributing authors) + (C) 2009, 2010 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -38,7 +38,6 @@ extern "C" #include "gnunet_common.h" #include "gnunet_connection_lib.h" -#include "gnunet_scheduler_lib.h" /** @@ -46,6 +45,10 @@ extern "C" */ #define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536 +/** + * Smallest supported message. + */ +#define GNUNET_SERVER_MIN_BUFFER_SIZE sizeof (struct GNUNET_MessageHeader) /** * @brief handle for a server @@ -70,9 +73,8 @@ struct GNUNET_SERVER_Client; typedef void (*GNUNET_SERVER_MessageCallback) (void *cls, struct GNUNET_SERVER_Client * client, - const struct - GNUNET_MessageHeader * - message); + const struct GNUNET_MessageHeader + * message); @@ -111,35 +113,50 @@ struct GNUNET_SERVER_MessageHandler /** * Create a new server. * - * @param sched scheduler to use + * @param access function for access control + * @param access_cls closure for access + * @param lsocks NULL-terminated array of listen sockets + * @param idle_timeout after how long should we timeout idle connections? + * @param require_found if YES, connections sending messages of unknown type + * will be closed + * @return handle for the new server, NULL on error + * (typically, "port" already in use) + */ +struct GNUNET_SERVER_Handle * +GNUNET_SERVER_create_with_sockets (GNUNET_CONNECTION_AccessCheck access, + void *access_cls, + struct GNUNET_NETWORK_Handle **lsocks, + struct GNUNET_TIME_Relative idle_timeout, + int require_found); + +/** + * Create a new server. + * * @param access function for access control * @param access_cls closure for access * @param serverAddr address toes listen on (including port), NULL terminated array - * @param socklen lengths of respective serverAddr - * @param maxbuf maximum write buffer size for accepted sockets + * @param socklen lengths of respective serverAddr * @param idle_timeout after how long should we timeout idle connections? * @param require_found if YES, connections sending messages of unknown type * will be closed * @return handle for the new server, NULL on error * (typically, "port" already in use) */ -struct GNUNET_SERVER_Handle *GNUNET_SERVER_create (struct - GNUNET_SCHEDULER_Handle - *sched, - GNUNET_CONNECTION_AccessCheck - access, void *access_cls, - struct sockaddr *const*serverAddr, - const socklen_t *socklen, - size_t maxbuf, - struct GNUNET_TIME_Relative - idle_timeout, - int require_found); +struct GNUNET_SERVER_Handle * +GNUNET_SERVER_create (GNUNET_CONNECTION_AccessCheck access, void *access_cls, + struct sockaddr *const *serverAddr, + const socklen_t * socklen, + struct GNUNET_TIME_Relative idle_timeout, + int require_found); /** * Free resources held by this server. + * + * @param s server to destroy */ -void GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s); +void +GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s); /** @@ -176,13 +193,22 @@ GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server, * GNUNET_CONNECTION_notify_transmit_ready_cancel. * NULL if we are already going to notify someone else (busy) */ -struct GNUNET_CONNECTION_TransmitHandle - *GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client, - size_t size, - struct GNUNET_TIME_Relative timeout, - GNUNET_CONNECTION_TransmitReadyNotify - callback, void *callback_cls); +struct GNUNET_CONNECTION_TransmitHandle * +GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client, + size_t size, + struct GNUNET_TIME_Relative timeout, + GNUNET_CONNECTION_TransmitReadyNotify + callback, void *callback_cls); + +/** + * Set the persistent flag on this client, used to setup client connection + * to only be killed when the service it's connected to is actually dead. + * + * @param client the client to set the persistent flag on + */ +void +GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client); /** * Resume receiving from this client, we are done processing the @@ -192,6 +218,7 @@ struct GNUNET_CONNECTION_TransmitHandle * @param client client we were processing a message of * @param success GNUNET_OK to keep the connection open and * continue to receive + * GNUNET_NO to close the connection (normal behavior) * GNUNET_SYSERR to close the connection (signal * serious error) */ @@ -199,6 +226,31 @@ void GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success); +/** + * Change the timeout for a particular client. Decreasing the timeout + * may not go into effect immediately (only after the previous timeout + * times out or activity happens on the socket). + * + * @param client the client to update + * @param timeout new timeout for activities on the socket + */ +void +GNUNET_SERVER_client_set_timeout (struct GNUNET_SERVER_Client *client, + struct GNUNET_TIME_Relative timeout); + + +/** + * Disable the warning the server issues if a message is not acknowledged + * in a timely fashion. Use this call if a client is intentionally delayed + * for a while. Only applies to the current message. + * + * @param client client for which to disable the warning + */ +void +GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client + *client); + + /** * Inject a message into the server, pretend it came * from the specified client. Delivery of the message @@ -232,125 +284,9 @@ GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server, * @return the client handle (client should call * "client_drop" on the return value eventually) */ -struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_socket (struct - GNUNET_SERVER_Handle - *server, - struct - GNUNET_CONNECTION_Handle - *connection); - - -/** - * Receive data from the given connection. This function should call - * "receiver" asynchronously using the scheduler. It must return - * "immediately". - * - * @param cls closure - * @param sched scheduler to use - * @param max maximum number of bytes to read - * @param timeout maximum amount of time to wait (use -1 for "forever") - * @param receiver function to call with received data - * @param receiver_cls closure for receiver - */ -typedef void - (*GNUNET_SERVER_ReceiveCallback) (void *cls, - size_t max, - struct GNUNET_TIME_Relative timeout, - GNUNET_CONNECTION_Receiver - receiver, void *receiver_cls); - - -/** - * Cancel receive request. - * - * @param cls closure - */ -typedef void (*GNUNET_SERVER_ReceiveCancelCallback) (void *cls); - - -/** - * Notify us when the connection is ready to transmit size bytes. - * - * @param cls closure - * @param size number of bytes to be ready for sending - * @param timeout after how long should we give up (and call - * notify with buf NULL and size 0)? - * @param notify function to call - * @param notify_cls closure for notify - * @return a handle that can be used to cancel - * the transmission request or NULL if - * queueing a transmission request failed - */ -typedef void *(*GNUNET_SERVER_TransmitReadyCallback) (void *cls, - size_t size, - struct - GNUNET_TIME_Relative - timeout, - GNUNET_CONNECTION_TransmitReadyNotify - notify, - void *notify_cls); - - -/** - * Cancel an earlier transmit notification request. - * - * @param cls closure - * @param ctx handle that was returned by the TransmitReadyCallback - */ -typedef void (*GNUNET_SERVER_TransmitReadyCancelCallback) (void *cls, - void *ctx); - - -/** - * Check if connection is still valid (no fatal errors have happened so far). - * - * @param cls closure - * @return GNUNET_YES if valid, GNUNET_NO otherwise - */ -typedef int (*GNUNET_SERVER_CheckCallback) (void *cls); - - -/** - * Destroy this connection (free resources). - * - * @param cls closure - */ -typedef void (*GNUNET_SERVER_DestroyCallback) (void *cls); - - -/** - * Add an arbitrary connection to the set of handles managed by this - * server. This can be used if a sending and receiving does not - * really go over the network (internal transmission) or for servers - * using UDP. - * - * @param server the server to use - * @param chandle opaque handle for the connection - * @param creceive receive function for the connection - * @param ccancel cancel receive function for the connection - * @param cnotify transmit notification function for the connection - * @param cnotify_cancel transmit notification cancellation function for the connection - * @param ccheck function to test if the connection is still up - * @param cdestroy function to close and free the connection - * @return the client handle (client should call - * "client_drop" on the return value eventually) - */ -struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_callback (struct - GNUNET_SERVER_Handle - *server, - void *chandle, - GNUNET_SERVER_ReceiveCallback - creceive, - GNUNET_SERVER_ReceiveCancelCallback - ccancel, - GNUNET_SERVER_TransmitReadyCallback - cnotify, - GNUNET_SERVER_TransmitReadyCancelCallback - cnotify_cancel, - GNUNET_SERVER_CheckCallback - ccheck, - GNUNET_SERVER_DestroyCallback - cdestroy); +struct GNUNET_SERVER_Client * +GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server, + struct GNUNET_CONNECTION_Handle *connection); /** @@ -360,7 +296,8 @@ struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_callback (struct * * @param client the client to keep */ -void GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client); +void +GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client); /** @@ -371,7 +308,8 @@ void GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client); * * @param client the client to drop */ -void GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client); +void +GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client); /** @@ -382,8 +320,9 @@ void GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client); * @param addrlen where to store the length of the address * @return GNUNET_OK on success */ -int GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client, - void **addr, size_t * addrlen); +int +GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client, + void **addr, size_t * addrlen); /** @@ -391,26 +330,45 @@ int GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client, * is disconnected on the network level. * * @param cls closure - * @param client identification of the client + * @param client identification of the client; NULL + * for the last call when the server is destroyed */ typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls, - struct GNUNET_SERVER_Client - * client); + struct GNUNET_SERVER_Client * + client); /** * Ask the server to notify us whenever a client disconnects. * This function is called whenever the actual network connection * is closed; the reference count may be zero or larger than zero - * at this point. + * at this point. If the server is destroyed before this + * notification is explicitly cancelled, the 'callback' will + * once be called with a 'client' argument of NULL to indicate + * that the server itself is now gone (and that the callback + * won't be called anymore and also can no longer be cancelled). * * @param server the server manageing the clients * @param callback function to call on disconnect * @param callback_cls closure for callback */ -void GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server, - GNUNET_SERVER_DisconnectCallback - callback, void *callback_cls); +void +GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server, + GNUNET_SERVER_DisconnectCallback callback, + void *callback_cls); + + +/** + * Ask the server to stop notifying us whenever a client disconnects. + * + * @param server the server manageing the clients + * @param callback function to call on disconnect + * @param callback_cls closure for callback + */ +void +GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server, + GNUNET_SERVER_DisconnectCallback + callback, void *callback_cls); /** @@ -421,7 +379,8 @@ void GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server, * * @param client the client to disconnect from */ -void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client); +void +GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client); /** @@ -436,8 +395,20 @@ void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client); * @param do_ignore GNUNET_YES to ignore, GNUNET_NO to restore default */ void -GNUNET_SERVER_ignore_shutdown (struct GNUNET_SERVER_Handle *h, - int do_ignore); +GNUNET_SERVER_ignore_shutdown (struct GNUNET_SERVER_Handle *h, int do_ignore); + + + +/** + * Disable the "CORK" feature for communication with the given client, + * forcing the OS to immediately flush the buffer on transmission + * instead of potentially buffering multiple messages. + * + * @param client handle to the client + * @return GNUNET_OK on success + */ +int +GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client); /** @@ -455,9 +426,8 @@ struct GNUNET_SERVER_TransmitContext; * @param client client to create the context for. * @return NULL on error */ -struct GNUNET_SERVER_TransmitContext - *GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client - *client); +struct GNUNET_SERVER_TransmitContext * +GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client *client); /** @@ -471,15 +441,31 @@ struct GNUNET_SERVER_TransmitContext * @param type type of the message */ void -GNUNET_SERVER_transmit_context_append (struct GNUNET_SERVER_TransmitContext - *tc, const void *data, size_t length, - uint16_t type); +GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext + *tc, const void *data, + size_t length, uint16_t type); + /** - * Execute a transmission context. If there is - * an error in the transmission, the receive_done - * method will be called with an error code (GNUNET_SYSERR), - * otherwise with GNUNET_OK. + * Append a message to the transmission context. + * All messages in the context will be sent by + * the transmit_context_run method. + * + * @param tc context to use + * @param msg message to append + */ +void +GNUNET_SERVER_transmit_context_append_message (struct + GNUNET_SERVER_TransmitContext + *tc, + const struct GNUNET_MessageHeader + *msg); + + +/** + * Execute a transmission context. If there is an error in the + * transmission, the receive_done method will be called with an error + * code (GNUNET_SYSERR), otherwise with GNUNET_OK. * * @param tc transmission context to use * @param timeout when to time out and abort the transmission @@ -489,6 +475,166 @@ GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc, struct GNUNET_TIME_Relative timeout); +/** + * Destroy a transmission context. This function must not be called + * after 'GNUNET_SERVER_transmit_context_run'. + * + * @param tc transmission context to destroy + * @param success code to give to 'GNUNET_SERVER_receive_done' for + * the client: GNUNET_OK to keep the connection open and + * continue to receive + * GNUNET_NO to close the connection (normal behavior) + * GNUNET_SYSERR to close the connection (signal + * serious error) + */ +void +GNUNET_SERVER_transmit_context_destroy (struct GNUNET_SERVER_TransmitContext + *tc, int success); + + +/** + * The notification context is the key datastructure for a conveniance + * API used for transmission of notifications to the client until the + * client disconnects (or the notification context is destroyed, in + * which case we disconnect these clients). Essentially, all + * (notification) messages are queued up until the client is able to + * read them. + */ +struct GNUNET_SERVER_NotificationContext; + + +/** + * Create a new notification context. + * + * @param server server for which this function creates the context + * @param queue_length maximum number of messages to keep in + * the notification queue; optional messages are dropped + * if the queue gets longer than this number of messages + * @return handle to the notification context + */ +struct GNUNET_SERVER_NotificationContext * +GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server, + unsigned int queue_length); + + +/** + * Destroy the context, force disconnect for all clients. + * + * @param nc context to destroy. + */ +void +GNUNET_SERVER_notification_context_destroy (struct + GNUNET_SERVER_NotificationContext + *nc); + + +/** + * Add a client to the notification context. + * + * @param nc context to modify + * @param client client to add + */ +void +GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext + *nc, + struct GNUNET_SERVER_Client *client); + + +/** + * Send a message to a particular client; must have + * already been added to the notification context. + * + * @param nc context to modify + * @param client client to transmit to + * @param msg message to send + * @param can_drop can this message be dropped due to queue length limitations + */ +void +GNUNET_SERVER_notification_context_unicast (struct + GNUNET_SERVER_NotificationContext + *nc, + struct GNUNET_SERVER_Client *client, + const struct GNUNET_MessageHeader + *msg, int can_drop); + + +/** + * Send a message to all clients of this context. + * + * @param nc context to modify + * @param msg message to send + * @param can_drop can this message be dropped due to queue length limitations + */ +void +GNUNET_SERVER_notification_context_broadcast (struct + GNUNET_SERVER_NotificationContext + *nc, + const struct GNUNET_MessageHeader + *msg, int can_drop); + + + +/** + * Handle to a message stream tokenizer. + */ +struct GNUNET_SERVER_MessageStreamTokenizer; + +/** + * Functions with this signature are called whenever a + * complete message is received by the tokenizer. + * + * @param cls closure + * @param client identification of the client + * @param message the actual message + */ +typedef void (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client, + const struct + GNUNET_MessageHeader * + message); + + +/** + * Create a message stream tokenizer. + * + * @param cb function to call on completed messages + * @param cb_cls closure for cb + * @return handle to tokenizer + */ +struct GNUNET_SERVER_MessageStreamTokenizer * +GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb, + void *cb_cls); + + +/** + * Add incoming data to the receive buffer and call the + * callback for all complete messages. + * + * @param mst tokenizer to use + * @param client_identity ID of client for which this is a buffer, + * can be NULL (will be passed back to 'cb') + * @param buf input data to add + * @param size number of bytes in buf + * @param purge should any excess bytes in the buffer be discarded + * (i.e. for packet-based services like UDP) + * @param one_shot only call callback once, keep rest of message in buffer + * @return GNUNET_OK if we are done processing (need more data) + * GNUNET_NO if one_shot was set and we have another message ready + * GNUNET_SYSERR if the data stream is corrupt + */ +int +GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst, + void *client_identity, const char *buf, size_t size, + int purge, int one_shot); + + +/** + * Destroys a tokenizer. + * + * @param mst tokenizer to destroy + */ +void +GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst); + #if 0 /* keep Emacsens' auto-indent happy */ {