src/include/gnunet_server_lib.h

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