2 This file is part of GNUnet
3 (C) 2009 Christian Grothoff (and other contributing authors)
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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_arm_service.h
23 * @brief API to access gnunet-arm
24 * @author Christian Grothoff
27 #ifndef GNUNET_ARM_SERVICE_H
28 #define GNUNET_ARM_SERVICE_H
33 #if 0 /* keep Emacsens' auto-indent happy */
38 #include "gnunet_configuration_lib.h"
39 #include "gnunet_scheduler_lib.h"
40 #include "gnunet_time_lib.h"
43 * Version of the arm API.
45 #define GNUNET_ARM_VERSION 0x00000000
49 * Callback function invoked when operation is complete.
52 * @param success GNUNET_YES if we think the service is running
53 * GNUNET_NO if we think the service is stopped
54 * GNUNET_SYSERR if we think ARM was not running or
55 * if the service status is unknown
57 typedef void (*GNUNET_ARM_Callback) (void *cls, int success);
61 * Handle for interacting with ARM.
63 struct GNUNET_ARM_Handle;
67 * Setup a context for communicating with ARM. Note that this
68 * can be done even if the ARM service is not yet running.
70 * @param cfg configuration to use (needed to contact ARM;
71 * the ARM service may internally use a different
72 * configuration to determine how to start the service).
73 * @param service service that *this* process is implementing/providing, can be NULL
74 * @return context to use for further ARM operations, NULL on error
76 struct GNUNET_ARM_Handle *
77 GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
82 * Disconnect from the ARM service.
84 * @param h the handle that was being used
87 GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h);
91 * Start a service. Note that this function merely asks ARM to start
92 * the service and that ARM merely confirms that it forked the
93 * respective process. The specified callback may thus return before
94 * the service has started to listen on the server socket and it may
95 * also be that the service has crashed in the meantime. Clients
96 * should repeatedly try to connect to the service at the respective
97 * port (with some delays in between) before assuming that the service
98 * actually failed to start. Note that if an error is returned to the
99 * callback, clients obviously should not bother with trying to
100 * contact the service.
102 * @param h handle to ARM
103 * @param service_name name of the service
104 * @param timeout how long to wait before failing for good
105 * @param cb callback to invoke when service is ready
106 * @param cb_cls closure for callback
109 GNUNET_ARM_start_service (struct GNUNET_ARM_Handle *h,
110 const char *service_name,
111 struct GNUNET_TIME_Relative timeout,
112 GNUNET_ARM_Callback cb, void *cb_cls);
116 * Stop a service. Note that the callback is invoked as soon
117 * as ARM confirms that it will ask the service to terminate.
118 * The actual termination may still take some time.
120 * @param h handle to ARM
121 * @param service_name name of the service
122 * @param timeout how long to wait before failing for good
123 * @param cb callback to invoke when service is ready
124 * @param cb_cls closure for callback
127 GNUNET_ARM_stop_service (struct GNUNET_ARM_Handle *h,
128 const char *service_name,
129 struct GNUNET_TIME_Relative timeout,
130 GNUNET_ARM_Callback cb, void *cb_cls);
134 #if 0 /* keep Emacsens' auto-indent happy */