Merge branch 'master' of git+ssh://gnunet.org/gnunet

[oweals/gnunet.git] / src / include / gnunet_arm_service.h

diff --git a/src/include/gnunet_arm_service.h b/src/include/gnunet_arm_service.h
index bbb8cb0f6aacec8f203fee4226a1a04ce74f908a..f8d71bd8b551f498e6ba07d9734ff5f962204117 100644 (file)
--- a/src/include/gnunet_arm_service.h
+++ b/src/include/gnunet_arm_service.h
@@ -1,10 +1,10 @@
 /*
       This file is part of GNUnet
 /*
       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
 
       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
       option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but


@@ -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
 
       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
  * @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
  */
 
 #ifndef GNUNET_ARM_SERVICE_H


@@ -35,68 +43,305 @@ extern "C"
 #endif
 #endif
 
 #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.
  */
 
 /**
  * Version of the arm API.
  */

-#define GNUNET_ARM_VERSION 0x00000000
+#define GNUNET_ARM_VERSION 0x00000003
+
+
+/**
+ * Statuses of the requests that client can send to ARM.
+ */
+enum GNUNET_ARM_RequestStatus
+{
+  /**
+   * Message was sent successfully.
+   */
+  GNUNET_ARM_REQUEST_SENT_OK = 0,
+
+  /**
+   * We disconnected from ARM, and request was not sent.
+   */
+  GNUNET_ARM_REQUEST_DISCONNECTED = 2
+
+};
+
+
+/**
+ * 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;
+
+/**
+ * Handle for an ARM operation.
+ */
+struct GNUNET_ARM_Operation;

 
 
 /**
 
 
 /**

- * Callback function invoked when operation is complete.
+ * Function called whenever we connect to or disconnect from ARM.

  *
  * @param cls closure
  *
  * @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
+ * @param connected #GNUNET_YES if connected, #GNUNET_NO if disconnected,
+ *                  #GNUNET_SYSERR if there was an error.

  */
  */

-typedef void (*GNUNET_ARM_Callback) (void *cls, int success);
+typedef void
+(*GNUNET_ARM_ConnectionStatusCallback) (void *cls,
+                                        int connected);

 
 
 /**
 
 
 /**

- * Start a service.
+ * 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,
+ * @a rs will indicate that, and @a result will be undefined.
+ *
+ * @param cls closure
+ * @param rs status of the request
+ * @param result result of the operation
+ */
+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,
+ * @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);
+
+
+/**
+ * Set up a context for communicating with ARM, then
+ * start connecting to the ARM service using that context.

  *
  *

- * @param service_name name of the service

  * @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 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 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 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_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                   GNUNET_ARM_ConnectionStatusCallback conn_status,
+                   void *conn_status_cls);
+
+
+/**
+ * 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);
+
+
+/**
+ * Abort an operation.  Only prevents the callback from being
+ * called, the operation may still complete.
+ *
+ * @param op operation to cancel

  */
 void
  */
 void

-GNUNET_ARM_start_service (const char *service_name,
-                          const struct GNUNET_CONFIGURATION_Handle *cfg,
-                          struct GNUNET_SCHEDULER_Handle *sched,
-                          struct GNUNET_TIME_Relative timeout,
-                          GNUNET_ARM_Callback cb, void *cb_cls);
+GNUNET_ARM_operation_cancel (struct GNUNET_ARM_Operation *op);
+
+
+/**
+ * Request a list of running services.
+ *
+ * @param h handle to ARM
+ * @param cont callback to invoke after request is sent or is not sent
+ * @param cont_cls closure for @a cont
+ * @return handle for the operation, NULL on error
+ */
+struct GNUNET_ARM_Operation *
+GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h,
+                                GNUNET_ARM_ServiceListCallback cont,
+                                 void *cont_cls);
+
+
+/**
+ * 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() to free the handle and prevent
+ * further connection attempts.
+ *
+ * @param h handle to ARM
+ * @param service_name name of the service
+ * @param cont callback to invoke after request is sent or is not sent
+ * @param cont_cls closure for @a cont
+ * @return handle for the operation, NULL on error
+ */
+struct GNUNET_ARM_Operation *
+GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h,
+                                const char *service_name,
+                                GNUNET_ARM_ResultCallback cont,
+                                 void *cont_cls);

 
 
 /**
 
 
 /**

- * Stop a service.
+ * Request for a service to be started.

  *
  *

+ * @param h handle to ARM

  * @param service_name name of the service
  * @param service_name name of the service

+ * @param std_inheritance inheritance of std streams
+ * @param cont callback to invoke after request is sent or not sent
+ * @param cont_cls closure for @a cont
+ * @return handle for the operation, NULL on error
+ */
+struct GNUNET_ARM_Operation *
+GNUNET_ARM_request_service_start (struct GNUNET_ARM_Handle *h,
+                                 const char *service_name,
+                                 enum GNUNET_OS_InheritStdioFlags std_inheritance,
+                                 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 service service name
+ * @param status status of the service
+ */
+typedef void
+(*GNUNET_ARM_ServiceStatusCallback) (void *cls,
+                                     const char *service,
+                                     enum GNUNET_ARM_ServiceStatus status);
+
+
+/**
+ * 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 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 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 on status updates
+ * @param cont_cls closure for @a cont
+ * @return context to use for further ARM monitor operations, NULL on error.

  */
  */

-void
-GNUNET_ARM_stop_service (const char *service_name,
-                         const struct GNUNET_CONFIGURATION_Handle *cfg,
-                         struct GNUNET_SCHEDULER_Handle *sched,
-                         struct GNUNET_TIME_Relative timeout,
-                         GNUNET_ARM_Callback cb, void *cb_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.
+ *
+ * @param h the handle that was being used
+ */
+void
+GNUNET_ARM_monitor_stop (struct GNUNET_ARM_MonitorHandle *h);

 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {


@@ -106,3 +351,5 @@ GNUNET_ARM_stop_service (const char *service_name,
 #endif
 
 #endif
 #endif
 
 #endif

+
+/** @} */  /* end of group */