diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-08-09 15:43:48 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-08-09 15:43:48 +0000 |
commit | 189e703a007d7950842e71399526a3b11ef5a6ac (patch) | |
tree | b1a6cacbee35ee953048e183233297bf81d7eeed /src/include/gnunet_service_lib.h | |
parent | 922318150433906dafd11adb5185a6ff664573db (diff) | |
download | gnunet-189e703a007d7950842e71399526a3b11ef5a6ac.tar.gz gnunet-189e703a007d7950842e71399526a3b11ef5a6ac.zip |
-proposal for new service API
Diffstat (limited to 'src/include/gnunet_service_lib.h')
-rw-r--r-- | src/include/gnunet_service_lib.h | 235 |
1 files changed, 231 insertions, 4 deletions
diff --git a/src/include/gnunet_service_lib.h b/src/include/gnunet_service_lib.h index d15b41a29..a3ad76f60 100644 --- a/src/include/gnunet_service_lib.h +++ b/src/include/gnunet_service_lib.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet. | 2 | This file is part of GNUnet. |
3 | Copyright (C) 2009-2013 GNUnet e.V. | 3 | Copyright (C) 2009-2013, 2016 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software; you can redistribute it and/or modify | 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 | 6 | it under the terms of the GNU General Public License as published |
@@ -45,6 +45,7 @@ extern "C" | |||
45 | 45 | ||
46 | #include "gnunet_configuration_lib.h" | 46 | #include "gnunet_configuration_lib.h" |
47 | #include "gnunet_server_lib.h" | 47 | #include "gnunet_server_lib.h" |
48 | #include "gnunet_mq_lib.h" | ||
48 | 49 | ||
49 | 50 | ||
50 | /** | 51 | /** |
@@ -69,8 +70,8 @@ extern "C" | |||
69 | */ | 70 | */ |
70 | int | 71 | int |
71 | GNUNET_SERVICE_get_server_addresses (const char *service_name, | 72 | GNUNET_SERVICE_get_server_addresses (const char *service_name, |
72 | const struct GNUNET_CONFIGURATION_Handle | 73 | const struct GNUNET_CONFIGURATION_Handle *cfg, |
73 | *cfg, struct sockaddr ***addrs, | 74 | struct sockaddr ***addrs, |
74 | socklen_t **addr_lens); | 75 | socklen_t **addr_lens); |
75 | 76 | ||
76 | 77 | ||
@@ -124,9 +125,11 @@ enum GNUNET_SERVICE_Options | |||
124 | * @param task_cls closure for @a task | 125 | * @param task_cls closure for @a task |
125 | * @return #GNUNET_SYSERR on error, #GNUNET_OK | 126 | * @return #GNUNET_SYSERR on error, #GNUNET_OK |
126 | * if we shutdown nicely | 127 | * if we shutdown nicely |
128 | * @deprecated | ||
127 | */ | 129 | */ |
128 | int | 130 | int |
129 | GNUNET_SERVICE_run (int argc, char *const *argv, | 131 | GNUNET_SERVICE_run (int argc, |
132 | char *const *argv, | ||
130 | const char *service_name, | 133 | const char *service_name, |
131 | enum GNUNET_SERVICE_Options options, | 134 | enum GNUNET_SERVICE_Options options, |
132 | GNUNET_SERVICE_Main task, | 135 | GNUNET_SERVICE_Main task, |
@@ -147,6 +150,7 @@ struct GNUNET_SERVICE_Context; | |||
147 | * @param cfg configuration to use | 150 | * @param cfg configuration to use |
148 | * @param options service options | 151 | * @param options service options |
149 | * @return NULL on error, service handle | 152 | * @return NULL on error, service handle |
153 | * @deprecated | ||
150 | */ | 154 | */ |
151 | struct GNUNET_SERVICE_Context * | 155 | struct GNUNET_SERVICE_Context * |
152 | GNUNET_SERVICE_start (const char *service_name, | 156 | GNUNET_SERVICE_start (const char *service_name, |
@@ -160,6 +164,7 @@ GNUNET_SERVICE_start (const char *service_name, | |||
160 | * | 164 | * |
161 | * @param ctx the service context returned from the start function | 165 | * @param ctx the service context returned from the start function |
162 | * @return handle to the server for this service, NULL if there is none | 166 | * @return handle to the server for this service, NULL if there is none |
167 | * @deprecated | ||
163 | */ | 168 | */ |
164 | struct GNUNET_SERVER_Handle * | 169 | struct GNUNET_SERVER_Handle * |
165 | GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx); | 170 | GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx); |
@@ -171,6 +176,7 @@ GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx); | |||
171 | * @param ctx service context to query | 176 | * @param ctx service context to query |
172 | * @return NULL if there are no listen sockets, otherwise NULL-terminated | 177 | * @return NULL if there are no listen sockets, otherwise NULL-terminated |
173 | * array of listen sockets. | 178 | * array of listen sockets. |
179 | * @deprecated | ||
174 | */ | 180 | */ |
175 | struct GNUNET_NETWORK_Handle *const * | 181 | struct GNUNET_NETWORK_Handle *const * |
176 | GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx); | 182 | GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx); |
@@ -180,11 +186,232 @@ GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx); | |||
180 | * Stop a service that was started with #GNUNET_SERVICE_start. | 186 | * Stop a service that was started with #GNUNET_SERVICE_start. |
181 | * | 187 | * |
182 | * @param sctx the service context returned from the start function | 188 | * @param sctx the service context returned from the start function |
189 | * @deprecated | ||
183 | */ | 190 | */ |
184 | void | 191 | void |
185 | GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx); | 192 | GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx); |
186 | 193 | ||
187 | 194 | ||
195 | /* **************** NEW SERVICE API ********************** */ | ||
196 | |||
197 | /** | ||
198 | * | ||
199 | */ | ||
200 | struct GNUNET_SERVICE_Handle; | ||
201 | |||
202 | |||
203 | /** | ||
204 | * | ||
205 | */ | ||
206 | struct GNUNET_SERVICE_Client; | ||
207 | |||
208 | |||
209 | /** | ||
210 | * | ||
211 | * | ||
212 | * @param cls | ||
213 | * @param cfg | ||
214 | * @param sh | ||
215 | */ | ||
216 | typedef void | ||
217 | (*GNUNET_SERVICE_InitCallback)(void *cls, | ||
218 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
219 | struct GNUNET_SERVICE_Handle *sh); | ||
220 | |||
221 | |||
222 | /** | ||
223 | * | ||
224 | * | ||
225 | * @param cls | ||
226 | * @param c | ||
227 | * @param mq | ||
228 | * @return | ||
229 | */ | ||
230 | typedef void * | ||
231 | (*GNUNET_SERVICE_ConnectHandler)(void *cls, | ||
232 | struct GNUNET_SERVICE_Client *c, | ||
233 | struct GNUNET_MQ_Handle *mq); | ||
234 | |||
235 | |||
236 | /** | ||
237 | * | ||
238 | * | ||
239 | * @param cls | ||
240 | * @param c | ||
241 | * @param internal_cls | ||
242 | */ | ||
243 | typedef void | ||
244 | (*GNUNET_SERVICE_DisconnectHandler)(void *cls, | ||
245 | struct GNUNET_SERVICE_Client *c, | ||
246 | void *internal_cls); | ||
247 | |||
248 | |||
249 | /** | ||
250 | * Creates the "main" function for a GNUnet service. You | ||
251 | * should almost always use the #GNUNET_SERVICE_MAIN macro | ||
252 | * instead of calling this function directly (except | ||
253 | * for ARM, which should call this function directly). | ||
254 | * | ||
255 | * The function will launch the service with the name @a service_name | ||
256 | * using the @a service_options to configure its shutdown | ||
257 | * behavior. Once the service is ready, the @a init_cb will be called | ||
258 | * for service-specific initialization. @a init_cb will be given the | ||
259 | * service handler which can be used to control the service's | ||
260 | * availability. When clients connect or disconnect, the respective | ||
261 | * @a connect_cb or @a disconnect_cb functions will be called. For | ||
262 | * messages received from the clients, the respective @a handlers will | ||
263 | * be invoked; for the closure of the handlers we use the return value | ||
264 | * from the @a connect_cb invocation of the respective client. | ||
265 | * | ||
266 | * Each handler MUST call #GNUNET_SERVICE_client_continue() after each | ||
267 | * message to receive further messages from this client. If | ||
268 | * #GNUNET_SERVICE_client_continue() is not called within a short | ||
269 | * time, a warning will be logged. If delays are expected, services | ||
270 | * should call #GNUNET_SERVICE_client_disable_continue_warning() to | ||
271 | * disable the warning. | ||
272 | * | ||
273 | * Clients sending invalid messages (based on @a handlers) will be | ||
274 | * dropped. Additionally, clients can be dropped at any time using | ||
275 | * #GNUNET_SERVICE_client_drop(). | ||
276 | * | ||
277 | * @param argc | ||
278 | * @param argv | ||
279 | * @param service_name | ||
280 | * @param options | ||
281 | * @param service_init_cb | ||
282 | * @param connect_cb | ||
283 | * @param disconnect_cb | ||
284 | * @param cls | ||
285 | * @param handlers | ||
286 | * @return 0 on success, non-zero on error | ||
287 | */ | ||
288 | int | ||
289 | GNUNET_SERVICE_ruN_ (int argc, | ||
290 | char *const *argv, | ||
291 | const char *service_name, | ||
292 | enum GNUNET_SERVICE_Options options, | ||
293 | GNUNET_SERVICE_InitCallback service_init_cb, | ||
294 | GNUNET_SERVICE_ConnectHandler connect_cb, | ||
295 | GNUNET_SERVICE_DisconnectHandler disconnect_cb, | ||
296 | void *cls, | ||
297 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
298 | |||
299 | |||
300 | /** | ||
301 | * Creates the "main" function for a GNUnet service. You | ||
302 | * MUST use this macro to define GNUnet services (except | ||
303 | * for ARM, which MUST NOT use the macro). The reason is | ||
304 | * the GNUnet-as-a-library project, where we will not define | ||
305 | * a main function anywhere but in ARM. | ||
306 | * | ||
307 | * The macro will launch the service with the name @a service_name | ||
308 | * using the @a service_options to configure its shutdown | ||
309 | * behavior. Once the service is ready, the @a init_cb will be called | ||
310 | * for service-specific initialization. @a init_cb will be given the | ||
311 | * service handler which can be used to control the service's | ||
312 | * availability. When clients connect or disconnect, the respective | ||
313 | * @a connect_cb or @a disconnect_cb functions will be called. For | ||
314 | * messages received from the clients, the respective @a handlers will | ||
315 | * be invoked; for the closure of the handlers we use the return value | ||
316 | * from the @a connect_cb invocation of the respective client. | ||
317 | * | ||
318 | * Each handler MUST call #GNUNET_SERVICE_client_continue() after each | ||
319 | * message to receive further messages from this client. If | ||
320 | * #GNUNET_SERVICE_client_continue() is not called within a short | ||
321 | * time, a warning will be logged. If delays are expected, services | ||
322 | * should call #GNUNET_SERVICE_client_disable_continue_warning() to | ||
323 | * disable the warning. | ||
324 | * | ||
325 | * Clients sending invalid messages (based on @a handlers) will be | ||
326 | * dropped. Additionally, clients can be dropped at any time using | ||
327 | * #GNUNET_SERVICE_client_drop(). | ||
328 | * | ||
329 | * @param argc | ||
330 | * @param argv | ||
331 | * @param service_name | ||
332 | * @param options | ||
333 | * @param service_init_cb | ||
334 | * @param connect_cb | ||
335 | * @param disconnect_cb | ||
336 | * @param cls | ||
337 | * @param handlers | ||
338 | * @return 0 on success, non-zero on error | ||
339 | */ | ||
340 | #define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,handlers) \ | ||
341 | int \ | ||
342 | main (int argc,\ | ||
343 | char *const *argv)\ | ||
344 | { \ | ||
345 | return GNUNET_SERVICE_ruN_ (argc, \ | ||
346 | argv, \ | ||
347 | service_name, \ | ||
348 | service_options, \ | ||
349 | init_cb, \ | ||
350 | connect_cb, \ | ||
351 | disconnect_cb, \ | ||
352 | cls, \ | ||
353 | handlers); \ | ||
354 | } | ||
355 | |||
356 | |||
357 | /** | ||
358 | * | ||
359 | * @param sh | ||
360 | */ | ||
361 | void | ||
362 | GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh); | ||
363 | |||
364 | /** | ||
365 | * | ||
366 | * @param sh | ||
367 | */ | ||
368 | void | ||
369 | GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh); | ||
370 | |||
371 | /** | ||
372 | * | ||
373 | * @param c | ||
374 | */ | ||
375 | void | ||
376 | GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c); | ||
377 | |||
378 | /** | ||
379 | * | ||
380 | * @param c | ||
381 | */ | ||
382 | void | ||
383 | GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c); | ||
384 | |||
385 | /** | ||
386 | * | ||
387 | * @param c | ||
388 | */ | ||
389 | void | ||
390 | GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c); | ||
391 | |||
392 | /** | ||
393 | * | ||
394 | * @param sh | ||
395 | */ | ||
396 | void | ||
397 | GNUNET_SERVICE_stop_listening (struct GNUNET_SERVICE_Handle *sh); | ||
398 | |||
399 | /** | ||
400 | * | ||
401 | * @param c | ||
402 | */ | ||
403 | void | ||
404 | GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c); | ||
405 | |||
406 | /** | ||
407 | * | ||
408 | * @param c | ||
409 | */ | ||
410 | void | ||
411 | GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c); | ||
412 | |||
413 | |||
414 | |||
188 | #if 0 /* keep Emacsens' auto-indent happy */ | 415 | #if 0 /* keep Emacsens' auto-indent happy */ |
189 | { | 416 | { |
190 | #endif | 417 | #endif |