- use tunnel encryption state to select decryption key

[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 8e68cd5ee2fdcf796029710daba45d44def41448..e1f44620f611803fe6f64fcbf612a479ff9de8c7 100644 (file)
--- 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
 
       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


@@ -35,133 +35,312 @@ 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 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.
 
 
 /**
  * Handle for interacting with ARM.

- */ 
+ */

 struct GNUNET_ARM_Handle;
 
 
 /**
 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 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_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
  *
  * @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 h handle to ARM

- * @param service_name name of the service

  * @param timeout how long to wait before failing for good
  * @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
  */
 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 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
  */
 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
  */
 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 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
  */
 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 */
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */