src/include/gnunet_server_lib.h

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