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 Affero 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       You should have received a copy of the GNU Affero General Public License
  16       along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  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    * We disconnected from ARM, and request was not sent.
  66    */
  67   GNUNET_ARM_REQUEST_DISCONNECTED = 2
  68 };
  69
  70
  71 /**
  72  * Statuses of services.
  73  */
  74 enum GNUNET_ARM_ServiceMonitorStatus
  75 {
  76   /**
  77    * Dummy message.
  78    */
  79   GNUNET_ARM_SERVICE_MONITORING_STARTED = 0,
  80
  81   /**
  82    * Service was stopped.
  83    */
  84   GNUNET_ARM_SERVICE_STOPPED = 1,
  85
  86   /**
  87    * Service starting was initiated
  88    */
  89   GNUNET_ARM_SERVICE_STARTING = 2,
  90
  91   /**
  92    * Service stopping was initiated
  93    */
  94   GNUNET_ARM_SERVICE_STOPPING = 3
  95 };
  96
  97
  98 /**
  99  * Replies to ARM requests
 100  */
 101 enum GNUNET_ARM_Result
 102 {
 103   /**
 104    * Service was stopped (never sent for ARM itself).
 105    */
 106   GNUNET_ARM_RESULT_STOPPED = 0,
 107
 108   /**
 109    * ARM stopping was initiated (there's no "stopped" for ARM itself).
 110    */
 111   GNUNET_ARM_RESULT_STOPPING = 1,
 112
 113   /**
 114    * Service starting was initiated
 115    */
 116   GNUNET_ARM_RESULT_STARTING = 2,
 117
 118   /**
 119    * Asked to start it, but it's already starting.
 120    */
 121   GNUNET_ARM_RESULT_IS_STARTING_ALREADY = 3,
 122
 123   /**
 124    * Asked to stop it, but it's already stopping.
 125    */
 126   GNUNET_ARM_RESULT_IS_STOPPING_ALREADY = 4,
 127
 128   /**
 129    * Asked to start it, but it's already started.
 130    */
 131   GNUNET_ARM_RESULT_IS_STARTED_ALREADY = 5,
 132
 133   /**
 134    * Asked to stop it, but it's already stopped.
 135    */
 136   GNUNET_ARM_RESULT_IS_STOPPED_ALREADY = 6,
 137
 138   /**
 139    * Asked to start or stop a service, but it's not known.
 140    */
 141   GNUNET_ARM_RESULT_IS_NOT_KNOWN = 7,
 142
 143   /**
 144    * Tried to start a service, but that failed for some reason.
 145    */
 146   GNUNET_ARM_RESULT_START_FAILED = 8,
 147
 148   /**
 149    * Asked to start something, but ARM is shutting down and can't comply.
 150    */
 151   GNUNET_ARM_RESULT_IN_SHUTDOWN = 9
 152 };
 153
 154
 155 /**
 156  * Status of a service managed by ARM.
 157  */
 158 enum GNUNET_ARM_ServiceStatus
 159 {
 160   /**
 161    * Service is stopped.
 162    */
 163   GNUNET_ARM_SERVICE_STATUS_STOPPED = 0,
 164
 165   /**
 166    * Service has been started and is currently running.
 167    */
 168   GNUNET_ARM_SERVICE_STATUS_STARTED = 1,
 169
 170   /**
 171    * The service has previously failed, and
 172    * will be restarted.
 173    */
 174   GNUNET_ARM_SERVICE_STATUS_FAILED = 2,
 175
 176   /**
 177    * The service was started, but then exited normally.
 178    */
 179   GNUNET_ARM_SERVICE_STATUS_FINISHED = 3,
 180
 181   /**
 182    * The service was started, and we're currently waiting
 183    * for it to be stopped.
 184    */
 185   GNUNET_ARM_SERVICE_STATUS_STOPPING = 4,
 186 };
 187
 188
 189 /**
 190  * Information about a service managed by ARM.
 191  */
 192 struct GNUNET_ARM_ServiceInfo
 193 {
 194   /**
 195    * The current status of the service.
 196    */
 197   enum GNUNET_ARM_ServiceStatus status;
 198
 199   /**
 200    * The name of the service.
 201    */
 202   const char *name;
 203
 204   /**
 205    * The binary used to execute the service.
 206    */
 207   const char *binary;
 208
 209   /**
 210    * Time when the sevice will be restarted, if applicable
 211    * to the current status.
 212    */
 213   struct GNUNET_TIME_Absolute restart_at;
 214
 215   /**
 216    * Time when the sevice was first started, if applicable.
 217    */
 218   struct GNUNET_TIME_Absolute last_started_at;
 219
 220   /**
 221    * Last process exit status.
 222    */
 223   int last_exit_status;
 224 };
 225
 226
 227 /**
 228  * Handle for interacting with ARM.
 229  */
 230 struct GNUNET_ARM_Handle;
 231
 232 /**
 233  * Handle for an ARM operation.
 234  */
 235 struct GNUNET_ARM_Operation;
 236
 237
 238 /**
 239  * Function called whenever we connect to or disconnect from ARM.
 240  *
 241  * @param cls closure
 242  * @param connected #GNUNET_YES if connected, #GNUNET_NO if disconnected,
 243  *                  #GNUNET_SYSERR if there was an error.
 244  */
 245 typedef void
 246 (*GNUNET_ARM_ConnectionStatusCallback) (void *cls,
 247                                         int connected);
 248
 249
 250 /**
 251  * Function called in response to a start/stop request.
 252  * Will be called when request was not sent successfully,
 253  * or when a reply comes. If the request was not sent successfully,
 254  * @a rs will indicate that, and @a result will be undefined.
 255  *
 256  * @param cls closure
 257  * @param rs status of the request
 258  * @param result result of the operation
 259  */
 260 typedef void
 261 (*GNUNET_ARM_ResultCallback) (void *cls,
 262                               enum GNUNET_ARM_RequestStatus rs,
 263                               enum GNUNET_ARM_Result result);
 264
 265
 266 /**
 267  * Callback function invoked when list operation is complete.
 268  * Will be called when request was not sent successfully,
 269  * or when a reply comes. If the request was not sent successfully,
 270  * @a rs will indicate that, and @a count and @a list will be undefined.
 271  *
 272  * @param cls closure
 273  * @param rs status of the request
 274  * @param count number of strings in the list
 275  * @param list list of services managed by arm
 276  */
 277 typedef void
 278 (*GNUNET_ARM_ServiceListCallback) (void *cls,
 279                                    enum GNUNET_ARM_RequestStatus rs,
 280                                    unsigned int count,
 281                                    const struct GNUNET_ARM_ServiceInfo *list);
 282
 283
 284 /**
 285  * Set up a context for communicating with ARM, then
 286  * start connecting to the ARM service using that context.
 287  *
 288  * @param cfg configuration to use (needed to contact ARM;
 289  *        the ARM service may internally use a different
 290  *        configuration to determine how to start the service).
 291  * @param conn_status will be called when connecting/disconnecting
 292  * @param conn_status_cls closure for @a conn_status
 293  * @return context to use for further ARM operations, NULL on error.
 294  */
 295 struct GNUNET_ARM_Handle *
 296 GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 297                     GNUNET_ARM_ConnectionStatusCallback conn_status,
 298                     void *conn_status_cls);
 299
 300
 301 /**
 302  * Disconnect from the ARM service and destroy the handle.
 303  *
 304  * @param h the handle that was being used
 305  */
 306 void
 307 GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h);
 308
 309
 310 /**
 311  * Abort an operation.  Only prevents the callback from being
 312  * called, the operation may still complete.
 313  *
 314  * @param op operation to cancel
 315  */
 316 void
 317 GNUNET_ARM_operation_cancel (struct GNUNET_ARM_Operation *op);
 318
 319
 320 /**
 321  * Request a list of running services.
 322  *
 323  * @param h handle to ARM
 324  * @param cont callback to invoke after request is sent or is not sent
 325  * @param cont_cls closure for @a cont
 326  * @return handle for the operation, NULL on error
 327  */
 328 struct GNUNET_ARM_Operation *
 329 GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h,
 330                                  GNUNET_ARM_ServiceListCallback cont,
 331                                  void *cont_cls);
 332
 333
 334 /**
 335  * Request a service to be stopped.
 336  * Stopping arm itself will not invalidate its handle, and
 337  * ARM API will try to restore connection to the ARM service,
 338  * even if ARM connection was lost because you asked for ARM to be stopped.
 339  * Call #GNUNET_ARM_disconnect() to free the handle and prevent
 340  * further connection attempts.
 341  *
 342  * @param h handle to ARM
 343  * @param service_name name of the service
 344  * @param cont callback to invoke after request is sent or is not sent
 345  * @param cont_cls closure for @a cont
 346  * @return handle for the operation, NULL on error
 347  */
 348 struct GNUNET_ARM_Operation *
 349 GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h,
 350                                  const char *service_name,
 351                                  GNUNET_ARM_ResultCallback cont,
 352                                  void *cont_cls);
 353
 354
 355 /**
 356  * Request for a service to be started.
 357  *
 358  * @param h handle to ARM
 359  * @param service_name name of the service
 360  * @param std_inheritance inheritance of std streams
 361  * @param cont callback to invoke after request is sent or not sent
 362  * @param cont_cls closure for @a cont
 363  * @return handle for the operation, NULL on error
 364  */
 365 struct GNUNET_ARM_Operation *
 366 GNUNET_ARM_request_service_start (struct GNUNET_ARM_Handle *h,
 367                                   const char *service_name,
 368                                   enum GNUNET_OS_InheritStdioFlags
 369                                   std_inheritance,
 370                                   GNUNET_ARM_ResultCallback cont,
 371                                   void *cont_cls);
 372
 373
 374 /**
 375  * Handle for monitoring ARM.
 376  */
 377 struct GNUNET_ARM_MonitorHandle;
 378
 379
 380 /**
 381  * Function called in when a status update arrives.
 382  *
 383  * @param cls closure
 384  * @param service service name
 385  * @param status status of the service
 386  */
 387 typedef void
 388 (*GNUNET_ARM_ServiceMonitorCallback) (void *cls,
 389                                       const char *service,
 390                                       enum GNUNET_ARM_ServiceMonitorStatus
 391                                       status);
 392
 393
 394 /**
 395  * Setup a context for monitoring ARM, then
 396  * start connecting to the ARM service for monitoring using that context.
 397  *
 398  * @param cfg configuration to use (needed to contact ARM;
 399  *        the ARM service may internally use a different
 400  *        configuration to determine how to start the service).
 401  * @param cont callback to invoke on status updates
 402  * @param cont_cls closure for @a cont
 403  * @return context to use for further ARM monitor operations, NULL on error.
 404  */
 405 struct GNUNET_ARM_MonitorHandle *
 406 GNUNET_ARM_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 407                           GNUNET_ARM_ServiceMonitorCallback cont,
 408                           void *cont_cls);
 409
 410
 411 /**
 412  * Disconnect from the ARM service and destroy the handle.
 413  *
 414  * @param h the handle that was being used
 415  */
 416 void
 417 GNUNET_ARM_monitor_stop (struct GNUNET_ARM_MonitorHandle *h);
 418
 419 #if 0                           /* keep Emacsens' auto-indent happy */
 420 {
 421 #endif
 422 #ifdef __cplusplus
 423 }
 424 #endif
 425
 426 #endif
 427
 428 /** @} */  /* end of group */