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