src/include/gnunet_arm_service.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2009 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18       Boston, MA 02110-1301, USA.
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * API to access gnunet-arm
  26  *
  27  * @defgroup arm  ARM service
  28  * Automatic Restart Manager
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_ARM_SERVICE_H
  33 #define GNUNET_ARM_SERVICE_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_util_lib.h"
  44
  45 /**
  46  * Version of the arm API.
  47  */
  48 #define GNUNET_ARM_VERSION 0x00000002
  49
  50
  51 /**
  52  * Statuses of the requests that client can send to ARM.
  53  */
  54 enum GNUNET_ARM_RequestStatus
  55 {
  56   /**
  57    * Message was sent successfully.
  58    */
  59   GNUNET_ARM_REQUEST_SENT_OK = 0,
  60
  61   /**
  62    * Misconfiguration (can't connect to the ARM service).
  63    */
  64   GNUNET_ARM_REQUEST_CONFIGURATION_ERROR = 1,
  65
  66   /**
  67    * We disconnected from ARM, and request was not sent.
  68    */
  69   GNUNET_ARM_REQUEST_DISCONNECTED = 2,
  70
  71   /**
  72    * ARM API is busy (probably trying to connect to ARM),
  73    * and request was not sent. Try again later.
  74    */
  75   GNUNET_ARM_REQUEST_BUSY = 3,
  76
  77   /**
  78    * It was discovered that the request would be too long to fit in a message,
  79    * and thus it was not sent.
  80    */
  81   GNUNET_ARM_REQUEST_TOO_LONG = 4,
  82
  83   /**
  84    * Request time ran out before we had a chance to send it.
  85    */
  86   GNUNET_ARM_REQUEST_TIMEOUT = 5
  87
  88 };
  89
  90
  91 /**
  92  * Statuses of services.
  93  */
  94 enum GNUNET_ARM_ServiceStatus
  95 {
  96   /**
  97    * Dummy message.
  98    */
  99   GNUNET_ARM_SERVICE_MONITORING_STARTED = 0,
 100
 101   /**
 102    * Service was stopped.
 103    */
 104   GNUNET_ARM_SERVICE_STOPPED = 1,
 105
 106   /**
 107    * Service starting was initiated
 108    */
 109   GNUNET_ARM_SERVICE_STARTING = 2,
 110
 111   /**
 112    * Service stopping was initiated
 113    */
 114   GNUNET_ARM_SERVICE_STOPPING = 3
 115 };
 116
 117
 118 /**
 119  * Replies to ARM requests
 120  */
 121 enum GNUNET_ARM_Result
 122 {
 123   /**
 124    * Service was stopped (never sent for ARM itself).
 125    */
 126   GNUNET_ARM_RESULT_STOPPED = 0,
 127
 128   /**
 129    * ARM stopping was initiated (there's no "stopped" for ARM itself).
 130    */
 131   GNUNET_ARM_RESULT_STOPPING = 1,
 132
 133   /**
 134    * Service starting was initiated
 135    */
 136   GNUNET_ARM_RESULT_STARTING = 2,
 137
 138   /**
 139    * Asked to start it, but it's already starting.
 140    */
 141   GNUNET_ARM_RESULT_IS_STARTING_ALREADY = 3,
 142
 143   /**
 144    * Asked to stop it, but it's already stopping.
 145    */
 146   GNUNET_ARM_RESULT_IS_STOPPING_ALREADY = 4,
 147
 148   /**
 149    * Asked to start it, but it's already started.
 150    */
 151   GNUNET_ARM_RESULT_IS_STARTED_ALREADY = 5,
 152
 153   /**
 154    * Asked to stop it, but it's already stopped.
 155    */
 156   GNUNET_ARM_RESULT_IS_STOPPED_ALREADY = 6,
 157
 158   /**
 159    * Asked to start or stop a service, but it's not known.
 160    */
 161   GNUNET_ARM_RESULT_IS_NOT_KNOWN = 7,
 162
 163   /**
 164    * Tried to start a service, but that failed for some reason.
 165    */
 166   GNUNET_ARM_RESULT_START_FAILED = 8,
 167
 168   /**
 169    * Asked to start something, but ARM is shutting down and can't comply.
 170    */
 171   GNUNET_ARM_RESULT_IN_SHUTDOWN = 9
 172 };
 173
 174
 175 /**
 176  * Handle for interacting with ARM.
 177  */
 178 struct GNUNET_ARM_Handle;
 179
 180
 181 /**
 182  * Function called whenever we connect to or disconnect from ARM.
 183  *
 184  * @param cls closure
 185  * @param connected GNUNET_YES if connected, GNUNET_NO if disconnected,
 186  *                  GNUNET_SYSERR if there was an error.
 187  */
 188 typedef void (*GNUNET_ARM_ConnectionStatusCallback) (void *cls,
 189                                                      int connected);
 190
 191
 192 /**
 193  * Function called in response to a start/stop request.
 194  * Will be called when request was not sent successfully,
 195  * or when a reply comes. If the request was not sent successfully,
 196  * 'rs' will indicate that, and 'service' and 'result' will be undefined.
 197  *
 198  * @param cls closure
 199  * @param rs status of the request
 200  * @param service service name
 201  * @param result result of the operation
 202  */
 203 typedef void (*GNUNET_ARM_ResultCallback) (void *cls,
 204                                            enum GNUNET_ARM_RequestStatus rs,
 205                                            const char *service,
 206                                            enum GNUNET_ARM_Result result);
 207
 208
 209 /**
 210  * Callback function invoked when list operation is complete.
 211  * Will be called when request was not sent successfully,
 212  * or when a reply comes. If the request was not sent successfully,
 213  * 'rs' will indicate that, and 'count' and 'list' will be undefined.
 214  *
 215  * @param cls closure
 216  * @param rs status of the request
 217  * @param count number of strings in the list
 218  * @param list list of running services
 219  */
 220 typedef void (*GNUNET_ARM_ServiceListCallback) (void *cls,
 221                                                 enum GNUNET_ARM_RequestStatus rs,
 222                                                 unsigned int count,
 223                                                 const char *const*list);
 224
 225
 226 /**
 227  * Set up a context for communicating with ARM, then
 228  * start connecting to the ARM service using that context.
 229  *
 230  * @param cfg configuration to use (needed to contact ARM;
 231  *        the ARM service may internally use a different
 232  *        configuration to determine how to start the service).
 233  * @param conn_status will be called when connecting/disconnecting
 234  * @param cls closure for conn_status
 235  * @return context to use for further ARM operations, NULL on error.
 236  */
 237 struct GNUNET_ARM_Handle *
 238 GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 239                     GNUNET_ARM_ConnectionStatusCallback conn_status,
 240                     void *cls);
 241
 242
 243 /**
 244  * Disconnect from the ARM service and destroy the handle.
 245  *
 246  * @param h the handle that was being used
 247  */
 248 void
 249 GNUNET_ARM_disconnect_and_free (struct GNUNET_ARM_Handle *h);
 250
 251
 252 /**
 253  * Request a list of running services.
 254  *
 255  * @param h handle to ARM
 256  * @param timeout how long to wait before failing for good
 257  * @param cont callback to invoke after request is sent or is not sent
 258  * @param cont_cls closure for callback
 259  */
 260 void
 261 GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h,
 262                                  struct GNUNET_TIME_Relative timeout,
 263                                  GNUNET_ARM_ServiceListCallback cont, void *cont_cls);
 264
 265
 266 /**
 267  * Request a service to be stopped.
 268  * Stopping arm itself will not invalidate its handle, and
 269  * ARM API will try to restore connection to the ARM service,
 270  * even if ARM connection was lost because you asked for ARM to be stopped.
 271  * Call GNUNET_ARM_disconnect_and_free () to free the handle and prevent
 272  * further connection attempts.
 273  *
 274  * @param h handle to ARM
 275  * @param service_name name of the service
 276  * @param timeout how long to wait before failing for good
 277  * @param cont callback to invoke after request is sent or is not sent
 278  * @param cont_cls closure for callback
 279  */
 280 void
 281 GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h,
 282                                  const char *service_name,
 283                                  struct GNUNET_TIME_Relative timeout,
 284                                  GNUNET_ARM_ResultCallback cont, void *cont_cls);
 285
 286
 287 /**
 288  * Request for a service to be started.
 289  *
 290  * @param h handle to ARM
 291  * @param service_name name of the service
 292  * @param std_inheritance inheritance of std streams
 293  * @param timeout how long to wait before failing for good
 294  * @param cont callback to invoke after request is sent or not sent
 295  * @param cont_cls closure for callback
 296  */
 297 void
 298 GNUNET_ARM_request_service_start (struct GNUNET_ARM_Handle *h,
 299                                   const char *service_name,
 300                                   enum GNUNET_OS_InheritStdioFlags std_inheritance,
 301                                   struct GNUNET_TIME_Relative timeout,
 302                                   GNUNET_ARM_ResultCallback cont,
 303                                   void *cont_cls);
 304
 305
 306 /**
 307  * Handle for monitoring ARM.
 308  */
 309 struct GNUNET_ARM_MonitorHandle;
 310
 311
 312 /**
 313  * Function called in when a status update arrives.
 314  *
 315  * @param cls closure
 316  * @param arm handle to the arm connection
 317  * @param service service name
 318  * @param status status of the service
 319  */
 320 typedef void (*GNUNET_ARM_ServiceStatusCallback) (void *cls,
 321                                                   const char *service,
 322                                                   enum GNUNET_ARM_ServiceStatus status);
 323
 324
 325 /**
 326  * Setup a context for monitoring ARM, then
 327  * start connecting to the ARM service for monitoring using that context.
 328  *
 329  * @param cfg configuration to use (needed to contact ARM;
 330  *        the ARM service may internally use a different
 331  *        configuration to determine how to start the service).
 332  * @param cont callback to invoke on status updates
 333  * @param cont_cls closure
 334  * @return context to use for further ARM monitor operations, NULL on error.
 335  */
 336 struct GNUNET_ARM_MonitorHandle *
 337 GNUNET_ARM_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg,
 338                     GNUNET_ARM_ServiceStatusCallback cont,
 339                     void *cont_cls);
 340
 341
 342 /**
 343  * Disconnect from the ARM service and destroy the handle.
 344  *
 345  * @param h the handle that was being used
 346  */
 347 void
 348 GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h);
 349
 350 #if 0                           /* keep Emacsens' auto-indent happy */
 351 {
 352 #endif
 353 #ifdef __cplusplus
 354 }
 355 #endif
 356
 357 #endif
 358
 359 /** @} */  /* end of group */