src/include/gnunet_server_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010 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 2, 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 ptr 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.
 480  *
 481  * @param server the server manageing the clients
 482  * @param callback function to call on sconnect
 483  * @param callback_cls closure for callback
 484  */
 485 void
 486 GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server,
 487     GNUNET_SERVER_ConnectCallback callback, void *callback_cls);
 488
 489
 490 /**
 491  * Ask the server to stop notifying us whenever a client disconnects.
 492  *
 493  * @param server the server manageing the clients
 494  * @param callback function to call on disconnect
 495  * @param callback_cls closure for callback
 496  */
 497 void
 498 GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 499                                         GNUNET_SERVER_DisconnectCallback
 500                                         callback, void *callback_cls);
 501
 502
 503 /**
 504  * Ask the server to stop notifying us whenever a client connects.
 505  *
 506  * @param server the server manageing the clients
 507  * @param callback function to call on connect
 508  * @param callback_cls closure for callback
 509  */
 510 void
 511 GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 512     GNUNET_SERVER_ConnectCallback callback, void *callback_cls);
 513
 514
 515 /**
 516  * Ask the server to disconnect from the given client.
 517  * This is the same as returning GNUNET_SYSERR from a message
 518  * handler, except that it allows dropping of a client even
 519  * when not handling a message from that client.
 520  *
 521  * @param client the client to disconnect from
 522  */
 523 void
 524 GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
 525
 526
 527 /**
 528  * Disable the "CORK" feature for communication with the given client,
 529  * forcing the OS to immediately flush the buffer on transmission
 530  * instead of potentially buffering multiple messages.
 531  *
 532  * @param client handle to the client
 533  * @return GNUNET_OK on success
 534  */
 535 int
 536 GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
 537
 538
 539 /**
 540  * The tansmit context is the key datastructure for a conveniance API
 541  * used for transmission of complex results to the client followed
 542  * ONLY by signaling receive_done with success or error
 543  */
 544 struct GNUNET_SERVER_TransmitContext;
 545
 546
 547 /**
 548  * Create a new transmission context for the
 549  * given client.
 550  *
 551  * @param client client to create the context for.
 552  * @return NULL on error
 553  */
 554 struct GNUNET_SERVER_TransmitContext *
 555 GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client *client);
 556
 557
 558 /**
 559  * Append a message to the transmission context.
 560  * All messages in the context will be sent by
 561  * the transmit_context_run method.
 562  *
 563  * @param tc context to use
 564  * @param data what to append to the result message
 565  * @param length length of data
 566  * @param type type of the message
 567  */
 568 void
 569 GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext
 570                                             *tc, const void *data,
 571                                             size_t length, uint16_t type);
 572
 573
 574 /**
 575  * Append a message to the transmission context.
 576  * All messages in the context will be sent by
 577  * the transmit_context_run method.
 578  *
 579  * @param tc context to use
 580  * @param msg message to append
 581  */
 582 void
 583 GNUNET_SERVER_transmit_context_append_message (struct
 584                                                GNUNET_SERVER_TransmitContext
 585                                                *tc,
 586                                                const struct GNUNET_MessageHeader
 587                                                *msg);
 588
 589
 590 /**
 591  * Execute a transmission context.  If there is an error in the
 592  * transmission, the receive_done method will be called with an error
 593  * code (GNUNET_SYSERR), otherwise with GNUNET_OK.
 594  *
 595  * @param tc transmission context to use
 596  * @param timeout when to time out and abort the transmission
 597  */
 598 void
 599 GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
 600                                     struct GNUNET_TIME_Relative timeout);
 601
 602
 603 /**
 604  * Destroy a transmission context.  This function must not be called
 605  * after 'GNUNET_SERVER_transmit_context_run'.
 606  *
 607  * @param tc transmission context to destroy
 608  * @param success code to give to 'GNUNET_SERVER_receive_done' for
 609  *        the client:  GNUNET_OK to keep the connection open and
 610  *                          continue to receive
 611  *                GNUNET_NO to close the connection (normal behavior)
 612  *                GNUNET_SYSERR to close the connection (signal
 613  *                          serious error)
 614  */
 615 void
 616 GNUNET_SERVER_transmit_context_destroy (struct GNUNET_SERVER_TransmitContext
 617                                         *tc, int success);
 618
 619
 620 /**
 621  * The notification context is the key datastructure for a conveniance
 622  * API used for transmission of notifications to the client until the
 623  * client disconnects or is disconnected (or the notification context
 624  * is destroyed, in which case we disconnect these clients).
 625  * Essentially, all (notification) messages are queued up until the
 626  * client is able to read them.
 627  */
 628 struct GNUNET_SERVER_NotificationContext;
 629
 630
 631 /**
 632  * Create a new notification context.
 633  *
 634  * @param server server for which this function creates the context
 635  * @param queue_length maximum number of messages to keep in
 636  *        the notification queue; optional messages are dropped
 637  *        if the queue gets longer than this number of messages
 638  * @return handle to the notification context
 639  */
 640 struct GNUNET_SERVER_NotificationContext *
 641 GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server,
 642                                            unsigned int queue_length);
 643
 644
 645 /**
 646  * Destroy the context, force disconnect for all clients.
 647  *
 648  * @param nc context to destroy.
 649  */
 650 void
 651 GNUNET_SERVER_notification_context_destroy (struct
 652                                             GNUNET_SERVER_NotificationContext
 653                                             *nc);
 654
 655
 656 /**
 657  * Add a client to the notification context.
 658  *
 659  * @param nc context to modify
 660  * @param client client to add
 661  */
 662 void
 663 GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext
 664                                         *nc,
 665                                         struct GNUNET_SERVER_Client *client);
 666
 667
 668 /**
 669  * Send a message to a particular client; must have
 670  * already been added to the notification context.
 671  *
 672  * @param nc context to modify
 673  * @param client client to transmit to
 674  * @param msg message to send
 675  * @param can_drop can this message be dropped due to queue length limitations
 676  */
 677 void
 678 GNUNET_SERVER_notification_context_unicast (struct
 679                                             GNUNET_SERVER_NotificationContext
 680                                             *nc,
 681                                             struct GNUNET_SERVER_Client *client,
 682                                             const struct GNUNET_MessageHeader
 683                                             *msg, int can_drop);
 684
 685
 686 /**
 687  * Send a message to all clients of this context.
 688  *
 689  * @param nc context to modify
 690  * @param msg message to send
 691  * @param can_drop can this message be dropped due to queue length limitations
 692  */
 693 void
 694 GNUNET_SERVER_notification_context_broadcast (struct
 695                                               GNUNET_SERVER_NotificationContext
 696                                               *nc,
 697                                               const struct GNUNET_MessageHeader
 698                                               *msg, int can_drop);
 699
 700
 701
 702 /**
 703  * Handle to a message stream tokenizer.
 704  */
 705 struct GNUNET_SERVER_MessageStreamTokenizer;
 706
 707 /**
 708  * Functions with this signature are called whenever a
 709  * complete message is received by the tokenizer.
 710  *
 711  * Do not call GNUNET_SERVER_mst_destroy in callback
 712  *
 713  * @param cls closure
 714  * @param client identification of the client
 715  * @param message the actual message
 716  *
 717  * @return GNUNET_OK on success, GNUNET_SYSERR to stop further processing
 718  */
 719 typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
 720                                                         const struct
 721                                                         GNUNET_MessageHeader *
 722                                                         message);
 723
 724
 725 /**
 726  * Create a message stream tokenizer.
 727  *
 728  * @param cb function to call on completed messages
 729  * @param cb_cls closure for cb
 730  * @return handle to tokenizer
 731  */
 732 struct GNUNET_SERVER_MessageStreamTokenizer *
 733 GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb,
 734                           void *cb_cls);
 735
 736
 737 /**
 738  * Add incoming data to the receive buffer and call the
 739  * callback for all complete messages.
 740  *
 741  * @param mst tokenizer to use
 742  * @param client_identity ID of client for which this is a buffer,
 743  *        can be NULL (will be passed back to 'cb')
 744  * @param buf input data to add
 745  * @param size number of bytes in buf
 746  * @param purge should any excess bytes in the buffer be discarded
 747  *       (i.e. for packet-based services like UDP)
 748  * @param one_shot only call callback once, keep rest of message in buffer
 749  * @return GNUNET_OK if we are done processing (need more data)
 750  *         GNUNET_NO if one_shot was set and we have another message ready
 751  *         GNUNET_SYSERR if the data stream is corrupt
 752  */
 753 int
 754 GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
 755                            void *client_identity, const char *buf, size_t size,
 756                            int purge, int one_shot);
 757
 758
 759 /**
 760  * Destroys a tokenizer.
 761  *
 762  * @param mst tokenizer to destroy
 763  */
 764 void
 765 GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
 766
 767
 768 /**
 769  * Signature of a function to create a custom tokenizer.
 770  *
 771  * @param cls closure from 'GNUNET_SERVER_set_callbacks'
 772  * @param client handle to client the tokenzier will be used for
 773  * @return handle to custom tokenizer ('mst')
 774  */
 775 typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls,
 776                                                   struct GNUNET_SERVER_Client *client);
 777
 778 /**
 779  * Signature of a function to destroy a custom tokenizer.
 780  *
 781  * @param cls closure from 'GNUNET_SERVER_set_callbacks'
 782  * @param mst custom tokenizer handle
 783  */
 784 typedef void (*GNUNET_SERVER_MstDestroyCallback) (void *cls, void *mst);
 785
 786 /**
 787  * Signature of a function to destroy a custom tokenizer.
 788  *
 789  * @param cls closure from 'GNUNET_SERVER_set_callbacks'
 790  * @param mst custom tokenizer handle
 791  * @param client_identity ID of client for which this is a buffer,
 792  *        can be NULL (will be passed back to 'cb')
 793  * @param buf input data to add
 794  * @param size number of bytes in buf
 795  * @param purge should any excess bytes in the buffer be discarded
 796  *       (i.e. for packet-based services like UDP)
 797  * @param one_shot only call callback once, keep rest of message in buffer
 798  * @return GNUNET_OK if we are done processing (need more data)
 799  *         GNUNET_NO if one_shot was set and we have another message ready
 800  *         GNUNET_SYSERR if the data stream is corrupt
 801  */
 802 typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
 803                                                  struct GNUNET_SERVER_Client *client,
 804                                                  const char *buf, size_t size,
 805                                                  int purge, int one_shot);
 806
 807
 808 /**
 809  * Change functions used by the server to tokenize the message stream.
 810  * (very rarely used).
 811  *
 812  * @param server server to modify
 813  * @param create new tokenizer initialization function
 814  * @param destroy new tokenizer destruction function
 815  * @param receive new tokenizer receive function
 816  * @param cls closure for 'create', 'receive', 'destroy'
 817  */
 818 void
 819 GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
 820                              GNUNET_SERVER_MstCreateCallback create,
 821                              GNUNET_SERVER_MstDestroyCallback destroy,
 822                              GNUNET_SERVER_MstReceiveCallback receive,
 823                              void *cls);
 824
 825
 826 #if 0                           /* keep Emacsens' auto-indent happy */
 827 {
 828 #endif
 829 #ifdef __cplusplus
 830 }
 831 #endif
 832
 833
 834 /* ifndef GNUNET_SERVER_LIB_H */
 835 #endif
 836 /* end of gnunet_server_lib.h */