gnunet_service_lib.h (19825B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2009-2013, 2016, 2017 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 #if ! defined (__GNUNET_UTIL_LIB_H_INSIDE__) 23 #error "Only <gnunet_util_lib.h> can be included directly." 24 #endif 25 26 /** 27 * @addtogroup libgnunetutil 28 * Multi-function utilities library for GNUnet programs 29 * @{ 30 * 31 * @addtogroup networking 32 * @{ 33 * 34 * @author Christian Grothoff 35 * 36 * @file 37 * Functions related to starting services 38 * 39 * @defgroup service Service library 40 * Start service processes. 41 * 42 * @see [Documentation](https://gnunet.org/developer-handbook-util-services) 43 * 44 * @{ 45 */ 46 47 #ifndef GNUNET_SERVICE_LIB_H 48 #define GNUNET_SERVICE_LIB_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #if 0 /* keep Emacsens' auto-indent happy */ 54 } 55 #endif 56 #endif 57 58 #include "gnunet_util_lib.h" 59 #include "gnunet_configuration_lib.h" 60 61 62 /** 63 * Options for the service (bitmask). 64 */ 65 enum GNUNET_SERVICE_Options 66 { 67 /** 68 * Use defaults. Terminates all client connections and the listen 69 * sockets immediately upon receiving the shutdown signal. 70 */ 71 GNUNET_SERVICE_OPTION_NONE = 0, 72 73 /** 74 * Do not trigger server shutdown on signal at all; instead, allow 75 * for the user to terminate the server explicitly when needed 76 * by calling #GNUNET_SERVICE_shutdown(). 77 */ 78 GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1, 79 80 /** 81 * Trigger a SOFT server shutdown on signals, allowing active 82 * non-monitor clients to complete their transactions. 83 */ 84 GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2, 85 86 /** 87 * Bitmask over the shutdown options. 88 */ 89 GNUNET_SERVICE_OPTION_SHUTDOWN_BITMASK = 3, 90 91 /** 92 * Instead of listening on lsocks passed by the parent, 93 * close them *after* opening our own listen socket(s). 94 */ 95 GNUNET_SERVICE_OPTION_CLOSE_LSOCKS = 4 96 }; 97 98 99 /* **************** NEW SERVICE API ********************** */ 100 101 /** 102 * Handle to a service. 103 */ 104 struct GNUNET_SERVICE_Handle; 105 106 107 /** 108 * Handle to a client that is connected to a service. 109 */ 110 struct GNUNET_SERVICE_Client; 111 112 113 /** 114 * Callback to initialize a service, called exactly once when the service is run. 115 * 116 * @param cls closure passed to #GNUNET_SERVICE_MAIN 117 * @param cfg configuration to use for this service 118 * @param sh handle to the newly create service 119 */ 120 typedef void 121 (*GNUNET_SERVICE_InitCallback)(void *cls, 122 const struct GNUNET_CONFIGURATION_Handle *cfg, 123 struct GNUNET_SERVICE_Handle *sh); 124 125 126 /** 127 * Callback to be called when a client connects to the service. 128 * 129 * @param cls closure for the service 130 * @param c the new client that connected to the service 131 * @param mq the message queue used to send messages to the client 132 * @return the client-specific (`internal') closure 133 */ 134 typedef void * 135 (*GNUNET_SERVICE_ConnectHandler)(void *cls, 136 struct GNUNET_SERVICE_Client *c, 137 struct GNUNET_MQ_Handle *mq); 138 139 140 /** 141 * Callback to be called when a client disconnected from the service 142 * 143 * @param cls closure for the service 144 * @param c the client that disconnected 145 * @param internal_cls the client-specific (`internal') closure 146 */ 147 typedef void 148 (*GNUNET_SERVICE_DisconnectHandler)(void *cls, 149 struct GNUNET_SERVICE_Client *c, 150 void *internal_cls); 151 152 153 /** 154 * Low-level function to start a service if the scheduler 155 * is already running. Should only be used directly in 156 * special cases. 157 * 158 * The function will launch the service with the name @a service_name 159 * using the @a service_options to configure its shutdown 160 * behavior. When clients connect or disconnect, the respective 161 * @a connect_cb or @a disconnect_cb functions will be called. For 162 * messages received from the clients, the respective @a handlers will 163 * be invoked; for the closure of the handlers we use the return value 164 * from the @a connect_cb invocation of the respective client. 165 * 166 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each 167 * message to receive further messages from this client. If 168 * #GNUNET_SERVICE_client_continue() is not called within a short 169 * time, a warning will be logged. If delays are expected, services 170 * should call #GNUNET_SERVICE_client_disable_continue_warning() to 171 * disable the warning. 172 * 173 * Clients sending invalid messages (based on @a handlers) will be 174 * dropped. Additionally, clients can be dropped at any time using 175 * #GNUNET_SERVICE_client_drop(). 176 * 177 * The service must be stopped using #GNUNET_SERVICE_stop(). 178 * 179 * @param pd project data for the service 180 * @param service_name name of the service to run 181 * @param cfg configuration to use 182 * @param connect_cb function to call whenever a client connects 183 * @param disconnect_cb function to call whenever a client disconnects 184 * @param cls closure argument for @a connect_cb and @a disconnect_cb 185 * @param handlers NULL-terminated array of message handlers for the service, 186 * the closure will be set to the value returned by 187 * the @a connect_cb for the respective connection 188 * @return NULL on error 189 */ 190 struct GNUNET_SERVICE_Handle * 191 GNUNET_SERVICE_start (const struct GNUNET_OS_ProjectData *pd, 192 const char *service_name, 193 const struct GNUNET_CONFIGURATION_Handle *cfg, 194 GNUNET_SERVICE_ConnectHandler connect_cb, 195 GNUNET_SERVICE_DisconnectHandler disconnect_cb, 196 void *cls, 197 const struct GNUNET_MQ_MessageHandler *handlers); 198 199 200 /** 201 * Stops a service that was started with #GNUNET_SERVICE_start(). 202 * 203 * @param srv service to stop 204 */ 205 void 206 GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Handle *srv); 207 208 /** 209 * Creates the "main" function for a GNUnet service. You 210 * should almost always use the #GNUNET_SERVICE_MAIN macro 211 * instead of calling this function directly (except 212 * for ARM, which should call this function directly). 213 * 214 * The function will launch the service with the name @a service_name 215 * using the @a service_options to configure its shutdown 216 * behavior. Once the service is ready, the @a init_cb will be called 217 * for service-specific initialization. @a init_cb will be given the 218 * service handler which can be used to control the service's 219 * availability. When clients connect or disconnect, the respective 220 * @a connect_cb or @a disconnect_cb functions will be called. For 221 * messages received from the clients, the respective @a handlers will 222 * be invoked; for the closure of the handlers we use the return value 223 * from the @a connect_cb invocation of the respective client. 224 * 225 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each 226 * message to receive further messages from this client. If 227 * #GNUNET_SERVICE_client_continue() is not called within a short 228 * time, a warning will be logged. If delays are expected, services 229 * should call #GNUNET_SERVICE_client_disable_continue_warning() to 230 * disable the warning. 231 * 232 * Clients sending invalid messages (based on @a handlers) will be 233 * dropped. Additionally, clients can be dropped at any time using 234 * #GNUNET_SERVICE_client_drop(). 235 * 236 * @param pd project data for the service 237 * @param argc number of command-line arguments in @a argv 238 * @param argv array of command-line arguments 239 * @param service_name name of the service to run 240 * @param options options controlling shutdown of the service 241 * @param service_init_cb function to call once the service is ready 242 * @param connect_cb function to call whenever a client connects 243 * @param disconnect_cb function to call whenever a client disconnects 244 * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb 245 * @param handlers NULL-terminated array of message handlers for the service, 246 * the closure will be set to the value returned by 247 * the @a connect_cb for the respective connection 248 * @return 0 on success, non-zero on error 249 */ 250 int 251 GNUNET_SERVICE_run_ (const struct GNUNET_OS_ProjectData *pd, 252 int argc, 253 char *const *argv, 254 const char *service_name, 255 enum GNUNET_SERVICE_Options options, 256 GNUNET_SERVICE_InitCallback service_init_cb, 257 GNUNET_SERVICE_ConnectHandler connect_cb, 258 GNUNET_SERVICE_DisconnectHandler disconnect_cb, 259 void *cls, 260 const struct GNUNET_MQ_MessageHandler *handlers); 261 262 263 /** 264 * Registers the GNUnet service to be scheduled as part of a monilithic 265 * libgnunet. 266 * You should almost always use the #GNUNET_SERVICE_MAIN macro 267 * instead of calling this function directly. 268 * 269 * The function will launch the service with the name @a service_name 270 * using the @a service_options to configure its shutdown 271 * behavior. Once the service is ready, the @a init_cb will be called 272 * for service-specific initialization. @a init_cb will be given the 273 * service handler which can be used to control the service's 274 * availability. When clients connect or disconnect, the respective 275 * @a connect_cb or @a disconnect_cb functions will be called. For 276 * messages received from the clients, the respective @a handlers will 277 * be invoked; for the closure of the handlers we use the return value 278 * from the @a connect_cb invocation of the respective client. 279 * 280 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each 281 * message to receive further messages from this client. If 282 * #GNUNET_SERVICE_client_continue() is not called within a short 283 * time, a warning will be logged. If delays are expected, services 284 * should call #GNUNET_SERVICE_client_disable_continue_warning() to 285 * disable the warning. 286 * 287 * Clients sending invalid messages (based on @a handlers) will be 288 * dropped. Additionally, clients can be dropped at any time using 289 * #GNUNET_SERVICE_client_drop(). 290 * 291 * @param pd project data for the service 292 * @param service_name name of the service to run 293 * @param options options controlling shutdown of the service 294 * @param service_init_cb function to call once the service is ready 295 * @param connect_cb function to call whenever a client connects 296 * @param disconnect_cb function to call whenever a client disconnects 297 * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb 298 * @param handlers NULL-terminated array of message handlers for the service, 299 * the closure will be set to the value returned by 300 * the @a connect_cb for the respective connection 301 * @return 0 on success, non-zero on error 302 */ 303 int 304 GNUNET_SERVICE_register_ ( 305 const struct GNUNET_OS_ProjectData *pd, 306 const char *service_name, 307 enum GNUNET_SERVICE_Options options, 308 GNUNET_SERVICE_InitCallback service_init_cb, 309 GNUNET_SERVICE_ConnectHandler connect_cb, 310 GNUNET_SERVICE_DisconnectHandler disconnect_cb, 311 void *cls, 312 const struct GNUNET_MQ_MessageHandler *handlers); 313 314 315 /** 316 * Creates the "main" function for a GNUnet service. You 317 * MUST use this macro to define GNUnet services (except 318 * for ARM, which MUST NOT use the macro). The reason is 319 * the GNUnet-as-a-library project, where we will not define 320 * a main function anywhere but in ARM. 321 * 322 * The macro will launch the service with the name @a service_name 323 * using the @a service_options to configure its shutdown 324 * behavior. Once the service is ready, the @a init_cb will be called 325 * for service-specific initialization. @a init_cb will be given the 326 * service handler which can be used to control the service's 327 * availability. When clients connect or disconnect, the respective 328 * @a connect_cb or @a disconnect_cb functions will be called. For 329 * messages received from the clients, the respective @a handlers will 330 * be invoked; for the closure of the handlers we use the return value 331 * from the @a connect_cb invocation of the respective client. 332 * 333 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each 334 * message to receive further messages from this client. If 335 * #GNUNET_SERVICE_client_continue() is not called within a short 336 * time, a warning will be logged. If delays are expected, services 337 * should call #GNUNET_SERVICE_client_disable_continue_warning() to 338 * disable the warning. 339 * 340 * Clients sending invalid messages (based on @a handlers) will be 341 * dropped. Additionally, clients can be dropped at any time using 342 * #GNUNET_SERVICE_client_drop(). 343 * 344 * @param service_name name of the service to run 345 * @param service_options options controlling shutdown of the service 346 * @param init_cb function to call once the service is ready 347 * @param connect_cb function to call whenever a client connects 348 * @param disconnect_cb function to call whenever a client disconnects 349 * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb 350 * @param ... array of message handlers for the service, terminated 351 * by #GNUNET_MQ_handler_end(); 352 * the closure will be set to the value returned by 353 * the @a connect_cb for the respective connection 354 * @return 0 on success, non-zero on error 355 * 356 * Sample invocation: 357 * <code> 358 * GNUNET_SERVICE_MAIN 359 * ("resolver", 360 * GNUNET_SERVICE_OPTION_NONE, 361 * &init_cb, 362 * &connect_cb, 363 * &disconnect_cb, 364 * closure_for_cb, 365 * GNUNET_MQ_hd_var_size (get, 366 * GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST, 367 * struct GNUNET_RESOLVER_GetMessage, 368 * NULL), 369 * GNUNET_MQ_handler_end ()); 370 * </code> 371 */ 372 #ifndef HAVE_GNUNET_MONOLITH 373 #define GNUNET_SERVICE_MAIN(pd, service_name, service_options, init_cb, \ 374 connect_cb, \ 375 disconnect_cb, cls, ...) \ 376 int \ 377 main (int argc, \ 378 char *const *argv) \ 379 { \ 380 struct GNUNET_MQ_MessageHandler mh[] = { \ 381 __VA_ARGS__ \ 382 }; \ 383 return GNUNET_SERVICE_run_ (pd, \ 384 argc, \ 385 argv, \ 386 service_name, \ 387 service_options, \ 388 init_cb, \ 389 connect_cb, \ 390 disconnect_cb, \ 391 cls, \ 392 mh); \ 393 } 394 #else 395 #define GNUNET_SERVICE_MAIN(pd, service_name, service_options, init_cb, \ 396 connect_cb, \ 397 disconnect_cb, cls, ...) \ 398 static int __attribute__ ((constructor)) \ 399 init (void) \ 400 { \ 401 struct GNUNET_MQ_MessageHandler mh[] = { \ 402 __VA_ARGS__ \ 403 }; \ 404 return GNUNET_SERVICE_register_ (pd, \ 405 service_name, \ 406 service_options, \ 407 init_cb, \ 408 connect_cb, \ 409 disconnect_cb, \ 410 cls, \ 411 mh); \ 412 } 413 #endif 414 415 /** 416 * Run the mainloop in a monolithic libgnunet. 417 * Must be called such that services are actually launched. 418 */ 419 void 420 GNUNET_SERVICE_main (const struct GNUNET_OS_ProjectData *pd, 421 int argc, 422 char *const *argv, 423 struct GNUNET_CONFIGURATION_Handle *cfg, 424 enum GNUNET_GenericReturnValue with_scheduler); 425 426 /** 427 * Suspend accepting connections from the listen socket temporarily. 428 * Resume activity using #GNUNET_SERVICE_resume. 429 * 430 * @param sh service to stop accepting connections. 431 */ 432 void 433 GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh); 434 435 436 /** 437 * Resume accepting connections from the listen socket. 438 * 439 * @param sh service to resume accepting connections. 440 */ 441 void 442 GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh); 443 444 445 /** 446 * Continue receiving further messages from the given client. 447 * Must be called after each message received. 448 * 449 * @param c the client to continue receiving from 450 */ 451 void 452 GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c); 453 454 455 /** 456 * Obtain the message queue of @a c. Convenience function. 457 * 458 * @param c the client to continue receiving from 459 * @return the message queue of @a c 460 */ 461 struct GNUNET_MQ_Handle * 462 GNUNET_SERVICE_client_get_mq (struct GNUNET_SERVICE_Client *c); 463 464 465 /** 466 * Disable the warning the server issues if a message is not 467 * acknowledged in a timely fashion. Use this call if a client is 468 * intentionally delayed for a while. Only applies to the current 469 * message. 470 * 471 * @param c client for which to disable the warning 472 */ 473 void 474 GNUNET_SERVICE_client_disable_continue_warning ( 475 struct GNUNET_SERVICE_Client *c); 476 477 478 /** 479 * Ask the server to disconnect from the given client. This is the 480 * same as returning #GNUNET_SYSERR within the check procedure when 481 * handling a message, except that it allows dropping of a client even 482 * when not handling a message from that client. The `disconnect_cb` 483 * will be called on @a c even if the application closes the connection 484 * using this function. 485 * 486 * This function should be called (outside of util's internal logic) 487 * if (and usually only if) the client has violated the 488 * protocol. Otherwise, we should leave it to the client to disconnect 489 * from the service. 490 * 491 * @param c client to disconnect now 492 */ 493 void 494 GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c); 495 496 497 /** 498 * Explicitly stops the service. 499 * 500 * @param sh server to shutdown 501 */ 502 void 503 GNUNET_SERVICE_shutdown (struct GNUNET_SERVICE_Handle *sh); 504 505 506 /** 507 * Set the 'monitor' flag on this client. Clients which have been 508 * marked as 'monitors' won't prevent the server from shutting down 509 * once #GNUNET_SERVICE_stop_listening() has been invoked. The idea is 510 * that for "normal" clients we likely want to allow them to process 511 * their requests; however, monitor-clients are likely to 'never' 512 * disconnect during shutdown and thus will not be considered when 513 * determining if the server should continue to exist after 514 * shutdown has been triggered. 515 * 516 * @param c client to mark as a monitor 517 */ 518 void 519 GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c); 520 521 522 /** 523 * Set the persist option on this client. Indicates that the 524 * underlying socket or fd should never really be closed. Used for 525 * indicating process death. 526 * 527 * @param c client to persist the socket (never to be closed) 528 */ 529 void 530 GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c); 531 532 533 #if 0 /* keep Emacsens' auto-indent happy */ 534 { 535 #endif 536 #ifdef __cplusplus 537 } 538 #endif 539 540 /* ifndef GNUNET_SERVICE_LIB_H */ 541 #endif 542 543 /** @} */ /* end of group service */ 544 545 /** @} */ /* end of group addition to networking*/ 546 547 /** @} */ /* end of group addition to libgnunetutil */ 548 549 /* end of gnunet_service_lib.h */