src/include/gnunet_server_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2013 GNUnet e.V.
   4
   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.
   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      General Public License for more details.
  14
  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.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Library for building GNUnet network servers
  26
  27  * @defgroup server  Server library
  28  * Library for building GNUnet network servers
  29  *
  30  * Provides functions for a server that communicates with clients.
  31  *
  32  * @see [Documentation](https://gnunet.org/ipc)
  33  *
  34  * @{
  35  */
  36
  37 #ifndef GNUNET_SERVER_LIB_H
  38 #define GNUNET_SERVER_LIB_H
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #if 0                           /* keep Emacsens' auto-indent happy */
  44 }
  45 #endif
  46 #endif
  47
  48 #include "gnunet_common.h"
  49 #include "gnunet_connection_lib.h"
  50
  51
  52 /**
  53  * Largest supported message (to be precise, one byte more
  54  * than the largest possible message, so tests involving
  55  * this value should check for messages being smaller than
  56  * this value).
  57  */
  58 #define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536
  59
  60 /**
  61  * Smallest supported message.
  62  */
  63 #define GNUNET_SERVER_MIN_BUFFER_SIZE sizeof (struct GNUNET_MessageHeader)
  64
  65 /**
  66  * @brief handle for a server
  67  */
  68 struct GNUNET_SERVER_Handle;
  69
  70 /**
  71  * @brief opaque handle for a client of the server
  72  */
  73 struct GNUNET_SERVER_Client;
  74
  75 /**
  76  * @brief opaque handle server returns for aborting transmission to a client.
  77  */
  78 struct GNUNET_SERVER_TransmitHandle;
  79
  80
  81 /**
  82  * Functions with this signature are called whenever a message is
  83  * received.
  84  *
  85  * @param cls closure
  86  * @param client identification of the client
  87  * @param message the actual message
  88  */
  89 typedef void
  90 (*GNUNET_SERVER_MessageCallback) (void *cls,
  91                                   struct GNUNET_SERVER_Client *client,
  92                                   const struct GNUNET_MessageHeader *message);
  93
  94
  95 /**
  96  * Message handler.  Each struct specifies how to handle on particular
  97  * type of message received.
  98  */
  99 struct GNUNET_SERVER_MessageHandler
 100 {
 101   /**
 102    * Function to call for messages of "type".
 103    */
 104   GNUNET_SERVER_MessageCallback callback;
 105
 106   /**
 107    * Closure argument for @e callback.
 108    */
 109   void *callback_cls;
 110
 111   /**
 112    * Type of the message this handler covers.
 113    */
 114   uint16_t type;
 115
 116   /**
 117    * Expected size of messages of this type.  Use 0 for
 118    * variable-size.  If non-zero, messages of the given
 119    * type will be discarded (and the connection closed)
 120    * if they do not have the right size.
 121    */
 122   uint16_t expected_size;
 123
 124 };
 125
 126
 127 /**
 128  * Create a new server.
 129  *
 130  * @param access_cb function for access control
 131  * @param access_cb_cls closure for @a access_cb
 132  * @param lsocks NULL-terminated array of listen sockets
 133  * @param idle_timeout after how long should we timeout idle connections?
 134  * @param require_found if #GNUNET_YES, connections sending messages of unknown type
 135  *        will be closed
 136  * @return handle for the new server, NULL on error
 137  *         (typically, "port" already in use)
 138  */
 139 struct GNUNET_SERVER_Handle *
 140 GNUNET_SERVER_create_with_sockets (GNUNET_CONNECTION_AccessCheck access_cb,
 141                                    void *access_cb_cls,
 142                                    struct GNUNET_NETWORK_Handle **lsocks,
 143                                    struct GNUNET_TIME_Relative idle_timeout,
 144                                    int require_found);
 145
 146 /**
 147  * Create a new server.
 148  *
 149  * @param access_cb function for access control
 150  * @param access_cb_cls closure for @a access_cb
 151  * @param server_addr address toes listen on (including port), NULL terminated array
 152  * @param socklen lengths of respective @a server_addr
 153  * @param idle_timeout after how long should we timeout idle connections?
 154  * @param require_found if #GNUNET_YES, connections sending messages of unknown type
 155  *        will be closed
 156  * @return handle for the new server, NULL on error
 157  *         (typically, "port" already in use)
 158  */
 159 struct GNUNET_SERVER_Handle *
 160 GNUNET_SERVER_create (GNUNET_CONNECTION_AccessCheck access_cb,
 161                       void *access_cb_cls,
 162                       struct sockaddr *const *server_addr,
 163                       const socklen_t * socklen,
 164                       struct GNUNET_TIME_Relative idle_timeout,
 165                       int require_found);
 166
 167
 168 /**
 169  * Suspend accepting connections from the listen socket temporarily.
 170  * Resume activity using #GNUNET_SERVER_resume.
 171  *
 172  * @param server server to stop accepting connections.
 173  */
 174 void
 175 GNUNET_SERVER_suspend (struct GNUNET_SERVER_Handle *server);
 176
 177
 178 /**
 179  * Resume accepting connections from the listen socket.
 180  *
 181  * @param server server to resume accepting connections.
 182  */
 183 void
 184 GNUNET_SERVER_resume (struct GNUNET_SERVER_Handle *server);
 185
 186
 187 /**
 188  * Stop the listen socket and get ready to shutdown the server once
 189  * only clients marked using #GNUNET_SERVER_client_mark_monitor are
 190  * left.
 191  *
 192  * @param server server to stop listening on
 193  */
 194 void
 195 GNUNET_SERVER_stop_listening (struct GNUNET_SERVER_Handle *server);
 196
 197
 198 /**
 199  * Free resources held by this server.
 200  *
 201  * @param server server to destroy
 202  */
 203 void
 204 GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *server);
 205
 206
 207 /**
 208  * Add additional handlers to an existing server.
 209  *
 210  * @param server the server to add handlers to
 211  * @param handlers array of message handlers for
 212  *        incoming messages; the last entry must
 213  *        have "NULL" for the "callback"; multiple
 214  *        entries for the same type are allowed,
 215  *        they will be called in order of occurence.
 216  *        These handlers can be removed later;
 217  *        the handlers array must exist until removed
 218  *        (or server is destroyed).
 219  */
 220 void
 221 GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
 222                             const struct GNUNET_SERVER_MessageHandler *handlers);
 223
 224
 225 /**
 226  * Notify us when the server has enough space to transmit
 227  * a message of the given size to the given client.
 228  *
 229  * @param client client to transmit message to
 230  * @param size requested amount of buffer space
 231  * @param timeout after how long should we give up (and call
 232  *        notify with buf NULL and size 0)?
 233  * @param callback function to call when space is available
 234  * @param callback_cls closure for @a callback
 235  * @return non-NULL if the notify callback was queued; can be used
 236  *           to cancel the request using
 237  *           #GNUNET_SERVER_notify_transmit_ready_cancel.
 238  *         NULL if we are already going to notify someone else (busy)
 239  */
 240 struct GNUNET_SERVER_TransmitHandle *
 241 GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client,
 242                                      size_t size,
 243                                      struct GNUNET_TIME_Relative timeout,
 244                                      GNUNET_CONNECTION_TransmitReadyNotify callback,
 245                                      void *callback_cls);
 246
 247
 248 /**
 249  * Abort transmission request.
 250  *
 251  * @param th request to abort
 252  */
 253 void
 254 GNUNET_SERVER_notify_transmit_ready_cancel (struct GNUNET_SERVER_TransmitHandle *th);
 255
 256
 257 /**
 258  * Set the 'monitor' flag on this client.  Clients which have been
 259  * marked as 'monitors' won't prevent the server from shutting down
 260  * once #GNUNET_SERVER_stop_listening has been invoked.  The idea is
 261  * that for "normal" clients we likely want to allow them to process
 262  * their requests; however, monitor-clients are likely to 'never'
 263  * disconnect during shutdown and thus will not be considered when
 264  * determining if the server should continue to exist after
 265  * #GNUNET_SERVER_destroy has been called.
 266  *
 267  * @param client the client to set the 'monitor' flag on
 268  */
 269 void
 270 GNUNET_SERVER_client_mark_monitor (struct GNUNET_SERVER_Client *client);
 271
 272
 273 /**
 274  * Set the persistent flag on this client, used to setup client
 275  * connection to only be killed when the process of the service it's
 276  * connected to is actually dead.  This API is used during shutdown
 277  * signalling within ARM, and it is not expected that typical users
 278  * of the API would need this function.
 279  *
 280  * @param client the client to set the persistent flag on
 281  */
 282 void
 283 GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client);
 284
 285
 286 /**
 287  * Resume receiving from this client, we are done processing the
 288  * current request.  This function must be called from within each
 289  * #GNUNET_SERVER_MessageCallback (or its respective continuations).
 290  *
 291  * @param client client we were processing a message of
 292  * @param success #GNUNET_OK to keep the connection open and
 293  *                          continue to receive
 294  *                #GNUNET_NO to close the connection (normal behavior)
 295  *                #GNUNET_SYSERR to close the connection (signal
 296  *                          serious error)
 297  */
 298 void
 299 GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client,
 300                             int success);
 301
 302
 303 /**
 304  * Change the timeout for a particular client.  Decreasing the timeout
 305  * may not go into effect immediately (only after the previous timeout
 306  * times out or activity happens on the socket).
 307  *
 308  * @param client the client to update
 309  * @param timeout new timeout for activities on the socket
 310  */
 311 void
 312 GNUNET_SERVER_client_set_timeout (struct GNUNET_SERVER_Client *client,
 313                                   struct GNUNET_TIME_Relative timeout);
 314
 315
 316 /**
 317  * Return user context associated with the given client.
 318  * Note: you should probably use the macro (call without the underscore).
 319  *
 320  * @param client client to query
 321  * @param size number of bytes in user context struct (for verification only)
 322  * @return pointer to user context
 323  */
 324 void *
 325 GNUNET_SERVER_client_get_user_context_ (struct GNUNET_SERVER_Client *client,
 326                                         size_t size);
 327
 328
 329 /**
 330  * Set user context to be associated with the given client.
 331  * Note: you should probably use the macro (call without the underscore).
 332  *
 333  * @param client client to query
 334  * @param ptr pointer to user context
 335  * @param size number of bytes in user context struct (for verification only)
 336  */
 337 void
 338 GNUNET_SERVER_client_set_user_context_ (struct GNUNET_SERVER_Client *client,
 339                                         void *ptr,
 340                                         size_t size);
 341
 342
 343 /**
 344  * Return user context associated with the given client.
 345  *
 346  * @param client client to query
 347  * @param type expected return type (i.e. 'struct Foo')
 348  * @return pointer to user context of type 'type *'.
 349  */
 350 #define GNUNET_SERVER_client_get_user_context(client,type)              \
 351   (type *) GNUNET_SERVER_client_get_user_context_ (client, sizeof (type))
 352
 353 /**
 354  * Set user context to be associated with the given client.
 355  *
 356  * @param client client to query
 357  * @param value pointer to user context
 358  */
 359 #define GNUNET_SERVER_client_set_user_context(client,value)             \
 360   GNUNET_SERVER_client_set_user_context_ (client, value, sizeof (*value))
 361
 362
 363 /**
 364  * Disable the warning the server issues if a message is not acknowledged
 365  * in a timely fashion.  Use this call if a client is intentionally delayed
 366  * for a while.  Only applies to the current message.
 367  *
 368  * @param client client for which to disable the warning
 369  */
 370 void
 371 GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client
 372                                             *client);
 373
 374
 375 /**
 376  * Inject a message into the server, pretend it came
 377  * from the specified client.  Delivery of the message
 378  * will happen instantly (if a handler is installed;
 379  * otherwise the call does nothing).
 380  *
 381  * @param server the server receiving the message
 382  * @param sender the "pretended" sender of the message
 383  *        can be NULL!
 384  * @param message message to transmit
 385  * @return #GNUNET_OK if the message was OK and the
 386  *                   connection can stay open
 387  *         #GNUNET_SYSERR if the connection to the
 388  *         client should be shut down
 389  */
 390 int
 391 GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
 392                       struct GNUNET_SERVER_Client *sender,
 393                       const struct GNUNET_MessageHeader *message);
 394
 395
 396 /**
 397  * Add a TCP socket-based connection to the set of handles managed by
 398  * this server.  Use this function for outgoing (P2P) connections that
 399  * we initiated (and where this server should process incoming
 400  * messages).
 401  *
 402  * @param server the server to use
 403  * @param connection the connection to manage (client must
 404  *        stop using this connection from now on)
 405  * @return the client handle
 406  */
 407 struct GNUNET_SERVER_Client *
 408 GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server,
 409                               struct GNUNET_CONNECTION_Handle *connection);
 410
 411
 412 /**
 413  * Notify the server that the given client handle should
 414  * be kept (keeps the connection up if possible, increments
 415  * the internal reference counter).
 416  *
 417  * @param client the client to keep
 418  */
 419 void
 420 GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client);
 421
 422
 423 /**
 424  * Notify the server that the given client handle is no
 425  * longer required.  Decrements the reference counter.  If
 426  * that counter reaches zero an inactive connection maybe
 427  * closed.
 428  *
 429  * @param client the client to drop
 430  */
 431 void
 432 GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);
 433
 434
 435 /**
 436  * Obtain the network address of the other party.
 437  *
 438  * @param client the client to get the address for
 439  * @param addr where to store the address
 440  * @param addrlen where to store the length of @a addr
 441  * @return #GNUNET_OK on success
 442  */
 443 int
 444 GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
 445                                   void **addr, size_t *addrlen);
 446
 447
 448 /**
 449  * Functions with this signature are called whenever a client
 450  * is disconnected on the network level.
 451  *
 452  * @param cls closure
 453  * @param client identification of the client; NULL
 454  *        for the last call when the server is destroyed
 455  */
 456 typedef void
 457 (*GNUNET_SERVER_DisconnectCallback) (void *cls,
 458                                      struct GNUNET_SERVER_Client *client);
 459
 460
 461 /**
 462  * Functions with this signature are called whenever a client
 463  * is connected on the network level.
 464  *
 465  * @param cls closure
 466  * @param client identification of the client
 467  */
 468 typedef void
 469 (*GNUNET_SERVER_ConnectCallback) (void *cls,
 470                                   struct GNUNET_SERVER_Client *client);
 471
 472
 473 /**
 474  * Ask the server to notify us whenever a client disconnects.
 475  * This function is called whenever the actual network connection
 476  * is closed; the reference count may be zero or larger than zero
 477  * at this point.  If the server is destroyed before this
 478  * notification is explicitly cancelled, the 'callback' will
 479  * once be called with a 'client' argument of NULL to indicate
 480  * that the server itself is now gone (and that the callback
 481  * won't be called anymore and also can no longer be cancelled).
 482  *
 483  * @param server the server manageing the clients
 484  * @param callback function to call on disconnect
 485  * @param callback_cls closure for @a callback
 486  */
 487 void
 488 GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
 489                                  GNUNET_SERVER_DisconnectCallback callback,
 490                                  void *callback_cls);
 491
 492
 493 /**
 494  * Ask the server to notify us whenever a client connects.
 495  * This function is called whenever the actual network connection
 496  * is opened. If the server is destroyed before this
 497  * notification is explicitly cancelled, the @a callback will
 498  * once be called with a 'client' argument of NULL to indicate
 499  * that the server itself is now gone (and that the callback
 500  * won't be called anymore and also can no longer be cancelled).
 501  *
 502  * @param server the server manageing the clients
 503  * @param callback function to call on sconnect
 504  * @param callback_cls closure for @a callback
 505  */
 506 void
 507 GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server,
 508                               GNUNET_SERVER_ConnectCallback callback,
 509                               void *callback_cls);
 510
 511
 512 /**
 513  * Ask the server to stop notifying us whenever a client disconnects.
 514  * Arguments must match exactly those given to
 515  * #GNUNET_SERVER_disconnect_notify.  It is not necessary to call this
 516  * function during shutdown of the server; in fact, most applications
 517  * will never use this function.
 518  *
 519  * @param server the server manageing the clients
 520  * @param callback function to call on disconnect
 521  * @param callback_cls closure for @a callback
 522  */
 523 void
 524 GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 525                                         GNUNET_SERVER_DisconnectCallback callback,
 526                                         void *callback_cls);
 527
 528
 529 /**
 530  * Ask the server to stop notifying us whenever a client connects.
 531  * Arguments must match exactly those given to
 532  * #GNUNET_SERVER_connect_notify.  It is not necessary to call this
 533  * function during shutdown of the server; in fact, most applications
 534  * will never use this function.
 535  *
 536  * @param server the server manageing the clients
 537  * @param callback function to call on connect
 538  * @param callback_cls closure for @a callback
 539  */
 540 void
 541 GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 542                                      GNUNET_SERVER_ConnectCallback callback,
 543                                      void *callback_cls);
 544
 545
 546 /**
 547  * Ask the server to disconnect from the given client.  This is the
 548  * same as passing #GNUNET_SYSERR to #GNUNET_SERVER_receive_done,
 549  * except that it allows dropping of a client even when not handling a
 550  * message from that client.
 551  *
 552  * @param client the client to disconnect from
 553  */
 554 void
 555 GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
 556
 557
 558 /**
 559  * Disable the "CORK" feature for communication with the given client,
 560  * forcing the OS to immediately flush the buffer on transmission
 561  * instead of potentially buffering multiple messages.
 562  *
 563  * @param client handle to the client
 564  * @return #GNUNET_OK on success
 565  */
 566 int
 567 GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
 568
 569
 570 /**
 571  * The tansmit context is the key datastructure for a conveniance API
 572  * used for transmission of complex results to the client followed
 573  * ONLY by signaling receive_done with success or error
 574  */
 575 struct GNUNET_SERVER_TransmitContext;
 576
 577
 578 /**
 579  * Create a new transmission context for the given client.
 580  *
 581  * @param client client to create the context for.
 582  * @return NULL on error
 583  */
 584 struct GNUNET_SERVER_TransmitContext *
 585 GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client *client);
 586
 587
 588 /**
 589  * Append a message to the transmission context.
 590  * All messages in the context will be sent by
 591  * the #GNUNET_SERVER_transmit_context_run method.
 592  *
 593  * @param tc context to use
 594  * @param data what to append to the result message
 595  * @param length length of @a data
 596  * @param type type of the message
 597  */
 598 void
 599 GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext *tc,
 600                                             const void *data,
 601                                             size_t length, uint16_t type);
 602
 603
 604 /**
 605  * Append a message to the transmission context.
 606  * All messages in the context will be sent by
 607  * the transmit_context_run method.
 608  *
 609  * @param tc context to use
 610  * @param msg message to append
 611  */
 612 void
 613 GNUNET_SERVER_transmit_context_append_message (struct GNUNET_SERVER_TransmitContext *tc,
 614                                                const struct GNUNET_MessageHeader *msg);
 615
 616
 617 /**
 618  * Execute a transmission context.  If there is an error in the
 619  * transmission, the receive_done method will be called with an error
 620  * code (#GNUNET_SYSERR), otherwise with #GNUNET_OK.
 621  *
 622  * @param tc transmission context to use
 623  * @param timeout when to time out and abort the transmission
 624  */
 625 void
 626 GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
 627                                     struct GNUNET_TIME_Relative timeout);
 628
 629
 630 /**
 631  * Destroy a transmission context.  This function must not be called
 632  * after #GNUNET_SERVER_transmit_context_run.
 633  *
 634  * @param tc transmission context to destroy
 635  * @param success code to give to #GNUNET_SERVER_receive_done  for
 636  *        the client: #GNUNET_OK to keep the connection open and
 637  *                          continue to receive
 638  *                #GNUNET_NO to close the connection (normal behavior)
 639  *                #GNUNET_SYSERR to close the connection (signal
 640  *                          serious error)
 641  */
 642 void
 643 GNUNET_SERVER_transmit_context_destroy (struct GNUNET_SERVER_TransmitContext *tc,
 644                                         int success);
 645
 646
 647 /**
 648  * The notification context is the key datastructure for a conveniance
 649  * API used for transmission of notifications to the client until the
 650  * client disconnects or is disconnected (or the notification context
 651  * is destroyed, in which case we disconnect these clients).
 652  * Essentially, all (notification) messages are queued up until the
 653  * client is able to read them.
 654  */
 655 struct GNUNET_SERVER_NotificationContext;
 656
 657
 658 /**
 659  * Create a new notification context.
 660  *
 661  * @param server server for which this function creates the context
 662  * @param queue_length maximum number of messages to keep in
 663  *        the notification queue; optional messages are dropped
 664  *        if the queue gets longer than this number of messages
 665  * @return handle to the notification context
 666  */
 667 struct GNUNET_SERVER_NotificationContext *
 668 GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server,
 669                                            unsigned int queue_length);
 670
 671
 672 /**
 673  * Destroy the context, force disconnect for all clients.
 674  *
 675  * @param nc context to destroy.
 676  */
 677 void
 678 GNUNET_SERVER_notification_context_destroy (struct GNUNET_SERVER_NotificationContext *nc);
 679
 680
 681 /**
 682  * Add a client to the notification context.
 683  *
 684  * @param nc context to modify
 685  * @param client client to add
 686  */
 687 void
 688 GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext *nc,
 689                                         struct GNUNET_SERVER_Client *client);
 690
 691
 692 /**
 693  * Send a message to a particular client; must have
 694  * already been added to the notification context.
 695  *
 696  * @param nc context to modify
 697  * @param client client to transmit to
 698  * @param msg message to send
 699  * @param can_drop can this message be dropped due to queue length limitations
 700  */
 701 void
 702 GNUNET_SERVER_notification_context_unicast (struct GNUNET_SERVER_NotificationContext *nc,
 703                                             struct GNUNET_SERVER_Client *client,
 704                                             const struct GNUNET_MessageHeader *msg,
 705                                             int can_drop);
 706
 707
 708 /**
 709  * Send a message to all clients of this context.
 710  *
 711  * @param nc context to modify
 712  * @param msg message to send
 713  * @param can_drop can this message be dropped due to queue length limitations
 714  */
 715 void
 716 GNUNET_SERVER_notification_context_broadcast (struct GNUNET_SERVER_NotificationContext *nc,
 717                                               const struct GNUNET_MessageHeader *msg,
 718                                               int can_drop);
 719
 720
 721 /**
 722  * Return active number of subscribers in this context.
 723  *
 724  * @param nc context to query
 725  * @return number of current subscribers
 726  */
 727 unsigned int
 728 GNUNET_SERVER_notification_context_get_size (struct GNUNET_SERVER_NotificationContext *nc);
 729
 730
 731 /**
 732  * Create a message queue for a server's client.
 733  *
 734  * @param client the client
 735  * @return the message queue
 736  */
 737 struct GNUNET_MQ_Handle *
 738 GNUNET_MQ_queue_for_server_client (struct GNUNET_SERVER_Client *client);
 739
 740
 741 /**
 742  * Handle to a message stream tokenizer.
 743  */
 744 struct GNUNET_SERVER_MessageStreamTokenizer;
 745
 746
 747 /**
 748  * Functions with this signature are called whenever a
 749  * complete message is received by the tokenizer.
 750  *
 751  * Do not call #GNUNET_SERVER_mst_destroy from within
 752  * the scope of this callback.
 753  *
 754  * @param cls closure
 755  * @param client identification of the client
 756  * @param message the actual message
 757  * @return #GNUNET_OK on success, #GNUNET_SYSERR to stop further processing
 758  */
 759 typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
 760                                                        const struct GNUNET_MessageHeader *message);
 761
 762
 763 /**
 764  * Create a message stream tokenizer.
 765  *
 766  * @param cb function to call on completed messages
 767  * @param cb_cls closure for @a cb
 768  * @return handle to tokenizer
 769  */
 770 struct GNUNET_SERVER_MessageStreamTokenizer *
 771 GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb,
 772                           void *cb_cls);
 773
 774
 775 /**
 776  * Add incoming data to the receive buffer and call the
 777  * callback for all complete messages.
 778  *
 779  * @param mst tokenizer to use
 780  * @param client_identity ID of client for which this is a buffer,
 781  *        can be NULL (will be passed back to 'cb')
 782  * @param buf input data to add
 783  * @param size number of bytes in @a buf
 784  * @param purge should any excess bytes in the buffer be discarded
 785  *       (i.e. for packet-based services like UDP)
 786  * @param one_shot only call callback once, keep rest of message in buffer
 787  * @return #GNUNET_OK if we are done processing (need more data)
 788  *         #GNUNET_NO if one_shot was set and we have another message ready
 789  *         #GNUNET_SYSERR if the data stream is corrupt
 790  */
 791 int
 792 GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
 793                            void *client_identity,
 794                            const char *buf, size_t size,
 795                            int purge, int one_shot);
 796
 797
 798 /**
 799  * Destroys a tokenizer.
 800  *
 801  * @param mst tokenizer to destroy
 802  */
 803 void
 804 GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
 805
 806
 807 /**
 808  * Signature of a function to create a custom tokenizer.
 809  *
 810  * @param cls closure from #GNUNET_SERVER_set_callbacks
 811  * @param client handle to client the tokenzier will be used for
 812  * @return handle to custom tokenizer ('mst')
 813  */
 814 typedef void*
 815 (*GNUNET_SERVER_MstCreateCallback) (void *cls,
 816                                     struct GNUNET_SERVER_Client *client);
 817
 818
 819 /**
 820  * Signature of a function to destroy a custom tokenizer.
 821  *
 822  * @param cls closure from #GNUNET_SERVER_set_callbacks
 823  * @param mst custom tokenizer handle
 824  */
 825 typedef void
 826 (*GNUNET_SERVER_MstDestroyCallback) (void *cls,
 827                                      void *mst);
 828
 829
 830 /**
 831  * Signature of a function to receive data for a custom tokenizer.
 832  *
 833  * @param cls closure from #GNUNET_SERVER_set_callbacks
 834  * @param mst custom tokenizer handle
 835  * @param client_identity ID of client for which this is a buffer,
 836  *        can be NULL (will be passed back to 'cb')
 837  * @param buf input data to add
 838  * @param size number of bytes in @a buf
 839  * @param purge should any excess bytes in the buffer be discarded
 840  *       (i.e. for packet-based services like UDP)
 841  * @param one_shot only call callback once, keep rest of message in buffer
 842  * @return #GNUNET_OK if we are done processing (need more data)
 843  *         #GNUNET_NO if one_shot was set and we have another message ready
 844  *         #GNUNET_SYSERR if the data stream is corrupt
 845  */
 846 typedef int
 847 (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
 848                                      struct GNUNET_SERVER_Client *client,
 849                                      const char *buf,
 850                                      size_t size,
 851                                      int purge,
 852                                      int one_shot);
 853
 854
 855 /**
 856  * Change functions used by the server to tokenize the message stream.
 857  * (very rarely used).
 858  *
 859  * @param server server to modify
 860  * @param create new tokenizer initialization function
 861  * @param destroy new tokenizer destruction function
 862  * @param receive new tokenizer receive function
 863  * @param cls closure for @a create, @a receive and @a destroy
 864  */
 865 void
 866 GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
 867                              GNUNET_SERVER_MstCreateCallback create,
 868                              GNUNET_SERVER_MstDestroyCallback destroy,
 869                              GNUNET_SERVER_MstReceiveCallback receive,
 870                              void *cls);
 871
 872
 873 #if 0                           /* keep Emacsens' auto-indent happy */
 874 {
 875 #endif
 876 #ifdef __cplusplus
 877 }
 878 #endif
 879
 880 /* ifndef GNUNET_SERVER_LIB_H */
 881 #endif
 882
 883 /** @} */  /* end of group server */
 884
 885 /* end of gnunet_server_lib.h */