src/include/gnunet_arm_service.h

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