2 This file is part of GNUnet
3 Copyright (C) 2009 GNUnet e.V.
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.
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.
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.
22 * @author Christian Grothoff
25 * API to access gnunet-arm
27 * @defgroup arm ARM service
28 * Automatic Restart Manager
30 * @see [Documentation](https://gnunet.org/arm)
35 #ifndef GNUNET_ARM_SERVICE_H
36 #define GNUNET_ARM_SERVICE_H
41 #if 0 /* keep Emacsens' auto-indent happy */
46 #include "gnunet_util_lib.h"
49 * Version of the arm API.
51 #define GNUNET_ARM_VERSION 0x00000002
55 * Statuses of the requests that client can send to ARM.
57 enum GNUNET_ARM_RequestStatus
60 * Message was sent successfully.
62 GNUNET_ARM_REQUEST_SENT_OK = 0,
65 * Misconfiguration (can't connect to the ARM service).
67 GNUNET_ARM_REQUEST_CONFIGURATION_ERROR = 1,
70 * We disconnected from ARM, and request was not sent.
72 GNUNET_ARM_REQUEST_DISCONNECTED = 2,
75 * ARM API is busy (probably trying to connect to ARM),
76 * and request was not sent. Try again later.
78 GNUNET_ARM_REQUEST_BUSY = 3,
81 * It was discovered that the request would be too long to fit in a message,
82 * and thus it was not sent.
84 GNUNET_ARM_REQUEST_TOO_LONG = 4,
87 * Request time ran out before we had a chance to send it.
89 GNUNET_ARM_REQUEST_TIMEOUT = 5
95 * Statuses of services.
97 enum GNUNET_ARM_ServiceStatus
102 GNUNET_ARM_SERVICE_MONITORING_STARTED = 0,
105 * Service was stopped.
107 GNUNET_ARM_SERVICE_STOPPED = 1,
110 * Service starting was initiated
112 GNUNET_ARM_SERVICE_STARTING = 2,
115 * Service stopping was initiated
117 GNUNET_ARM_SERVICE_STOPPING = 3
122 * Replies to ARM requests
124 enum GNUNET_ARM_Result
127 * Service was stopped (never sent for ARM itself).
129 GNUNET_ARM_RESULT_STOPPED = 0,
132 * ARM stopping was initiated (there's no "stopped" for ARM itself).
134 GNUNET_ARM_RESULT_STOPPING = 1,
137 * Service starting was initiated
139 GNUNET_ARM_RESULT_STARTING = 2,
142 * Asked to start it, but it's already starting.
144 GNUNET_ARM_RESULT_IS_STARTING_ALREADY = 3,
147 * Asked to stop it, but it's already stopping.
149 GNUNET_ARM_RESULT_IS_STOPPING_ALREADY = 4,
152 * Asked to start it, but it's already started.
154 GNUNET_ARM_RESULT_IS_STARTED_ALREADY = 5,
157 * Asked to stop it, but it's already stopped.
159 GNUNET_ARM_RESULT_IS_STOPPED_ALREADY = 6,
162 * Asked to start or stop a service, but it's not known.
164 GNUNET_ARM_RESULT_IS_NOT_KNOWN = 7,
167 * Tried to start a service, but that failed for some reason.
169 GNUNET_ARM_RESULT_START_FAILED = 8,
172 * Asked to start something, but ARM is shutting down and can't comply.
174 GNUNET_ARM_RESULT_IN_SHUTDOWN = 9
179 * Handle for interacting with ARM.
181 struct GNUNET_ARM_Handle;
185 * Function called whenever we connect to or disconnect from ARM.
188 * @param connected GNUNET_YES if connected, GNUNET_NO if disconnected,
189 * GNUNET_SYSERR if there was an error.
191 typedef void (*GNUNET_ARM_ConnectionStatusCallback) (void *cls,
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 * 'rs' will indicate that, and 'service' and 'result' will be undefined.
202 * @param rs status of the request
203 * @param service service name
204 * @param result result of the operation
206 typedef void (*GNUNET_ARM_ResultCallback) (void *cls,
207 enum GNUNET_ARM_RequestStatus rs,
209 enum GNUNET_ARM_Result result);
213 * Callback function invoked when list operation is complete.
214 * Will be called when request was not sent successfully,
215 * or when a reply comes. If the request was not sent successfully,
216 * 'rs' will indicate that, and 'count' and 'list' will be undefined.
219 * @param rs status of the request
220 * @param count number of strings in the list
221 * @param list list of running services
223 typedef void (*GNUNET_ARM_ServiceListCallback) (void *cls,
224 enum GNUNET_ARM_RequestStatus rs,
226 const char *const*list);
230 * Set up a context for communicating with ARM, then
231 * start connecting to the ARM service using that context.
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 cls closure for conn_status
238 * @return context to use for further ARM operations, NULL on error.
240 struct GNUNET_ARM_Handle *
241 GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
242 GNUNET_ARM_ConnectionStatusCallback conn_status,
247 * Disconnect from the ARM service and destroy the handle.
249 * @param h the handle that was being used
252 GNUNET_ARM_disconnect_and_free (struct GNUNET_ARM_Handle *h);
256 * Request a list of running services.
258 * @param h handle to ARM
259 * @param timeout how long to wait before failing for good
260 * @param cont callback to invoke after request is sent or is not sent
261 * @param cont_cls closure for callback
264 GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h,
265 struct GNUNET_TIME_Relative timeout,
266 GNUNET_ARM_ServiceListCallback cont, void *cont_cls);
270 * Request a service to be stopped.
271 * Stopping arm itself will not invalidate its handle, and
272 * ARM API will try to restore connection to the ARM service,
273 * even if ARM connection was lost because you asked for ARM to be stopped.
274 * Call GNUNET_ARM_disconnect_and_free () to free the handle and prevent
275 * further connection attempts.
277 * @param h handle to ARM
278 * @param service_name name of the service
279 * @param timeout how long to wait before failing for good
280 * @param cont callback to invoke after request is sent or is not sent
281 * @param cont_cls closure for callback
284 GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h,
285 const char *service_name,
286 struct GNUNET_TIME_Relative timeout,
287 GNUNET_ARM_ResultCallback cont, void *cont_cls);
291 * Request for a service to be started.
293 * @param h handle to ARM
294 * @param service_name name of the service
295 * @param std_inheritance inheritance of std streams
296 * @param timeout how long to wait before failing for good
297 * @param cont callback to invoke after request is sent or not sent
298 * @param cont_cls closure for callback
301 GNUNET_ARM_request_service_start (struct GNUNET_ARM_Handle *h,
302 const char *service_name,
303 enum GNUNET_OS_InheritStdioFlags std_inheritance,
304 struct GNUNET_TIME_Relative timeout,
305 GNUNET_ARM_ResultCallback cont,
310 * Handle for monitoring ARM.
312 struct GNUNET_ARM_MonitorHandle;
316 * Function called in when a status update arrives.
319 * @param arm handle to the arm connection
320 * @param service service name
321 * @param status status of the service
323 typedef void (*GNUNET_ARM_ServiceStatusCallback) (void *cls,
325 enum GNUNET_ARM_ServiceStatus status);
329 * Setup a context for monitoring ARM, then
330 * start connecting to the ARM service for monitoring using that context.
332 * @param cfg configuration to use (needed to contact ARM;
333 * the ARM service may internally use a different
334 * configuration to determine how to start the service).
335 * @param cont callback to invoke on status updates
336 * @param cont_cls closure
337 * @return context to use for further ARM monitor operations, NULL on error.
339 struct GNUNET_ARM_MonitorHandle *
340 GNUNET_ARM_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg,
341 GNUNET_ARM_ServiceStatusCallback cont,
346 * Disconnect from the ARM service and destroy the handle.
348 * @param h the handle that was being used
351 GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h);
353 #if 0 /* keep Emacsens' auto-indent happy */
362 /** @} */ /* end of group */