/*
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
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
#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
/**
*/
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_SERVICE_STOPPING = 3
};
+
/**
* Replies to ARM requests
*/
*/
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
- * @param error GNUNET_YES if we encountered a permanent error, and there
- * will be no re-connection.
+ * @param connected #GNUNET_YES if connected, #GNUNET_NO if disconnected,
+ * #GNUNET_SYSERR if there was an error.
*/
-typedef void (*GNUNET_ARM_ConnectionStatusCallback) (void *cls, struct GNUNET_ARM_Handle *arm, unsigned char connected, unsigned char 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.
+ * @a rs will indicate that, and @a result will be undefined.
*
* @param cls closure
- * @param arm handle to the arm connection
* @param rs status of the request
- * @param service service name
* @param result result of the operation
*/
-typedef void (*GNUNET_ARM_ResultCallback) (void *cls, struct GNUNET_ARM_Handle *arm, 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 arm handle to the arm connection
* @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, struct GNUNET_ARM_Handle *arm, 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);
/**
- * Setup a context for communicating with ARM. Note that this
- * can be done even if the ARM service is not yet running.
- * Never fails.
+ * 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).
- * @return context to use for further ARM operations
+ * @param conn_status will be called when connecting/disconnecting
+ * @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_alloc (const struct GNUNET_CONFIGURATION_Handle *cfg);
+GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ GNUNET_ARM_ConnectionStatusCallback conn_status,
+ void *conn_status_cls);
+
/**
- * Start connecting to the ARM service using the context.
- * @param conn_status called when we (dis)connect from/to ARM.
- * It's also called on connection errors.
- * @param cls closure for conn_status
+ * Disconnect from the ARM service and destroy the handle.
*
- * @param h ARM handle
+ * @param h the handle that was being used
*/
void
-GNUNET_ARM_connect (struct GNUNET_ARM_Handle *h,
- GNUNET_ARM_ConnectionStatusCallback conn_status, void *cls);
+GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h);
/**
- * Disconnect from the ARM service and destroy the handle.
- * Don't call this from inside an ARM callback!
+ * Abort an operation. Only prevents the callback from being
+ * called, the operation may still complete.
*
- * @param h the handle that was being used
+ * @param op operation to cancel
*/
void
-GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h);
+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);
/**
* 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 () 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);
/**
* @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);
/**
* 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, struct GNUNET_ARM_MonitorHandle *arm, const char *service, enum GNUNET_ARM_ServiceStatus status);
+typedef void
+(*GNUNET_ARM_ServiceStatusCallback) (void *cls,
+ const char *service,
+ enum GNUNET_ARM_ServiceStatus status);
/**
- * Setup a context for monitoring ARM. Note that this
- * can be done even if the ARM service is not yet running.
- * Never fails.
+ * 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).
- * @return context to use for further ARM monitor operations
- */
-struct GNUNET_ARM_MonitorHandle *
-GNUNET_ARM_monitor_alloc (const struct GNUNET_CONFIGURATION_Handle *cfg);
-
-/**
- * Start connecting to the ARM service for monitoring using the context.
- *
- * @param h ARM monitor handle
* @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.
*/
-void
-GNUNET_ARM_monitor (struct GNUNET_ARM_MonitorHandle *h,
- GNUNET_ARM_ServiceStatusCallback cont, void *cont_cls);
+struct GNUNET_ARM_MonitorHandle *
+GNUNET_ARM_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ GNUNET_ARM_ServiceStatusCallback cont,
+ void *cont_cls);
/**
* Disconnect from the ARM service and destroy the handle.
- * Don't call this from inside an ARM callback!
*
* @param h the handle that was being used
*/
void
-GNUNET_ARM_monitor_disconnect (struct GNUNET_ARM_MonitorHandle *h);
-
+GNUNET_ARM_monitor_stop (struct GNUNET_ARM_MonitorHandle *h);
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
#endif
+
+/** @} */ /* end of group */
projects / oweals / gnunet.git / blobdiff