diff options
author | LRN <lrn1986@gmail.com> | 2013-03-13 17:49:26 +0000 |
---|---|---|
committer | LRN <lrn1986@gmail.com> | 2013-03-13 17:49:26 +0000 |
commit | 405f776bc08486af4edb80e18149c0829732b347 (patch) | |
tree | d5fc635a51641dec6b53cb2540276f34ae8f6210 /src/include/gnunet_arm_service.h | |
parent | 3ceae682287492ecc768aea5c4c463216a35774d (diff) | |
download | gnunet-405f776bc08486af4edb80e18149c0829732b347.tar.gz gnunet-405f776bc08486af4edb80e18149c0829732b347.zip |
All-encompassing ARM update
Diffstat (limited to 'src/include/gnunet_arm_service.h')
-rw-r--r-- | src/include/gnunet_arm_service.h | 295 |
1 files changed, 219 insertions, 76 deletions
diff --git a/src/include/gnunet_arm_service.h b/src/include/gnunet_arm_service.h index 0aa916bd4..be46831a4 100644 --- a/src/include/gnunet_arm_service.h +++ b/src/include/gnunet_arm_service.h | |||
@@ -43,112 +43,208 @@ extern "C" | |||
43 | /** | 43 | /** |
44 | * Version of the arm API. | 44 | * Version of the arm API. |
45 | */ | 45 | */ |
46 | #define GNUNET_ARM_VERSION 0x00000001 | 46 | #define GNUNET_ARM_VERSION 0x00000002 |
47 | 47 | ||
48 | 48 | ||
49 | /** | 49 | /** |
50 | * Values characterizing GNUnet process states. | 50 | * Statuses of the requests that client can send to ARM. |
51 | */ | 51 | */ |
52 | enum GNUNET_ARM_ProcessStatus | 52 | enum GNUNET_ARM_RequestStatus |
53 | { | 53 | { |
54 | /** | 54 | /** |
55 | * Service name is unknown to ARM. | 55 | * Message was sent successfully. |
56 | */ | 56 | */ |
57 | GNUNET_ARM_PROCESS_UNKNOWN = -1, | 57 | GNUNET_ARM_REQUEST_SENT_OK = 0, |
58 | 58 | ||
59 | /** | 59 | /** |
60 | * Service is now down (due to client request). | 60 | * Misconfiguration (can't connect to the ARM service). |
61 | */ | 61 | */ |
62 | GNUNET_ARM_PROCESS_DOWN = 0, | 62 | GNUNET_ARM_REQUEST_CONFIGURATION_ERROR = 1, |
63 | 63 | ||
64 | /** | 64 | /** |
65 | * Service is already running. | 65 | * We disconnected from ARM, and request was not sent. |
66 | */ | 66 | */ |
67 | GNUNET_ARM_PROCESS_ALREADY_RUNNING = 1, | 67 | GNUNET_ARM_REQUEST_DISCONNECTED = 2, |
68 | 68 | ||
69 | /** | 69 | /** |
70 | * Service is currently being started (due to client request). | 70 | * ARM API is busy (probably trying to connect to ARM), |
71 | * and request was not sent. Try again later. | ||
71 | */ | 72 | */ |
72 | GNUNET_ARM_PROCESS_STARTING = 2, | 73 | GNUNET_ARM_REQUEST_BUSY = 3, |
73 | 74 | ||
74 | /** | 75 | /** |
75 | * Service is already being stopped by some other client. | 76 | * It was discovered that the request would be too long to fit in a message, |
77 | * and thus it was not sent. | ||
76 | */ | 78 | */ |
77 | GNUNET_ARM_PROCESS_ALREADY_STOPPING = 3, | 79 | GNUNET_ARM_REQUEST_TOO_LONG = 4, |
78 | 80 | ||
79 | /** | 81 | /** |
80 | * Service is already down (no action taken) | 82 | * Request time ran out before we had a chance to send it. |
81 | */ | 83 | */ |
82 | GNUNET_ARM_PROCESS_ALREADY_DOWN = 4, | 84 | GNUNET_ARM_REQUEST_TIMEOUT = 5 |
85 | |||
86 | }; | ||
87 | |||
83 | 88 | ||
89 | /** | ||
90 | * Statuses of services. | ||
91 | */ | ||
92 | enum GNUNET_ARM_ServiceStatus | ||
93 | { | ||
84 | /** | 94 | /** |
85 | * ARM is currently being shut down (no more process starts) | 95 | * Dummy message. |
86 | */ | 96 | */ |
87 | GNUNET_ARM_PROCESS_SHUTDOWN = 5, | 97 | GNUNET_ARM_SERVICE_MONITORING_STARTED = 0, |
88 | 98 | ||
89 | /** | 99 | /** |
90 | * Error in communication with ARM | 100 | * Service was stopped. |
91 | */ | 101 | */ |
92 | GNUNET_ARM_PROCESS_COMMUNICATION_ERROR = 6, | 102 | GNUNET_ARM_SERVICE_STOPPED = 1, |
93 | 103 | ||
94 | /** | 104 | /** |
95 | * Timeout in communication with ARM | 105 | * Service starting was initiated |
96 | */ | 106 | */ |
97 | GNUNET_ARM_PROCESS_COMMUNICATION_TIMEOUT = 7, | 107 | GNUNET_ARM_SERVICE_STARTING = 2, |
98 | 108 | ||
99 | /** | 109 | /** |
100 | * Failure to perform operation | 110 | * Service stopping was initiated |
101 | */ | 111 | */ |
102 | GNUNET_ARM_PROCESS_FAILURE = 8 | 112 | GNUNET_ARM_SERVICE_STOPPING = 3 |
103 | }; | 113 | }; |
104 | 114 | ||
115 | /** | ||
116 | * Replies to ARM requests | ||
117 | */ | ||
118 | enum GNUNET_ARM_Result | ||
119 | { | ||
120 | /** | ||
121 | * Service was stopped (never sent for ARM itself). | ||
122 | */ | ||
123 | GNUNET_ARM_RESULT_STOPPED = 0, | ||
124 | |||
125 | /** | ||
126 | * ARM stopping was initiated (there's no "stopped" for ARM itself). | ||
127 | */ | ||
128 | GNUNET_ARM_RESULT_STOPPING = 1, | ||
129 | |||
130 | /** | ||
131 | * Service starting was initiated | ||
132 | */ | ||
133 | GNUNET_ARM_RESULT_STARTING = 2, | ||
134 | |||
135 | /** | ||
136 | * Asked to start it, but it's already starting. | ||
137 | */ | ||
138 | GNUNET_ARM_RESULT_IS_STARTING_ALREADY = 3, | ||
139 | |||
140 | /** | ||
141 | * Asked to stop it, but it's already stopping. | ||
142 | */ | ||
143 | GNUNET_ARM_RESULT_IS_STOPPING_ALREADY = 4, | ||
144 | |||
145 | /** | ||
146 | * Asked to start it, but it's already started. | ||
147 | */ | ||
148 | GNUNET_ARM_RESULT_IS_STARTED_ALREADY = 5, | ||
149 | |||
150 | /** | ||
151 | * Asked to stop it, but it's already stopped. | ||
152 | */ | ||
153 | GNUNET_ARM_RESULT_IS_STOPPED_ALREADY = 6, | ||
154 | |||
155 | /** | ||
156 | * Asked to start or stop a service, but it's not known. | ||
157 | */ | ||
158 | GNUNET_ARM_RESULT_IS_NOT_KNOWN = 7, | ||
159 | |||
160 | /** | ||
161 | * Tried to start a service, but that failed for some reason. | ||
162 | */ | ||
163 | GNUNET_ARM_RESULT_START_FAILED = 8, | ||
164 | |||
165 | /** | ||
166 | * Asked to start something, but ARM is shutting down and can't comply. | ||
167 | */ | ||
168 | GNUNET_ARM_RESULT_IN_SHUTDOWN = 9 | ||
169 | }; | ||
170 | |||
171 | |||
172 | /** | ||
173 | * Handle for interacting with ARM. | ||
174 | */ | ||
175 | struct GNUNET_ARM_Handle; | ||
176 | |||
105 | 177 | ||
106 | /** | 178 | /** |
107 | * Callback function invoked when operation is complete. | 179 | * Function called whenever we connect to or disconnect from ARM. |
108 | * | 180 | * |
109 | * @param cls closure | 181 | * @param cls closure |
110 | * @param result outcome of the operation | 182 | * @param connected GNUNET_YES if connected, GNUNET_NO if disconnected |
183 | * @param error GNUNET_YES if we encountered a permanent error, and there | ||
184 | * will be no re-connection. | ||
111 | */ | 185 | */ |
112 | typedef void (*GNUNET_ARM_Callback) (void *cls, | 186 | typedef void (*GNUNET_ARM_ConnectionStatusCallback) (void *cls, struct GNUNET_ARM_Handle *arm, unsigned char connected, unsigned char error); |
113 | enum GNUNET_ARM_ProcessStatus result); | 187 | |
114 | 188 | ||
115 | /** | 189 | /** |
116 | * Callback function invoked when list operation is complete. | 190 | * Function called in response to a start/stop request. |
191 | * Will be called when request was not sent successfully, | ||
192 | * or when a reply comes. If the request was not sent successfully, | ||
193 | * 'rs' will indicate that, and 'service' and 'result' will be undefined. | ||
117 | * | 194 | * |
118 | * @param cls closure | 195 | * @param cls closure |
119 | * @param result outcome of the operation (GNUNET_YES if successful) | 196 | * @param arm handle to the arm connection |
120 | * @param count number of strings in the list | 197 | * @param rs status of the request |
121 | * @param list list of running services | 198 | * @param service service name |
199 | * @param result result of the operation | ||
122 | */ | 200 | */ |
123 | typedef void (*GNUNET_ARM_List_Callback) (void *cls, | 201 | typedef void (*GNUNET_ARM_ResultCallback) (void *cls, struct GNUNET_ARM_Handle *arm, enum GNUNET_ARM_RequestStatus rs, const char *service, enum GNUNET_ARM_Result result); |
124 | int result, | ||
125 | unsigned int count, | ||
126 | const char *const *list); | ||
127 | 202 | ||
128 | 203 | ||
129 | /** | 204 | /** |
130 | * Handle for interacting with ARM. | 205 | * Callback function invoked when list operation is complete. |
206 | * Will be called when request was not sent successfully, | ||
207 | * or when a reply comes. If the request was not sent successfully, | ||
208 | * 'rs' will indicate that, and 'count' and 'list' will be undefined. | ||
209 | * | ||
210 | * @param cls closure | ||
211 | * @param arm handle to the arm connection | ||
212 | * @param rs status of the request | ||
213 | * @param count number of strings in the list | ||
214 | * @param list list of running services | ||
131 | */ | 215 | */ |
132 | struct GNUNET_ARM_Handle; | 216 | typedef void (*GNUNET_ARM_ServiceListCallback) (void *cls, struct GNUNET_ARM_Handle *arm, enum GNUNET_ARM_RequestStatus rs, unsigned int count, const char *const*list); |
133 | 217 | ||
134 | 218 | ||
135 | /** | 219 | /** |
136 | * Setup a context for communicating with ARM. Note that this | 220 | * Setup a context for communicating with ARM. Note that this |
137 | * can be done even if the ARM service is not yet running. | 221 | * can be done even if the ARM service is not yet running. |
222 | * Never fails. | ||
138 | * | 223 | * |
139 | * @param cfg configuration to use (needed to contact ARM; | 224 | * @param cfg configuration to use (needed to contact ARM; |
140 | * the ARM service may internally use a different | 225 | * the ARM service may internally use a different |
141 | * configuration to determine how to start the service). | 226 | * configuration to determine how to start the service). |
142 | * @param service service that *this* process is implementing/providing, can be NULL | 227 | * @return context to use for further ARM operations |
143 | * @return context to use for further ARM operations, NULL on error | ||
144 | */ | 228 | */ |
145 | struct GNUNET_ARM_Handle * | 229 | struct GNUNET_ARM_Handle * |
146 | GNUNET_ARM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | 230 | GNUNET_ARM_alloc (const struct GNUNET_CONFIGURATION_Handle *cfg); |
147 | const char *service); | 231 | |
232 | /** | ||
233 | * Start connecting to the ARM service using the context. | ||
234 | * @param conn_status called when we (dis)connect from/to ARM. | ||
235 | * It's also called on connection errors. | ||
236 | * @param cls closure for conn_status | ||
237 | * | ||
238 | * @param h ARM handle | ||
239 | */ | ||
240 | void | ||
241 | GNUNET_ARM_connect (struct GNUNET_ARM_Handle *h, | ||
242 | GNUNET_ARM_ConnectionStatusCallback conn_status, void *cls); | ||
148 | 243 | ||
149 | 244 | ||
150 | /** | 245 | /** |
151 | * Disconnect from the ARM service. | 246 | * Disconnect from the ARM service and destroy the handle. |
247 | * Don't call this from inside an ARM callback! | ||
152 | * | 248 | * |
153 | * @param h the handle that was being used | 249 | * @param h the handle that was being used |
154 | */ | 250 | */ |
@@ -157,60 +253,107 @@ GNUNET_ARM_disconnect (struct GNUNET_ARM_Handle *h); | |||
157 | 253 | ||
158 | 254 | ||
159 | /** | 255 | /** |
160 | * Start a service. Note that this function merely asks ARM to start | 256 | * Request a list of running services. |
161 | * the service and that ARM merely confirms that it forked the | ||
162 | * respective process. The specified callback may thus return before | ||
163 | * the service has started to listen on the server socket and it may | ||
164 | * also be that the service has crashed in the meantime. Clients | ||
165 | * should repeatedly try to connect to the service at the respective | ||
166 | * port (with some delays in between) before assuming that the service | ||
167 | * actually failed to start. Note that if an error is returned to the | ||
168 | * callback, clients obviously should not bother with trying to | ||
169 | * contact the service. | ||
170 | * | 257 | * |
171 | * @param h handle to ARM | 258 | * @param h handle to ARM |
172 | * @param service_name name of the service | ||
173 | * @param std_inheritance flags controlling std descriptors inheritance | ||
174 | * @param timeout how long to wait before failing for good | 259 | * @param timeout how long to wait before failing for good |
175 | * @param cb callback to invoke when service is ready | 260 | * @param cont callback to invoke after request is sent or is not sent |
176 | * @param cb_cls closure for callback | 261 | * @param cont_cls closure for callback |
177 | */ | 262 | */ |
178 | void | 263 | void |
179 | GNUNET_ARM_start_service (struct GNUNET_ARM_Handle *h, const char *service_name, | 264 | GNUNET_ARM_request_service_list (struct GNUNET_ARM_Handle *h, |
180 | enum GNUNET_OS_InheritStdioFlags std_inheritance, | 265 | struct GNUNET_TIME_Relative timeout, |
181 | struct GNUNET_TIME_Relative timeout, | 266 | GNUNET_ARM_ServiceListCallback cont, void *cont_cls); |
182 | GNUNET_ARM_Callback cb, void *cb_cls); | ||
183 | 267 | ||
184 | 268 | ||
185 | /** | 269 | /** |
186 | * Stop a service. Note that the callback is invoked as soon | 270 | * Request a service to be stopped. |
187 | * as ARM confirms that it will ask the service to terminate. | 271 | * Stopping arm itself will not invalidate its handle, and |
188 | * The actual termination may still take some time. | 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 () to free the handle and prevent | ||
275 | * further connection attempts. | ||
189 | * | 276 | * |
190 | * @param h handle to ARM | 277 | * @param h handle to ARM |
191 | * @param service_name name of the service | 278 | * @param service_name name of the service |
192 | * @param timeout how long to wait before failing for good | 279 | * @param timeout how long to wait before failing for good |
193 | * @param cb callback to invoke when service is ready | 280 | * @param cont callback to invoke after request is sent or is not sent |
194 | * @param cb_cls closure for callback | 281 | * @param cont_cls closure for callback |
195 | */ | 282 | */ |
196 | void | 283 | void |
197 | GNUNET_ARM_stop_service (struct GNUNET_ARM_Handle *h, const char *service_name, | 284 | GNUNET_ARM_request_service_stop (struct GNUNET_ARM_Handle *h, |
198 | struct GNUNET_TIME_Relative timeout, | 285 | const char *service_name, struct GNUNET_TIME_Relative timeout, |
199 | GNUNET_ARM_Callback cb, void *cb_cls); | 286 | GNUNET_ARM_ResultCallback cont, void *cont_cls); |
200 | 287 | ||
201 | 288 | ||
202 | /** | 289 | /** |
203 | * List all running services. | 290 | * Request for a service to be started. |
204 | * | 291 | * |
205 | * @param h handle to ARM | 292 | * @param h handle to ARM |
293 | * @param service_name name of the service | ||
294 | * @param std_inheritance inheritance of std streams | ||
206 | * @param timeout how long to wait before failing for good | 295 | * @param timeout how long to wait before failing for good |
207 | * @param cb callback to invoke when service is ready | 296 | * @param cont callback to invoke after request is sent or not sent |
208 | * @param cb_cls closure for callback | 297 | * @param cont_cls closure for callback |
209 | */ | 298 | */ |
210 | void | 299 | void |
211 | GNUNET_ARM_list_running_services (struct GNUNET_ARM_Handle *h, | 300 | GNUNET_ARM_request_service_start (struct GNUNET_ARM_Handle *h, |
212 | struct GNUNET_TIME_Relative timeout, | 301 | const char *service_name, enum GNUNET_OS_InheritStdioFlags std_inheritance, |
213 | GNUNET_ARM_List_Callback cb, void *cb_cls); | 302 | struct GNUNET_TIME_Relative timeout, GNUNET_ARM_ResultCallback cont, |
303 | void *cont_cls); | ||
304 | |||
305 | |||
306 | /** | ||
307 | * Handle for monitoring ARM. | ||
308 | */ | ||
309 | struct GNUNET_ARM_MonitorHandle; | ||
310 | |||
311 | |||
312 | /** | ||
313 | * Function called in when a status update arrives. | ||
314 | * | ||
315 | * @param cls closure | ||
316 | * @param arm handle to the arm connection | ||
317 | * @param service service name | ||
318 | * @param status status of the service | ||
319 | */ | ||
320 | typedef void (*GNUNET_ARM_ServiceStatusCallback) (void *cls, struct GNUNET_ARM_MonitorHandle *arm, const char *service, enum GNUNET_ARM_ServiceStatus status); | ||
321 | |||
322 | |||
323 | /** | ||
324 | * Setup a context for monitoring ARM. Note that this | ||
325 | * can be done even if the ARM service is not yet running. | ||
326 | * Never fails. | ||
327 | * | ||
328 | * @param cfg configuration to use (needed to contact ARM; | ||
329 | * the ARM service may internally use a different | ||
330 | * configuration to determine how to start the service). | ||
331 | * @return context to use for further ARM monitor operations | ||
332 | */ | ||
333 | struct GNUNET_ARM_MonitorHandle * | ||
334 | GNUNET_ARM_monitor_alloc (const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
335 | |||
336 | /** | ||
337 | * Start connecting to the ARM service for monitoring using the context. | ||
338 | * | ||
339 | * @param h ARM monitor handle | ||
340 | * @param cont callback to invoke on status updates | ||
341 | * @param cont_cls closure | ||
342 | */ | ||
343 | void | ||
344 | GNUNET_ARM_monitor (struct GNUNET_ARM_MonitorHandle *h, | ||
345 | GNUNET_ARM_ServiceStatusCallback cont, void *cont_cls); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Disconnect from the ARM service and destroy the handle. | ||
350 | * Don't call this from inside an ARM callback! | ||
351 | * | ||
352 | * @param h the handle that was being used | ||
353 | */ | ||
354 | void | ||
355 | GNUNET_ARM_monitor_disconnect (struct GNUNET_ARM_MonitorHandle *h); | ||
356 | |||
214 | 357 | ||
215 | #if 0 /* keep Emacsens' auto-indent happy */ | 358 | #if 0 /* keep Emacsens' auto-indent happy */ |
216 | { | 359 | { |