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