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  * Disable the warning the server issues if a message is not acknowledged
 302  * in a timely fashion.  Use this call if a client is intentionally delayed
 303  * for a while.  Only applies to the current message.
 304  *
 305  * @param client client for which to disable the warning
 306  */
 307 void
 308 GNUNET_SERVER_disable_receive_done_warning (struct GNUNET_SERVER_Client
 309                                             *client);
 310
 311
 312 /**
 313  * Inject a message into the server, pretend it came
 314  * from the specified client.  Delivery of the message
 315  * will happen instantly (if a handler is installed;
 316  * otherwise the call does nothing).
 317  *
 318  * @param server the server receiving the message
 319  * @param sender the "pretended" sender of the message
 320  *        can be NULL!
 321  * @param message message to transmit
 322  * @return GNUNET_OK if the message was OK and the
 323  *                   connection can stay open
 324  *         GNUNET_SYSERR if the connection to the
 325  *         client should be shut down
 326  */
 327 int
 328 GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
 329                       struct GNUNET_SERVER_Client *sender,
 330                       const struct GNUNET_MessageHeader *message);
 331
 332
 333 /**
 334  * Add a TCP socket-based connection to the set of handles managed by
 335  * this server.  Use this function for outgoing (P2P) connections that
 336  * we initiated (and where this server should process incoming
 337  * messages).
 338  *
 339  * @param server the server to use
 340  * @param connection the connection to manage (client must
 341  *        stop using this connection from now on)
 342  * @return the client handle (client should call
 343  *         "client_drop" on the return value eventually)
 344  */
 345 struct GNUNET_SERVER_Client *
 346 GNUNET_SERVER_connect_socket (struct GNUNET_SERVER_Handle *server,
 347                               struct GNUNET_CONNECTION_Handle *connection);
 348
 349
 350 /**
 351  * Notify the server that the given client handle should
 352  * be kept (keeps the connection up if possible, increments
 353  * the internal reference counter).
 354  *
 355  * @param client the client to keep
 356  */
 357 void
 358 GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client);
 359
 360
 361 /**
 362  * Notify the server that the given client handle is no
 363  * longer required.  Decrements the reference counter.  If
 364  * that counter reaches zero an inactive connection maybe
 365  * closed.
 366  *
 367  * @param client the client to drop
 368  */
 369 void
 370 GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);
 371
 372
 373 /**
 374  * Obtain the network address of the other party.
 375  *
 376  * @param client the client to get the address for
 377  * @param addr where to store the address
 378  * @param addrlen where to store the length of the address
 379  * @return GNUNET_OK on success
 380  */
 381 int
 382 GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
 383                                   void **addr, size_t * addrlen);
 384
 385
 386 /**
 387  * Functions with this signature are called whenever a client
 388  * is disconnected on the network level.
 389  *
 390  * @param cls closure
 391  * @param client identification of the client; NULL
 392  *        for the last call when the server is destroyed
 393  */
 394 typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
 395                                                   struct GNUNET_SERVER_Client *
 396                                                   client);
 397
 398 /**
 399  * Functions with this signature are called whenever a client
 400  * is connected on the network level.
 401  *
 402  * @param cls closure
 403  * @param client identification of the client
 404  */
 405 typedef void (*GNUNET_SERVER_ConnectCallback) (void *cls,
 406     struct GNUNET_SERVER_Client *client);
 407
 408
 409
 410 /**
 411  * Ask the server to notify us whenever a client disconnects.
 412  * This function is called whenever the actual network connection
 413  * is closed; the reference count may be zero or larger than zero
 414  * at this point.  If the server is destroyed before this
 415  * notification is explicitly cancelled, the 'callback' will
 416  * once be called with a 'client' argument of NULL to indicate
 417  * that the server itself is now gone (and that the callback
 418  * won't be called anymore and also can no longer be cancelled).
 419  *
 420  * @param server the server manageing the clients
 421  * @param callback function to call on disconnect
 422  * @param callback_cls closure for callback
 423  */
 424 void
 425 GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
 426                                  GNUNET_SERVER_DisconnectCallback callback,
 427                                  void *callback_cls);
 428
 429
 430 /**
 431  * Ask the server to notify us whenever a client connects.
 432  * This function is called whenever the actual network connection
 433  * is opened.
 434  *
 435  * @param server the server manageing the clients
 436  * @param callback function to call on sconnect
 437  * @param callback_cls closure for callback
 438  */
 439 void
 440 GNUNET_SERVER_connect_notify (struct GNUNET_SERVER_Handle *server,
 441     GNUNET_SERVER_ConnectCallback callback, void *callback_cls);
 442
 443
 444 /**
 445  * Ask the server to stop notifying us whenever a client disconnects.
 446  *
 447  * @param server the server manageing the clients
 448  * @param callback function to call on disconnect
 449  * @param callback_cls closure for callback
 450  */
 451 void
 452 GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 453                                         GNUNET_SERVER_DisconnectCallback
 454                                         callback, void *callback_cls);
 455
 456
 457 /**
 458  * Ask the server to stop notifying us whenever a client connects.
 459  *
 460  * @param server the server manageing the clients
 461  * @param callback function to call on connect
 462  * @param callback_cls closure for callback
 463  */
 464 void
 465 GNUNET_SERVER_connect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 466     GNUNET_SERVER_ConnectCallback callback, void *callback_cls);
 467
 468
 469 /**
 470  * Ask the server to disconnect from the given client.
 471  * This is the same as returning GNUNET_SYSERR from a message
 472  * handler, except that it allows dropping of a client even
 473  * when not handling a message from that client.
 474  *
 475  * @param client the client to disconnect from
 476  */
 477 void
 478 GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
 479
 480
 481 /**
 482  * Disable the "CORK" feature for communication with the given client,
 483  * forcing the OS to immediately flush the buffer on transmission
 484  * instead of potentially buffering multiple messages.
 485  *
 486  * @param client handle to the client
 487  * @return GNUNET_OK on success
 488  */
 489 int
 490 GNUNET_SERVER_client_disable_corking (struct GNUNET_SERVER_Client *client);
 491
 492
 493 /**
 494  * The tansmit context is the key datastructure for a conveniance API
 495  * used for transmission of complex results to the client followed
 496  * ONLY by signaling receive_done with success or error
 497  */
 498 struct GNUNET_SERVER_TransmitContext;
 499
 500
 501 /**
 502  * Create a new transmission context for the
 503  * given client.
 504  *
 505  * @param client client to create the context for.
 506  * @return NULL on error
 507  */
 508 struct GNUNET_SERVER_TransmitContext *
 509 GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client *client);
 510
 511
 512 /**
 513  * Append a message to the transmission context.
 514  * All messages in the context will be sent by
 515  * the transmit_context_run method.
 516  *
 517  * @param tc context to use
 518  * @param data what to append to the result message
 519  * @param length length of data
 520  * @param type type of the message
 521  */
 522 void
 523 GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext
 524                                             *tc, const void *data,
 525                                             size_t length, uint16_t type);
 526
 527
 528 /**
 529  * Append a message to the transmission context.
 530  * All messages in the context will be sent by
 531  * the transmit_context_run method.
 532  *
 533  * @param tc context to use
 534  * @param msg message to append
 535  */
 536 void
 537 GNUNET_SERVER_transmit_context_append_message (struct
 538                                                GNUNET_SERVER_TransmitContext
 539                                                *tc,
 540                                                const struct GNUNET_MessageHeader
 541                                                *msg);
 542
 543
 544 /**
 545  * Execute a transmission context.  If there is an error in the
 546  * transmission, the receive_done method will be called with an error
 547  * code (GNUNET_SYSERR), otherwise with GNUNET_OK.
 548  *
 549  * @param tc transmission context to use
 550  * @param timeout when to time out and abort the transmission
 551  */
 552 void
 553 GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
 554                                     struct GNUNET_TIME_Relative timeout);
 555
 556
 557 /**
 558  * Destroy a transmission context.  This function must not be called
 559  * after 'GNUNET_SERVER_transmit_context_run'.
 560  *
 561  * @param tc transmission context to destroy
 562  * @param success code to give to 'GNUNET_SERVER_receive_done' for
 563  *        the client:  GNUNET_OK to keep the connection open and
 564  *                          continue to receive
 565  *                GNUNET_NO to close the connection (normal behavior)
 566  *                GNUNET_SYSERR to close the connection (signal
 567  *                          serious error)
 568  */
 569 void
 570 GNUNET_SERVER_transmit_context_destroy (struct GNUNET_SERVER_TransmitContext
 571                                         *tc, int success);
 572
 573
 574 /**
 575  * The notification context is the key datastructure for a conveniance
 576  * API used for transmission of notifications to the client until the
 577  * client disconnects or is disconnected (or the notification context
 578  * is destroyed, in which case we disconnect these clients).
 579  * Essentially, all (notification) messages are queued up until the
 580  * client is able to read them.
 581  */
 582 struct GNUNET_SERVER_NotificationContext;
 583
 584
 585 /**
 586  * Create a new notification context.
 587  *
 588  * @param server server for which this function creates the context
 589  * @param queue_length maximum number of messages to keep in
 590  *        the notification queue; optional messages are dropped
 591  *        if the queue gets longer than this number of messages
 592  * @return handle to the notification context
 593  */
 594 struct GNUNET_SERVER_NotificationContext *
 595 GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server,
 596                                            unsigned int queue_length);
 597
 598
 599 /**
 600  * Destroy the context, force disconnect for all clients.
 601  *
 602  * @param nc context to destroy.
 603  */
 604 void
 605 GNUNET_SERVER_notification_context_destroy (struct
 606                                             GNUNET_SERVER_NotificationContext
 607                                             *nc);
 608
 609
 610 /**
 611  * Add a client to the notification context.
 612  *
 613  * @param nc context to modify
 614  * @param client client to add
 615  */
 616 void
 617 GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext
 618                                         *nc,
 619                                         struct GNUNET_SERVER_Client *client);
 620
 621
 622 /**
 623  * Send a message to a particular client; must have
 624  * already been added to the notification context.
 625  *
 626  * @param nc context to modify
 627  * @param client client to transmit to
 628  * @param msg message to send
 629  * @param can_drop can this message be dropped due to queue length limitations
 630  */
 631 void
 632 GNUNET_SERVER_notification_context_unicast (struct
 633                                             GNUNET_SERVER_NotificationContext
 634                                             *nc,
 635                                             struct GNUNET_SERVER_Client *client,
 636                                             const struct GNUNET_MessageHeader
 637                                             *msg, int can_drop);
 638
 639
 640 /**
 641  * Send a message to all clients of this context.
 642  *
 643  * @param nc context to modify
 644  * @param msg message to send
 645  * @param can_drop can this message be dropped due to queue length limitations
 646  */
 647 void
 648 GNUNET_SERVER_notification_context_broadcast (struct
 649                                               GNUNET_SERVER_NotificationContext
 650                                               *nc,
 651                                               const struct GNUNET_MessageHeader
 652                                               *msg, int can_drop);
 653
 654
 655
 656 /**
 657  * Handle to a message stream tokenizer.
 658  */
 659 struct GNUNET_SERVER_MessageStreamTokenizer;
 660
 661 /**
 662  * Functions with this signature are called whenever a
 663  * complete message is received by the tokenizer.
 664  *
 665  * Do not call GNUNET_SERVER_mst_destroy in callback
 666  *
 667  * @param cls closure
 668  * @param client identification of the client
 669  * @param message the actual message
 670  *
 671  * @return GNUNET_OK on success, GNUNET_SYSERR to stop further processing
 672  */
 673 typedef int (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls, void *client,
 674                                                         const struct
 675                                                         GNUNET_MessageHeader *
 676                                                         message);
 677
 678
 679 /**
 680  * Create a message stream tokenizer.
 681  *
 682  * @param cb function to call on completed messages
 683  * @param cb_cls closure for cb
 684  * @return handle to tokenizer
 685  */
 686 struct GNUNET_SERVER_MessageStreamTokenizer *
 687 GNUNET_SERVER_mst_create (GNUNET_SERVER_MessageTokenizerCallback cb,
 688                           void *cb_cls);
 689
 690
 691 /**
 692  * Add incoming data to the receive buffer and call the
 693  * callback for all complete messages.
 694  *
 695  * @param mst tokenizer to use
 696  * @param client_identity ID of client for which this is a buffer,
 697  *        can be NULL (will be passed back to 'cb')
 698  * @param buf input data to add
 699  * @param size number of bytes in buf
 700  * @param purge should any excess bytes in the buffer be discarded
 701  *       (i.e. for packet-based services like UDP)
 702  * @param one_shot only call callback once, keep rest of message in buffer
 703  * @return GNUNET_OK if we are done processing (need more data)
 704  *         GNUNET_NO if one_shot was set and we have another message ready
 705  *         GNUNET_SYSERR if the data stream is corrupt
 706  */
 707 int
 708 GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
 709                            void *client_identity, const char *buf, size_t size,
 710                            int purge, int one_shot);
 711
 712
 713 /**
 714  * Destroys a tokenizer.
 715  *
 716  * @param mst tokenizer to destroy
 717  */
 718 void
 719 GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
 720
 721
 722 /**
 723  * Signature of a function to create a custom tokenizer.
 724  *
 725  * @param cls closure from 'GNUNET_SERVER_set_callbacks'
 726  * @param client handle to client the tokenzier will be used for
 727  * @return handle to custom tokenizer ('mst')
 728  */
 729 typedef void* (*GNUNET_SERVER_MstCreateCallback) (void *cls,
 730                                                   struct GNUNET_SERVER_Client *client);
 731
 732 /**
 733  * Signature of a function to destroy a custom tokenizer.
 734  *
 735  * @param cls closure from 'GNUNET_SERVER_set_callbacks'
 736  * @param mst custom tokenizer handle
 737  */
 738 typedef void (*GNUNET_SERVER_MstDestroyCallback) (void *cls, void *mst);
 739
 740 /**
 741  * Signature of a function to destroy a custom tokenizer.
 742  *
 743  * @param cls closure from 'GNUNET_SERVER_set_callbacks'
 744  * @param mst custom tokenizer handle
 745  * @param client_identity ID of client for which this is a buffer,
 746  *        can be NULL (will be passed back to 'cb')
 747  * @param buf input data to add
 748  * @param size number of bytes in buf
 749  * @param purge should any excess bytes in the buffer be discarded
 750  *       (i.e. for packet-based services like UDP)
 751  * @param one_shot only call callback once, keep rest of message in buffer
 752  * @return GNUNET_OK if we are done processing (need more data)
 753  *         GNUNET_NO if one_shot was set and we have another message ready
 754  *         GNUNET_SYSERR if the data stream is corrupt
 755  */
 756 typedef int (*GNUNET_SERVER_MstReceiveCallback) (void *cls, void *mst,
 757                                                  struct GNUNET_SERVER_Client *client,
 758                                                  const char *buf, size_t size,
 759                                                  int purge, int one_shot);
 760
 761
 762 /**
 763  * Change functions used by the server to tokenize the message stream.
 764  * (very rarely used).
 765  *
 766  * @param server server to modify
 767  * @param create new tokenizer initialization function
 768  * @param destroy new tokenizer destruction function
 769  * @param receive new tokenizer receive function
 770  * @param cls closure for 'create', 'receive', 'destroy'
 771  */
 772 void
 773 GNUNET_SERVER_set_callbacks (struct GNUNET_SERVER_Handle *server,
 774                              GNUNET_SERVER_MstCreateCallback create,
 775                              GNUNET_SERVER_MstDestroyCallback destroy,
 776                              GNUNET_SERVER_MstReceiveCallback receive,
 777                              void *cls);
 778
 779
 780 #if 0                           /* keep Emacsens' auto-indent happy */
 781 {
 782 #endif
 783 #ifdef __cplusplus
 784 }
 785 #endif
 786
 787
 788 /* ifndef GNUNET_SERVER_LIB_H */
 789 #endif
 790 /* end of gnunet_server_lib.h */