X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_arm_service.h;h=f8d71bd8b551f498e6ba07d9734ff5f962204117;hb=3f52ce03cb13118bef9a6fbe380f229e2cbec45f;hp=44e47affce1a5a47959a55ade007fdb9922728c2;hpb=08676aaa5b76a0723c8c60ee510aec3652e50774;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_arm_service.h b/src/include/gnunet_arm_service.h index 44e47affc..f8d71bd8b 100644 --- a/src/include/gnunet_arm_service.h +++ b/src/include/gnunet_arm_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - (C) 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2009, 2016 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -14,14 +14,22 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** - * @file include/gnunet_arm_service.h - * @brief API to access gnunet-arm * @author Christian Grothoff + * + * @file + * API to access gnunet-arm + * + * @defgroup arm ARM service + * Automatic Restart Manager + * + * @see [Documentation](https://gnunet.org/arm) + * + * @{ */ #ifndef GNUNET_ARM_SERVICE_H @@ -35,15 +43,12 @@ extern "C" #endif #endif -#include "gnunet_configuration_lib.h" -#include "gnunet_scheduler_lib.h" -#include "gnunet_os_lib.h" -#include "gnunet_time_lib.h" +#include "gnunet_util_lib.h" /** * Version of the arm API. */ -#define GNUNET_ARM_VERSION 0x00000002 +#define GNUNET_ARM_VERSION 0x00000003 /** @@ -56,32 +61,10 @@ enum GNUNET_ARM_RequestStatus */ 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 + GNUNET_ARM_REQUEST_DISCONNECTED = 2 }; @@ -112,6 +95,7 @@ enum GNUNET_ARM_ServiceStatus GNUNET_ARM_SERVICE_STOPPING = 3 }; + /** * Replies to ARM requests */ @@ -174,50 +158,56 @@ enum GNUNET_ARM_Result */ struct GNUNET_ARM_Handle; +/** + * Handle for an ARM operation. + */ +struct GNUNET_ARM_Operation; + /** * 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. + * @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); +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. + * @a rs will indicate that, and @a 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); +typedef void +(*GNUNET_ARM_ResultCallback) (void *cls, + enum GNUNET_ARM_RequestStatus rs, + 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. + * @a rs will indicate that, and @a count and @a 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); +typedef void +(*GNUNET_ARM_ServiceListCallback) (void *cls, + enum GNUNET_ARM_RequestStatus rs, + unsigned int count, + const char *const*list); /** @@ -228,13 +218,13 @@ typedef void (*GNUNET_ARM_ServiceListCallback) (void *cls, * the ARM service may internally use a different * configuration to determine how to start the service). * @param conn_status will be called when connecting/disconnecting - * @param cls closure for conn_status + * @param conn_status_cls closure for @a 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, - GNUNET_ARM_ConnectionStatusCallback conn_status, - void *cls); + GNUNET_ARM_ConnectionStatusCallback conn_status, + void *conn_status_cls); /** @@ -243,21 +233,31 @@ GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, * @param h the handle that was being used */ void -GNUNET_ARM_disconnect_and_free (struct GNUNET_ARM_Handle *h); +GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h); + + +/** + * Abort an operation. Only prevents the callback from being + * called, the operation may still complete. + * + * @param op operation to cancel + */ +void +GNUNET_ARM_operation_cancel (struct GNUNET_ARM_Operation *op); /** * Request a list of running services. * * @param h handle to ARM - * @param timeout how long to wait before failing for good * @param cont callback to invoke after request is sent or is not sent - * @param cont_cls closure for callback + * @param cont_cls closure for @a cont + * @return handle for the operation, NULL on error */ -void +struct GNUNET_ARM_Operation * GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h, - struct GNUNET_TIME_Relative timeout, - GNUNET_ARM_ServiceListCallback cont, void *cont_cls); + GNUNET_ARM_ServiceListCallback cont, + void *cont_cls); /** @@ -265,20 +265,20 @@ GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h, * 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 + * Call #GNUNET_ARM_disconnect() 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 cont callback to invoke after request is sent or is not sent - * @param cont_cls closure for callback + * @param cont_cls closure for @a cont + * @return handle for the operation, NULL on error */ -void +struct GNUNET_ARM_Operation * 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); + const char *service_name, + GNUNET_ARM_ResultCallback cont, + void *cont_cls); /** @@ -287,15 +287,16 @@ GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h, * @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 + * @param cont_cls closure for @a cont + * @return handle for the operation, NULL on error */ -void +struct GNUNET_ARM_Operation * 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); + const char *service_name, + enum GNUNET_OS_InheritStdioFlags std_inheritance, + GNUNET_ARM_ResultCallback cont, + void *cont_cls); /** @@ -308,13 +309,13 @@ 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); +typedef void +(*GNUNET_ARM_ServiceStatusCallback) (void *cls, + const char *service, + enum GNUNET_ARM_ServiceStatus status); /** @@ -325,13 +326,13 @@ typedef void (*GNUNET_ARM_ServiceStatusCallback) (void *cls, * the ARM service may internally use a different * configuration to determine how to start the service). * @param cont callback to invoke on status updates - * @param cont_cls closure + * @param cont_cls closure for @a cont * @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); +GNUNET_ARM_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_ARM_ServiceStatusCallback cont, + void *cont_cls); /** @@ -340,8 +341,7 @@ GNUNET_ARM_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg, * @param h the handle that was being used */ void -GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h); - +GNUNET_ARM_monitor_stop (struct GNUNET_ARM_MonitorHandle *h); #if 0 /* keep Emacsens' auto-indent happy */ { @@ -351,3 +351,5 @@ GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h); #endif #endif + +/** @} */ /* end of group */