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