gnunet_arm_service.h (10113B)
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 47 #include "gnunet_util_lib.h" 48 49 /** 50 * Version of the arm API. 51 */ 52 #define GNUNET_ARM_VERSION 0x00000003 53 54 55 /** 56 * Statuses of the requests that client can send to ARM. 57 */ 58 enum GNUNET_ARM_RequestStatus 59 { 60 /** 61 * Message was sent successfully. 62 */ 63 GNUNET_ARM_REQUEST_SENT_OK = 0, 64 65 /** 66 * We disconnected from ARM, and request was not sent. 67 */ 68 GNUNET_ARM_REQUEST_DISCONNECTED = 2 69 }; 70 71 72 /** 73 * Statuses of services. 74 */ 75 enum GNUNET_ARM_ServiceMonitorStatus 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 * Status of a service managed by ARM. 158 */ 159 enum GNUNET_ARM_ServiceStatus 160 { 161 /** 162 * Service is stopped. 163 */ 164 GNUNET_ARM_SERVICE_STATUS_STOPPED = 0, 165 166 /** 167 * Service has been started and is currently running. 168 */ 169 GNUNET_ARM_SERVICE_STATUS_STARTED = 1, 170 171 /** 172 * The service has previously failed, and 173 * will be restarted. 174 */ 175 GNUNET_ARM_SERVICE_STATUS_FAILED = 2, 176 177 /** 178 * The service was started, but then exited normally. 179 */ 180 GNUNET_ARM_SERVICE_STATUS_FINISHED = 3, 181 182 /** 183 * The service was started, and we're currently waiting 184 * for it to be stopped. 185 */ 186 GNUNET_ARM_SERVICE_STATUS_STOPPING = 4, 187 }; 188 189 190 /** 191 * Information about a service managed by ARM. 192 */ 193 struct GNUNET_ARM_ServiceInfo 194 { 195 /** 196 * The current status of the service. 197 */ 198 enum GNUNET_ARM_ServiceStatus status; 199 200 /** 201 * The name of the service. 202 */ 203 const char *name; 204 205 /** 206 * The binary used to execute the service. 207 */ 208 const char *binary; 209 210 /** 211 * Time when the service will be restarted, if applicable 212 * to the current status. 213 */ 214 struct GNUNET_TIME_Absolute restart_at; 215 216 /** 217 * Time when the service was first started, if applicable. 218 */ 219 struct GNUNET_TIME_Absolute last_started_at; 220 221 /** 222 * Last process exit status. 223 */ 224 int last_exit_status; 225 }; 226 227 228 /** 229 * Handle for interacting with ARM. 230 */ 231 struct GNUNET_ARM_Handle; 232 233 /** 234 * Handle for an ARM operation. 235 */ 236 struct GNUNET_ARM_Operation; 237 238 239 /** 240 * Function called whenever we connect to or disconnect from ARM. 241 * 242 * @param cls closure 243 * @param connected #GNUNET_YES if connected, #GNUNET_NO if disconnected, 244 * #GNUNET_SYSERR if there was an error. 245 */ 246 typedef void 247 (*GNUNET_ARM_ConnectionStatusCallback) ( 248 void *cls, 249 enum GNUNET_GenericReturnValue connected); 250 251 252 /** 253 * Function called in response to a start/stop request. 254 * Will be called when request was not sent successfully, 255 * or when a reply comes. If the request was not sent successfully, 256 * @a rs will indicate that, and @a result will be undefined. 257 * 258 * @param cls closure 259 * @param rs status of the request 260 * @param result result of the operation 261 */ 262 typedef void 263 (*GNUNET_ARM_ResultCallback) ( 264 void *cls, 265 enum GNUNET_ARM_RequestStatus rs, 266 enum GNUNET_ARM_Result result); 267 268 269 /** 270 * Callback function invoked when list operation is complete. 271 * Will be called when request was not sent successfully, 272 * or when a reply comes. If the request was not sent successfully, 273 * @a rs will indicate that, and @a count and @a list will be undefined. 274 * 275 * @param cls closure 276 * @param rs status of the request 277 * @param count number of strings in the list 278 * @param list list of services managed by arm 279 */ 280 typedef void 281 (*GNUNET_ARM_ServiceListCallback) ( 282 void *cls, 283 enum GNUNET_ARM_RequestStatus rs, 284 unsigned int count, 285 const struct GNUNET_ARM_ServiceInfo *list); 286 287 288 /** 289 * Set up a context for communicating with ARM, then 290 * start connecting to the ARM service using that context. 291 * 292 * @param cfg configuration to use (needed to contact ARM; 293 * the ARM service may internally use a different 294 * configuration to determine how to start the service). 295 * @param conn_status will be called when connecting/disconnecting 296 * @param conn_status_cls closure for @a conn_status 297 * @return context to use for further ARM operations, NULL on error. 298 */ 299 struct GNUNET_ARM_Handle * 300 GNUNET_ARM_connect ( 301 const struct GNUNET_CONFIGURATION_Handle *cfg, 302 GNUNET_ARM_ConnectionStatusCallback conn_status, 303 void *conn_status_cls); 304 305 306 /** 307 * Disconnect from the ARM service and destroy the handle. 308 * 309 * @param[in] h the handle that was being used 310 */ 311 void 312 GNUNET_ARM_disconnect ( 313 struct GNUNET_ARM_Handle *h); 314 315 316 /** 317 * Abort an operation. Only prevents the callback from being 318 * called, the operation may still complete. 319 * 320 * @param op operation to cancel 321 */ 322 void 323 GNUNET_ARM_operation_cancel ( 324 struct GNUNET_ARM_Operation *op); 325 326 327 /** 328 * Request a list of running services. 329 * 330 * @param h handle to ARM 331 * @param cont callback to invoke after request is sent or is not sent 332 * @param cont_cls closure for @a cont 333 * @return handle for the operation, NULL on error 334 */ 335 struct GNUNET_ARM_Operation * 336 GNUNET_ARM_request_service_list ( 337 struct GNUNET_ARM_Handle *h, 338 GNUNET_ARM_ServiceListCallback cont, 339 void *cont_cls); 340 341 342 /** 343 * Request a service to be stopped. 344 * Stopping arm itself will not invalidate its handle, and 345 * ARM API will try to restore connection to the ARM service, 346 * even if ARM connection was lost because you asked for ARM to be stopped. 347 * Call #GNUNET_ARM_disconnect() to free the handle and prevent 348 * further connection attempts. 349 * 350 * @param h handle to ARM 351 * @param service_name name of the service 352 * @param cont callback to invoke after request is sent or is not sent 353 * @param cont_cls closure for @a cont 354 * @return handle for the operation, NULL on error 355 */ 356 struct GNUNET_ARM_Operation * 357 GNUNET_ARM_request_service_stop ( 358 struct GNUNET_ARM_Handle *h, 359 const char *service_name, 360 GNUNET_ARM_ResultCallback cont, 361 void *cont_cls); 362 363 364 /** 365 * Request for a service to be started. 366 * 367 * @param h handle to ARM 368 * @param service_name name of the service 369 * @param std_inheritance inheritance of std streams 370 * @param cont callback to invoke after request is sent or not sent 371 * @param cont_cls closure for @a cont 372 * @return handle for the operation, NULL on error 373 */ 374 struct GNUNET_ARM_Operation * 375 GNUNET_ARM_request_service_start ( 376 struct GNUNET_ARM_Handle *h, 377 const char *service_name, 378 enum GNUNET_OS_InheritStdioFlags std_inheritance, 379 GNUNET_ARM_ResultCallback cont, 380 void *cont_cls); 381 382 383 /** 384 * Handle for monitoring ARM. 385 */ 386 struct GNUNET_ARM_MonitorHandle; 387 388 389 /** 390 * Function called in when a status update arrives. 391 * 392 * @param cls closure 393 * @param service service name 394 * @param status status of the service 395 */ 396 typedef void 397 (*GNUNET_ARM_ServiceMonitorCallback) ( 398 void *cls, 399 const char *service, 400 enum GNUNET_ARM_ServiceMonitorStatus status); 401 402 403 /** 404 * Setup a context for monitoring ARM, then 405 * start connecting to the ARM service for monitoring using that context. 406 * 407 * @param cfg configuration to use (needed to contact ARM; 408 * the ARM service may internally use a different 409 * configuration to determine how to start the service). 410 * @param cont callback to invoke on status updates 411 * @param cont_cls closure for @a cont 412 * @return context to use for further ARM monitor operations, NULL on error. 413 */ 414 struct GNUNET_ARM_MonitorHandle * 415 GNUNET_ARM_monitor_start ( 416 const struct GNUNET_CONFIGURATION_Handle *cfg, 417 GNUNET_ARM_ServiceMonitorCallback cont, 418 void *cont_cls); 419 420 421 /** 422 * Disconnect from the ARM service and destroy the handle. 423 * 424 * @param h the handle that was being used 425 */ 426 void 427 GNUNET_ARM_monitor_stop ( 428 struct GNUNET_ARM_MonitorHandle *h); 429 430 #if 0 /* keep Emacsens' auto-indent happy */ 431 { 432 #endif 433 #ifdef __cplusplus 434 } 435 #endif 436 437 #endif 438 439 /** @} */ /* end of group */