src/include/gnunet_server_lib.h

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