enum GNUNET_SERVICE_Options
{
/**
- * Use defaults.
+ * Use defaults. Terminates all client connections and the listen
+ * sockets immediately upon receiving the shutdown signal.
*/
GNUNET_SERVICE_OPTION_NONE = 0,
/**
- * Do not trigger server shutdown on signals, allow for the user
- * to terminate the server explicitly when needed.
+ * Do not trigger server shutdown on signal at all; instead, allow
+ * for the user to terminate the server explicitly when needed
+ * by calling #GNUNET_SERVICE_shutdown().
*/
GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
/* **************** NEW SERVICE API ********************** */
/**
- *
+ * Handle to a service.
*/
struct GNUNET_SERVICE_Handle;
/**
- *
+ * Handle to a client that is connected to a service.
*/
struct GNUNET_SERVICE_Client;
/**
+ * Callback to initialize a service, called exactly once when the service is run.
*
- *
- * @param cls
- * @param cfg
- * @param sh
+ * @param cls closure passed to #GNUNET_SERVICE_MAIN
+ * @param cfg configuration to use for this service
+ * @param sh handle to the newly create service
*/
typedef void
(*GNUNET_SERVICE_InitCallback)(void *cls,
/**
+ * Callback to be called when a client connects to the service.
*
- *
- * @param cls
- * @param c
- * @param mq
- * @return
+ * @param cls closure for the service
+ * @param c the new client that connected to the service
+ * @param mq the message queue used to send messages to the client
+ * @return the client-specific (`internal') closure
*/
typedef void *
(*GNUNET_SERVICE_ConnectHandler)(void *cls,
/**
+ * Callback to be called when a client disconnected from the service
*
- *
- * @param cls
- * @param c
- * @param internal_cls
+ * @param cls closure for the service
+ * @param c the client that disconnected
+ * @param internal_cls the client-specific (`internal') closure
*/
typedef void
(*GNUNET_SERVICE_DisconnectHandler)(void *cls,
* dropped. Additionally, clients can be dropped at any time using
* #GNUNET_SERVICE_client_drop().
*
- * @param argc
- * @param argv
- * @param service_name
- * @param options
- * @param service_init_cb
- * @param connect_cb
- * @param disconnect_cb
- * @param cls
- * @param handlers
+ * @param argc number of command-line arguments in @a argv
+ * @param argv array of command-line arguments
+ * @param service_name name of the service to run
+ * @param options options controlling shutdown of the service
+ * @param service_init_cb function to call once the service is ready
+ * @param connect_cb function to call whenever a client connects
+ * @param disconnect_cb function to call whenever a client disconnects
+ * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
+ * @param handlers NULL-terminated array of message handlers for the service,
+ * the closure will be set to the value returned by
+ * the @a connect_cb for the respective connection
* @return 0 on success, non-zero on error
*/
int
* dropped. Additionally, clients can be dropped at any time using
* #GNUNET_SERVICE_client_drop().
*
- * @param argc
- * @param argv
- * @param service_name
- * @param options
- * @param service_init_cb
- * @param connect_cb
- * @param disconnect_cb
- * @param cls
- * @param handlers
+ * @param service_name name of the service to run
+ * @param options options controlling shutdown of the service
+ * @param service_init_cb function to call once the service is ready
+ * @param connect_cb function to call whenever a client connects
+ * @param disconnect_cb function to call whenever a client disconnects
+ * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
+ * @param ... array of message handlers for the service, terminated
+ * by #GNUNET_MQ_handler_end();
+ * the closure will be set to the value returned by
+ * the @a connect_cb for the respective connection
* @return 0 on success, non-zero on error
+ *
+ * Sample invocation:
+ * <code>
+ * GNUNET_SERVICE_MAIN
+ * ("resolver",
+ * GNUNET_SERVICE_OPTION_NONE,
+ * &init_cb,
+ * &connect_cb,
+ * &disconnect_cb,
+ * closure_for_cb,
+ * GNUNET_MQ_hd_var_size (get,
+ * GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST,
+ * struct GNUNET_RESOLVER_GetMessage,
+ * NULL),
+ * GNUNET_MQ_handler_end ());
+ * </code>
*/
-#define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,handlers) \
+#define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,...) \
int \
main (int argc,\
char *const *argv)\
{ \
+ struct GNUNET_MQ_MessageHandler mh[] = { \
+ __VA_ARGS__ \
+ }; \
return GNUNET_SERVICE_ruN_ (argc, \
argv, \
service_name, \
connect_cb, \
disconnect_cb, \
cls, \
- handlers); \
+ mh); \
}
GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c);
+/**
+ * Obtain the message queue of @a c. Convenience function.
+ *
+ * @param c the client to continue receiving from
+ * @return the message queue of @a c
+ */
+struct GNUNET_MQ_Handle *
+GNUNET_SERVICE_client_get_mq (struct GNUNET_SERVICE_Client *c);
+
+
/**
* Disable the warning the server issues if a message is not
* acknowledged in a timely fashion. Use this call if a client is
* Ask the server to disconnect from the given client. This is the
* same as returning #GNUNET_SYSERR within the check procedure when
* handling a message, wexcept that it allows dropping of a client even
- * when not handling a message from that client.
+ * when not handling a message from that client. The `disconnect_cb`
+ * will be called on @a c even if the application closes the connection
+ * using this function.
*
* @param c client to disconnect now
*/
/**
- * Stop the listen socket and get ready to shutdown the server once
- * only clients marked using #GNUNET_SERVER_client_mark_monitor are
- * left.
+ * Explicitly stops the service.
*
- * @param sh server to stop listening on
+ * @param sh server to shutdown
*/
void
-GNUNET_SERVICE_stop_listening (struct GNUNET_SERVICE_Handle *sh);
+GNUNET_SERVICE_shutdown (struct GNUNET_SERVICE_Handle *sh);
/**
projects / oweals / gnunet.git / blobdiff