#define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536
/**
- * Largest supported message.
+ * Smallest supported message.
*/
#define GNUNET_SERVER_MIN_BUFFER_SIZE sizeof (struct GNUNET_MessageHeader)
*/
struct GNUNET_SERVER_Handle;
-
/**
* @brief opaque handle for a client of the server
*/
struct GNUNET_SERVER_Client;
+/**
+ * @brief opaque handle server returns for aborting transmission to a client.
+ */
+struct GNUNET_SERVER_TransmitHandle;
+
/**
* Functions with this signature are called whenever a message is
* @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);
+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 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 (GNUNET_CONNECTION_AccessCheck
- access, void *access_cls,
- struct sockaddr *const
- *serverAddr,
- const socklen_t * socklen,
- 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);
+
+
+/**
+ * Stop the listen socket and get ready to shutdown the server
+ * once only 'monitor' clients are left.
+ *
+ * @param server server to stop listening on
+ */
+void
+GNUNET_SERVER_stop_listening (struct GNUNET_SERVER_Handle *server);
/**
* Free resources held by this server.
*
- * @param s server to destroy
+ * @param server server to destroy
*/
-void GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s);
+void
+GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *server);
/**
* the handlers array must exist until removed
* (or server is destroyed).
*/
-void GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
- const struct GNUNET_SERVER_MessageHandler
- *handlers);
+void
+GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
+ const struct GNUNET_SERVER_MessageHandler
+ *handlers);
/**
* @param callback_cls closure for callback
* @return non-NULL if the notify callback was queued; can be used
* to cancel the request using
- * GNUNET_CONNECTION_notify_transmit_ready_cancel.
+ * GNUNET_SERVER_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_SERVER_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);
+
+
+/**
+ * Abort transmission request.
+ *
+ * @param th request to abort
+ */
+void
+GNUNET_SERVER_notify_transmit_ready_cancel (struct GNUNET_SERVER_TransmitHandle *th);
+
+
+/**
+ * Set the 'monitor' flag on this client. Clients which have been
+ * marked as 'monitors' won't prevent the server from shutting down
+ * once 'GNUNET_SERVER_stop_listening' has been invoked. The idea is
+ * that for "normal" clients we likely want to allow them to process
+ * their requests; however, monitor-clients are likely to 'never'
+ * disconnect during shutdown and thus will not be considered when
+ * determining if the server should continue to exist after
+ * 'GNUNET_SERVER_destroy' has been called.
+ *
+ * @param client the client to set the 'monitor' flag on
+ */
+void
+GNUNET_SERVER_client_mark_monitor (struct GNUNET_SERVER_Client *client);
/**
*
* @param client the client to set the persistent flag on
*/
-void GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client);
+void
+GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client);
+
/**
* Resume receiving from this client, we are done processing the
* GNUNET_SYSERR to close the connection (signal
* serious error)
*/
-void GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client,
- int success);
+void
+GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success);
/**
* @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);
+void
+GNUNET_SERVER_client_set_timeout (struct GNUNET_SERVER_Client *client,
+ struct GNUNET_TIME_Relative timeout);
/**
*
* @param client client for which to disable the warning
*/
-void GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client
- *client);
+void
+GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client
+ *client);
/**
* GNUNET_SYSERR if the connection to the
* client should be shut down
*/
-int GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
- struct GNUNET_SERVER_Client *sender,
- const struct GNUNET_MessageHeader *message);
+int
+GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
+ struct GNUNET_SERVER_Client *sender,
+ const struct GNUNET_MessageHeader *message);
/**
* @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);
+struct GNUNET_SERVER_Client *
+GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server,
+ struct GNUNET_CONNECTION_Handle *connection);
/**
*
* @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);
/**
*
* @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);
/**
* @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);
/**
* 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. If the server is destroyed before this
+ * 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
* @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);
/**
* @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);
+void
+GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
+ GNUNET_SERVER_DisconnectCallback
+ callback, void *callback_cls);
/**
*
* @param client the client to disconnect from
*/
-void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
-
-
-/**
- * Configure this server's connections to continue handling client
- * requests as usual even after we get a shutdown signal. The change
- * only applies to clients that connect to the server from the outside
- * using TCP after this call. Clients managed previously or those
- * added using GNUNET_SERVER_connect_socket and
- * GNUNET_SERVER_connect_callback are not affected by this option.
- *
- * @param h server handle
- * @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);
-
+void
+GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
/**
* @param client handle to the client
* @return GNUNET_OK on success
*/
-int GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
+int
+GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
/**
* @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);
/**
* @param length length of data
* @param type type of the message
*/
-void GNUNET_SERVER_transmit_context_append_data (struct
- GNUNET_SERVER_TransmitContext
- *tc, const void *data,
- size_t length, uint16_t type);
+void
+GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext
+ *tc, const void *data,
+ size_t length, uint16_t type);
/**
* @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);
+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.
+ * 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
*/
-void GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext
- *tc,
- struct GNUNET_TIME_Relative timeout);
+void
+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);
/**
* 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);
+struct GNUNET_SERVER_NotificationContext *
+GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server,
+ unsigned int queue_length);
/**
*
* @param nc context to destroy.
*/
-void GNUNET_SERVER_notification_context_destroy (struct
- GNUNET_SERVER_NotificationContext
- *nc);
+void
+GNUNET_SERVER_notification_context_destroy (struct
+ GNUNET_SERVER_NotificationContext
+ *nc);
/**
* @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);
+void
+GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext
+ *nc,
+ struct GNUNET_SERVER_Client *client);
/**
* @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);
+void
+GNUNET_SERVER_notification_context_unicast (struct
+ GNUNET_SERVER_NotificationContext
+ *nc,
+ struct GNUNET_SERVER_Client *client,
+ const struct GNUNET_MessageHeader
+ *msg, int can_drop);
/**
* @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);
+void
+GNUNET_SERVER_notification_context_broadcast (struct
+ GNUNET_SERVER_NotificationContext
+ *nc,
+ const struct GNUNET_MessageHeader
+ *msg, int can_drop);
* Functions with this signature are called whenever a
* complete message is received by the tokenizer.
*
+ * Do not call GNUNET_SERVER_mst_destroy in callback
+ *
* @param cls closure
* @param client identification of the client
* @param message the actual message
+ *
+ * @return GNUNET_OK on success, GNUNET_SYSERR to stop further processing
*/
-typedef void (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
+typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
const struct
GNUNET_MessageHeader *
message);
* @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);
+struct GNUNET_SERVER_MessageStreamTokenizer *
+GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb,
+ void *cb_cls);
/**
* 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
+ * @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);
+int
+GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
+ void *client_identity, const char *buf, size_t size,
+ int purge, int one_shot);
/**
*
* @param mst tokenizer to destroy
*/
-void GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer
- *mst);
+void
+GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
+
+
+/**
+ * Signature of a function to create a custom tokenizer.
+ *
+ * @param cls closure from 'GNUNET_SERVER_set_callbacks'
+ * @param client handle to client the tokenzier will be used for
+ * @return handle to custom tokenizer ('mst')
+ */
+typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls,
+ struct GNUNET_SERVER_Client *client);
+
+/**
+ * Signature of a function to destroy a custom tokenizer.
+ *
+ * @param cls closure from 'GNUNET_SERVER_set_callbacks'
+ * @param mst custom tokenizer handle
+ */
+typedef void (*GNUNET_SERVER_MstDestroyCallback) (void *cls, void *mst);
+
+/**
+ * Signature of a function to destroy a custom tokenizer.
+ *
+ * @param cls closure from 'GNUNET_SERVER_set_callbacks'
+ * @param mst custom tokenizer handle
+ * @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
+ */
+typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
+ struct GNUNET_SERVER_Client *client,
+ const char *buf, size_t size,
+ int purge, int one_shot);
+
+
+/**
+ * Change functions used by the server to tokenize the message stream.
+ * (very rarely used).
+ *
+ * @param server server to modify
+ * @param create new tokenizer initialization function
+ * @param destroy new tokenizer destruction function
+ * @param receive new tokenizer receive function
+ * @param cls closure for 'create', 'receive', 'destroy'
+ */
+void
+GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
+ GNUNET_SERVER_MstCreateCallback create,
+ GNUNET_SERVER_MstDestroyCallback destroy,
+ GNUNET_SERVER_MstReceiveCallback receive,
+ void *cls);
#if 0 /* keep Emacsens' auto-indent happy */