X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_arm_service.h;h=e1f44620f611803fe6f64fcbf612a479ff9de8c7;hb=27c12911f4f2aba2d90099270d70de846e83854f;hp=8e68cd5ee2fdcf796029710daba45d44def41448;hpb=d75fb1880a887a8f5339c5e8cf5e9d2b8755fdad;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_arm_service.h b/src/include/gnunet_arm_service.h index 8e68cd5ee..e1f44620f 100644 --- a/src/include/gnunet_arm_service.h +++ b/src/include/gnunet_arm_service.h @@ -4,7 +4,7 @@ GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your + by the Free Software Foundation; either version 3, or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but @@ -35,133 +35,312 @@ extern "C" #endif #endif -#include "gnunet_configuration_lib.h" -#include "gnunet_scheduler_lib.h" -#include "gnunet_time_lib.h" +#include "gnunet_util_lib.h" /** * Version of the arm API. */ -#define GNUNET_ARM_VERSION 0x00000000 +#define GNUNET_ARM_VERSION 0x00000002 /** - * Callback function invoked when operation is complete. - * - * @param cls closure - * @param success GNUNET_YES if we think the service is running - * GNUNET_NO if we think the service is stopped - * GNUNET_SYSERR if we think ARM was not running or - * if the service status is unknown + * Statuses of the requests that client can send to ARM. */ -typedef void (*GNUNET_ARM_Callback) (void *cls, int success); +enum GNUNET_ARM_RequestStatus +{ + /** + * Message was sent successfully. + */ + GNUNET_ARM_REQUEST_SENT_OK = 0, + + /** + * Misconfiguration (can't connect to the ARM service). + */ + GNUNET_ARM_REQUEST_CONFIGURATION_ERROR = 1, + + /** + * We disconnected from ARM, and request was not sent. + */ + GNUNET_ARM_REQUEST_DISCONNECTED = 2, + + /** + * ARM API is busy (probably trying to connect to ARM), + * and request was not sent. Try again later. + */ + GNUNET_ARM_REQUEST_BUSY = 3, + + /** + * It was discovered that the request would be too long to fit in a message, + * and thus it was not sent. + */ + GNUNET_ARM_REQUEST_TOO_LONG = 4, + + /** + * Request time ran out before we had a chance to send it. + */ + GNUNET_ARM_REQUEST_TIMEOUT = 5 + +}; + + +/** + * Statuses of services. + */ +enum GNUNET_ARM_ServiceStatus +{ + /** + * Dummy message. + */ + GNUNET_ARM_SERVICE_MONITORING_STARTED = 0, + + /** + * Service was stopped. + */ + GNUNET_ARM_SERVICE_STOPPED = 1, + + /** + * Service starting was initiated + */ + GNUNET_ARM_SERVICE_STARTING = 2, + + /** + * Service stopping was initiated + */ + GNUNET_ARM_SERVICE_STOPPING = 3 +}; + + +/** + * Replies to ARM requests + */ +enum GNUNET_ARM_Result +{ + /** + * Service was stopped (never sent for ARM itself). + */ + GNUNET_ARM_RESULT_STOPPED = 0, + + /** + * ARM stopping was initiated (there's no "stopped" for ARM itself). + */ + GNUNET_ARM_RESULT_STOPPING = 1, + + /** + * Service starting was initiated + */ + GNUNET_ARM_RESULT_STARTING = 2, + + /** + * Asked to start it, but it's already starting. + */ + GNUNET_ARM_RESULT_IS_STARTING_ALREADY = 3, + + /** + * Asked to stop it, but it's already stopping. + */ + GNUNET_ARM_RESULT_IS_STOPPING_ALREADY = 4, + + /** + * Asked to start it, but it's already started. + */ + GNUNET_ARM_RESULT_IS_STARTED_ALREADY = 5, + + /** + * Asked to stop it, but it's already stopped. + */ + GNUNET_ARM_RESULT_IS_STOPPED_ALREADY = 6, + + /** + * Asked to start or stop a service, but it's not known. + */ + GNUNET_ARM_RESULT_IS_NOT_KNOWN = 7, + + /** + * Tried to start a service, but that failed for some reason. + */ + GNUNET_ARM_RESULT_START_FAILED = 8, + + /** + * Asked to start something, but ARM is shutting down and can't comply. + */ + GNUNET_ARM_RESULT_IN_SHUTDOWN = 9 +}; /** * Handle for interacting with ARM. - */ + */ struct GNUNET_ARM_Handle; /** - * Setup a context for communicating with ARM. Note that this - * can be done even if the ARM service is not yet running. + * Function called whenever we connect to or disconnect from ARM. + * + * @param cls closure + * @param connected GNUNET_YES if connected, GNUNET_NO if disconnected, + * GNUNET_SYSERR if there was an error. + */ +typedef void (*GNUNET_ARM_ConnectionStatusCallback) (void *cls, + int connected); + + +/** + * Function called in response to a start/stop request. + * Will be called when request was not sent successfully, + * or when a reply comes. If the request was not sent successfully, + * 'rs' will indicate that, and 'service' and 'result' will be undefined. + * + * @param cls closure + * @param rs status of the request + * @param service service name + * @param result result of the operation + */ +typedef void (*GNUNET_ARM_ResultCallback) (void *cls, + enum GNUNET_ARM_RequestStatus rs, + const char *service, + enum GNUNET_ARM_Result result); + + +/** + * Callback function invoked when list operation is complete. + * Will be called when request was not sent successfully, + * or when a reply comes. If the request was not sent successfully, + * 'rs' will indicate that, and 'count' and 'list' will be undefined. + * + * @param cls closure + * @param rs status of the request + * @param count number of strings in the list + * @param list list of running services + */ +typedef void (*GNUNET_ARM_ServiceListCallback) (void *cls, + enum GNUNET_ARM_RequestStatus rs, + unsigned int count, + const char *const*list); + + +/** + * Set up a context for communicating with ARM, then + * start connecting to the ARM service using that context. * * @param cfg configuration to use (needed to contact ARM; * the ARM service may internally use a different * configuration to determine how to start the service). - * @param sched scheduler to use - * @param service service that *this* process is implementing/providing, can be NULL - * @return context to use for further ARM operations, NULL on error + * @param conn_status will be called when connecting/disconnecting + * @param cls closure for conn_status + * @return context to use for further ARM operations, NULL on error. */ struct GNUNET_ARM_Handle * GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_SCHEDULER_Handle *sched, - const char *service); + GNUNET_ARM_ConnectionStatusCallback conn_status, + void *cls); /** - * Disconnect from the ARM service. + * Disconnect from the ARM service and destroy the handle. * * @param h the handle that was being used */ void -GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h); +GNUNET_ARM_disconnect_and_free (struct GNUNET_ARM_Handle *h); /** - * Start a service. Note that this function merely asks ARM to start - * the service and that ARM merely confirms that it forked the - * respective process. The specified callback may thus return before - * the service has started to listen on the server socket and it may - * also be that the service has crashed in the meantime. Clients - * should repeatedly try to connect to the service at the respective - * port (with some delays in between) before assuming that the service - * actually failed to start. Note that if an error is returned to the - * callback, clients obviously should not bother with trying to - * contact the service. + * Request a list of running services. * * @param h handle to ARM - * @param service_name name of the service * @param timeout how long to wait before failing for good - * @param cb callback to invoke when service is ready - * @param cb_cls closure for callback + * @param cont callback to invoke after request is sent or is not sent + * @param cont_cls closure for callback */ void -GNUNET_ARM_start_service (struct GNUNET_ARM_Handle *h, - const char *service_name, - struct GNUNET_TIME_Relative timeout, - GNUNET_ARM_Callback cb, void *cb_cls); +GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h, + struct GNUNET_TIME_Relative timeout, + GNUNET_ARM_ServiceListCallback cont, void *cont_cls); /** - * Stop a service. Note that the callback is invoked as soon - * as ARM confirms that it will ask the service to terminate. - * The actual termination may still take some time. + * Request a service to be stopped. + * Stopping arm itself will not invalidate its handle, and + * ARM API will try to restore connection to the ARM service, + * even if ARM connection was lost because you asked for ARM to be stopped. + * Call GNUNET_ARM_disconnect_and_free () to free the handle and prevent + * further connection attempts. * * @param h handle to ARM * @param service_name name of the service * @param timeout how long to wait before failing for good - * @param cb callback to invoke when service is ready - * @param cb_cls closure for callback + * @param cont callback to invoke after request is sent or is not sent + * @param cont_cls closure for callback */ void -GNUNET_ARM_stop_service (struct GNUNET_ARM_Handle *h, - const char *service_name, - struct GNUNET_TIME_Relative timeout, - GNUNET_ARM_Callback cb, void *cb_cls); +GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h, + const char *service_name, + struct GNUNET_TIME_Relative timeout, + GNUNET_ARM_ResultCallback cont, void *cont_cls); /** - * Start multiple services in the specified order. Convenience - * function. Works asynchronously, failures are not reported. + * Request for a service to be started. * - * @param cfg configuration to use (needed to contact ARM; - * the ARM service may internally use a different - * configuration to determine how to start the service). - * @param sched scheduler to use - * @param ... NULL-terminated list of service names (const char*) + * @param h handle to ARM + * @param service_name name of the service + * @param std_inheritance inheritance of std streams + * @param timeout how long to wait before failing for good + * @param cont callback to invoke after request is sent or not sent + * @param cont_cls closure for callback */ void -GNUNET_ARM_start_services (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_SCHEDULER_Handle *sched, - ...); +GNUNET_ARM_request_service_start (struct GNUNET_ARM_Handle *h, + const char *service_name, + enum GNUNET_OS_InheritStdioFlags std_inheritance, + struct GNUNET_TIME_Relative timeout, + GNUNET_ARM_ResultCallback cont, + void *cont_cls); + + +/** + * Handle for monitoring ARM. + */ +struct GNUNET_ARM_MonitorHandle; + + +/** + * Function called in when a status update arrives. + * + * @param cls closure + * @param arm handle to the arm connection + * @param service service name + * @param status status of the service + */ +typedef void (*GNUNET_ARM_ServiceStatusCallback) (void *cls, + const char *service, + enum GNUNET_ARM_ServiceStatus status); /** - * Stop multiple services in the specified order. Convenience - * function. Works asynchronously, failures are not reported. + * Setup a context for monitoring ARM, then + * start connecting to the ARM service for monitoring using that context. * * @param cfg configuration to use (needed to contact ARM; * the ARM service may internally use a different * configuration to determine how to start the service). - * @param sched scheduler to use - * @param ... NULL-terminated list of service names (const char*) + * @param cont callback to invoke on status updates + * @param cont_cls closure + * @return context to use for further ARM monitor operations, NULL on error. + */ +struct GNUNET_ARM_MonitorHandle * +GNUNET_ARM_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_ARM_ServiceStatusCallback cont, + void *cont_cls); + + +/** + * Disconnect from the ARM service and destroy the handle. + * + * @param h the handle that was being used */ void -GNUNET_ARM_stop_services (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_SCHEDULER_Handle *sched, - ...); +GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h); #if 0 /* keep Emacsens' auto-indent happy */