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 #include "gnunet_scheduler_lib.h"
  42
  43
  44 /**
  45  * Largest supported message.
  46  */
  47 #define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536
  48
  49 /**
  50  * Largest supported message.
  51  */
  52 #define GNUNET_SERVER_MIN_BUFFER_SIZE sizeof (struct GNUNET_MessageHeader)
  53
  54 /**
  55  * @brief handle for a server
  56  */
  57 struct GNUNET_SERVER_Handle;
  58
  59
  60 /**
  61  * @brief opaque handle for a client of the server
  62  */
  63 struct GNUNET_SERVER_Client;
  64
  65
  66 /**
  67  * Functions with this signature are called whenever a message is
  68  * received.
  69  *
  70  * @param cls closure
  71  * @param client identification of the client
  72  * @param message the actual message
  73  */
  74 typedef void (*GNUNET_SERVER_MessageCallback) (void *cls,
  75                                                struct GNUNET_SERVER_Client *
  76                                                client,
  77                                                const struct
  78                                                GNUNET_MessageHeader *
  79                                                message);
  80
  81
  82
  83 /**
  84  * Message handler.  Each struct specifies how to handle on particular
  85  * type of message received.
  86  */
  87 struct GNUNET_SERVER_MessageHandler
  88 {
  89   /**
  90    * Function to call for messages of "type".
  91    */
  92   GNUNET_SERVER_MessageCallback callback;
  93
  94   /**
  95    * Closure argument for "callback".
  96    */
  97   void *callback_cls;
  98
  99   /**
 100    * Type of the message this handler covers.
 101    */
 102   uint16_t type;
 103
 104   /**
 105    * Expected size of messages of this type.  Use 0 for
 106    * variable-size.  If non-zero, messages of the given
 107    * type will be discarded (and the connection closed)
 108    * if they do not have the right size.
 109    */
 110   uint16_t expected_size;
 111
 112 };
 113
 114
 115 /**
 116  * Create a new server.
 117  *
 118  * @param sched scheduler to use
 119  * @param access function for access control
 120  * @param access_cls closure for access
 121  * @param lsocks NULL-terminated array of listen sockets
 122  * @param maxbuf maximum write buffer size for accepted 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 (struct GNUNET_SCHEDULER_Handle *sched,
 131                                    GNUNET_CONNECTION_AccessCheck access, void *access_cls,
 132                                    struct GNUNET_NETWORK_Handle **lsocks,
 133                                    size_t maxbuf,
 134                                    struct GNUNET_TIME_Relative
 135                                    idle_timeout,
 136                                    int require_found);
 137
 138 /**
 139  * Create a new server.
 140  *
 141  * @param sched scheduler to use
 142  * @param access function for access control
 143  * @param access_cls closure for access
 144  * @param serverAddr address toes listen on (including port), NULL terminated array
 145  * @param socklen lengths of respective serverAddr
 146  * @param maxbuf maximum write buffer size for accepted sockets
 147  * @param idle_timeout after how long should we timeout idle connections?
 148  * @param require_found if YES, connections sending messages of unknown type
 149  *        will be closed
 150  * @return handle for the new server, NULL on error
 151  *         (typically, "port" already in use)
 152  */
 153 struct GNUNET_SERVER_Handle *GNUNET_SERVER_create (struct
 154                                                    GNUNET_SCHEDULER_Handle
 155                                                    *sched,
 156                                                    GNUNET_CONNECTION_AccessCheck
 157                                                    access, void *access_cls,
 158                                                    struct sockaddr *const*serverAddr,
 159                                                    const socklen_t *socklen,
 160                                                    size_t maxbuf,
 161                                                    struct GNUNET_TIME_Relative
 162                                                    idle_timeout,
 163                                                    int require_found);
 164
 165
 166 /**
 167  * Free resources held by this server.
 168  *
 169  * @param s server to destroy
 170  */
 171 void GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s);
 172
 173
 174 /**
 175  * Add additional handlers to an existing server.
 176  *
 177  * @param server the server to add handlers to
 178  * @param handlers array of message handlers for
 179  *        incoming messages; the last entry must
 180  *        have "NULL" for the "callback"; multiple
 181  *        entries for the same type are allowed,
 182  *        they will be called in order of occurence.
 183  *        These handlers can be removed later;
 184  *        the handlers array must exist until removed
 185  *        (or server is destroyed).
 186  */
 187 void
 188 GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
 189                             const struct GNUNET_SERVER_MessageHandler
 190                             *handlers);
 191
 192
 193 /**
 194  * Notify us when the server has enough space to transmit
 195  * a message of the given size to the given client.
 196  *
 197  * @param client client to transmit message to
 198  * @param size requested amount of buffer space
 199  * @param timeout after how long should we give up (and call
 200  *        notify with buf NULL and size 0)?
 201  * @param callback function to call when space is available
 202  * @param callback_cls closure for callback
 203  * @return non-NULL if the notify callback was queued; can be used
 204  *           to cancel the request using
 205  *           GNUNET_CONNECTION_notify_transmit_ready_cancel.
 206  *         NULL if we are already going to notify someone else (busy)
 207  */
 208 struct GNUNET_CONNECTION_TransmitHandle
 209   *GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client,
 210                                         size_t size,
 211                                         struct GNUNET_TIME_Relative timeout,
 212                                         GNUNET_CONNECTION_TransmitReadyNotify
 213                                         callback, void *callback_cls);
 214
 215
 216 /**
 217  * Set the persistent flag on this client, used to setup client connection
 218  * to only be killed when the service it's connected to is actually dead.
 219  *
 220  * @param client the client to set the persistent flag on
 221  */
 222 void
 223 GNUNET_SERVER_client_persist_ (struct GNUNET_SERVER_Client *client);
 224
 225 /**
 226  * Resume receiving from this client, we are done processing the
 227  * current request.  This function must be called from within each
 228  * GNUNET_SERVER_MessageCallback (or its respective continuations).
 229  *
 230  * @param client client we were processing a message of
 231  * @param success GNUNET_OK to keep the connection open and
 232  *                          continue to receive
 233  *                GNUNET_NO to close the connection (normal behavior)
 234  *                GNUNET_SYSERR to close the connection (signal
 235  *                          serious error)
 236  */
 237 void
 238 GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success);
 239
 240
 241 /**
 242  * Inject a message into the server, pretend it came
 243  * from the specified client.  Delivery of the message
 244  * will happen instantly (if a handler is installed;
 245  * otherwise the call does nothing).
 246  *
 247  * @param server the server receiving the message
 248  * @param sender the "pretended" sender of the message
 249  *        can be NULL!
 250  * @param message message to transmit
 251  * @return GNUNET_OK if the message was OK and the
 252  *                   connection can stay open
 253  *         GNUNET_SYSERR if the connection to the
 254  *         client should be shut down
 255  */
 256 int
 257 GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
 258                       struct GNUNET_SERVER_Client *sender,
 259                       const struct GNUNET_MessageHeader *message);
 260
 261
 262 /**
 263  * Add a TCP socket-based connection to the set of handles managed by
 264  * this server.  Use this function for outgoing (P2P) connections that
 265  * we initiated (and where this server should process incoming
 266  * messages).
 267  *
 268  * @param server the server to use
 269  * @param connection the connection to manage (client must
 270  *        stop using this connection from now on)
 271  * @return the client handle (client should call
 272  *         "client_drop" on the return value eventually)
 273  */
 274 struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_socket (struct
 275                                                            GNUNET_SERVER_Handle
 276                                                            *server,
 277                                                            struct
 278                                                            GNUNET_CONNECTION_Handle
 279                                                            *connection);
 280
 281
 282 /**
 283  * Notify the server that the given client handle should
 284  * be kept (keeps the connection up if possible, increments
 285  * the internal reference counter).
 286  *
 287  * @param client the client to keep
 288  */
 289 void GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client);
 290
 291
 292 /**
 293  * Notify the server that the given client handle is no
 294  * longer required.  Decrements the reference counter.  If
 295  * that counter reaches zero an inactive connection maybe
 296  * closed.
 297  *
 298  * @param client the client to drop
 299  */
 300 void GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);
 301
 302
 303 /**
 304  * Obtain the network address of the other party.
 305  *
 306  * @param client the client to get the address for
 307  * @param addr where to store the address
 308  * @param addrlen where to store the length of the address
 309  * @return GNUNET_OK on success
 310  */
 311 int GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
 312                                       void **addr, size_t * addrlen);
 313
 314
 315 /**
 316  * Functions with this signature are called whenever a client
 317  * is disconnected on the network level.
 318  *
 319  * @param cls closure
 320  * @param client identification of the client; NULL
 321  *        for the last call when the server is destroyed
 322  */
 323 typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
 324                                                   struct GNUNET_SERVER_Client
 325                                                   * client);
 326
 327
 328 /**
 329  * Ask the server to notify us whenever a client disconnects.
 330  * This function is called whenever the actual network connection
 331  * is closed; the reference count may be zero or larger than zero
 332  * at this point.  If the server is destroyed before this
 333  * notification is explicitly cancelled, the 'callback' will
 334  * once be called with a 'client' argument of NULL to indicate
 335  * that the server itself is now gone (and that the callback
 336  * won't be called anymore and also can no longer be cancelled).
 337  *
 338  * @param server the server manageing the clients
 339  * @param callback function to call on disconnect
 340  * @param callback_cls closure for callback
 341  */
 342 void GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
 343                                       GNUNET_SERVER_DisconnectCallback
 344                                       callback, void *callback_cls);
 345
 346
 347 /**
 348  * Ask the server to stop notifying us whenever a client disconnects.
 349  *
 350  * @param server the server manageing the clients
 351  * @param callback function to call on disconnect
 352  * @param callback_cls closure for callback
 353  */
 354 void GNUNET_SERVER_disconnect_notify_cancel (struct GNUNET_SERVER_Handle *server,
 355                                              GNUNET_SERVER_DisconnectCallback
 356                                              callback, void *callback_cls);
 357
 358
 359 /**
 360  * Ask the server to disconnect from the given client.
 361  * This is the same as returning GNUNET_SYSERR from a message
 362  * handler, except that it allows dropping of a client even
 363  * when not handling a message from that client.
 364  *
 365  * @param client the client to disconnect from
 366  */
 367 void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
 368
 369
 370 /**
 371  * Configure this server's connections to continue handling client
 372  * requests as usual even after we get a shutdown signal.  The change
 373  * only applies to clients that connect to the server from the outside
 374  * using TCP after this call.  Clients managed previously or those
 375  * added using GNUNET_SERVER_connect_socket and
 376  * GNUNET_SERVER_connect_callback are not affected by this option.
 377  *
 378  * @param h server handle
 379  * @param do_ignore GNUNET_YES to ignore, GNUNET_NO to restore default
 380  */
 381 void
 382 GNUNET_SERVER_ignore_shutdown (struct GNUNET_SERVER_Handle *h,
 383                                int do_ignore);
 384
 385
 386
 387 /**
 388  * The tansmit context is the key datastructure for a conveniance API
 389  * used for transmission of complex results to the client followed
 390  * ONLY by signaling receive_done with success or error
 391  */
 392 struct GNUNET_SERVER_TransmitContext;
 393
 394
 395 /**
 396  * Create a new transmission context for the
 397  * given client.
 398  *
 399  * @param client client to create the context for.
 400  * @return NULL on error
 401  */
 402 struct GNUNET_SERVER_TransmitContext
 403   *GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client
 404                                           *client);
 405
 406
 407 /**
 408  * Append a message to the transmission context.
 409  * All messages in the context will be sent by
 410  * the transmit_context_run method.
 411  *
 412  * @param tc context to use
 413  * @param data what to append to the result message
 414  * @param length length of data
 415  * @param type type of the message
 416  */
 417 void
 418 GNUNET_SERVER_transmit_context_append_data (struct GNUNET_SERVER_TransmitContext
 419                                             *tc, const void *data, size_t length,
 420                                             uint16_t type);
 421
 422
 423 /**
 424  * Append a message to the transmission context.
 425  * All messages in the context will be sent by
 426  * the transmit_context_run method.
 427  *
 428  * @param tc context to use
 429  * @param msg message to append
 430  */
 431 void
 432 GNUNET_SERVER_transmit_context_append_message (struct GNUNET_SERVER_TransmitContext
 433                                                *tc, const struct GNUNET_MessageHeader *msg);
 434
 435
 436 /**
 437  * Execute a transmission context.  If there is
 438  * an error in the transmission, the receive_done
 439  * method will be called with an error code (GNUNET_SYSERR),
 440  * otherwise with GNUNET_OK.
 441  *
 442  * @param tc transmission context to use
 443  * @param timeout when to time out and abort the transmission
 444  */
 445 void
 446 GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
 447                                     struct GNUNET_TIME_Relative timeout);
 448
 449
 450
 451 /**
 452  * The notification context is the key datastructure for a conveniance
 453  * API used for transmission of notifications to the client until the
 454  * client disconnects (or the notification context is destroyed, in
 455  * which case we disconnect these clients).  Essentially, all
 456  * (notification) messages are queued up until the client is able to
 457  * read them.
 458  */
 459 struct GNUNET_SERVER_NotificationContext;
 460
 461
 462 /**
 463  * Create a new notification context.
 464  *
 465  * @param server server for which this function creates the context
 466  * @param queue_length maximum number of messages to keep in
 467  *        the notification queue; optional messages are dropped
 468  *        it the queue gets longer than this number of messages
 469  * @return handle to the notification context
 470  */
 471 struct GNUNET_SERVER_NotificationContext *
 472 GNUNET_SERVER_notification_context_create (struct GNUNET_SERVER_Handle *server,
 473                                            unsigned int queue_length);
 474
 475
 476 /**
 477  * Destroy the context, force disconnect for all clients.
 478  *
 479  * @param nc context to destroy.
 480  */
 481 void
 482 GNUNET_SERVER_notification_context_destroy (struct GNUNET_SERVER_NotificationContext *nc);
 483
 484
 485 /**
 486  * Add a client to the notification context.
 487  *
 488  * @param nc context to modify
 489  * @param client client to add
 490  */
 491 void
 492 GNUNET_SERVER_notification_context_add (struct GNUNET_SERVER_NotificationContext *nc,
 493                                         struct GNUNET_SERVER_Client *client);
 494
 495
 496 /**
 497  * Send a message to a particular client; must have
 498  * already been added to the notification context.
 499  *
 500  * @param nc context to modify
 501  * @param client client to transmit to
 502  * @param msg message to send
 503  * @param can_drop can this message be dropped due to queue length limitations
 504  */
 505 void
 506 GNUNET_SERVER_notification_context_unicast (struct GNUNET_SERVER_NotificationContext *nc,
 507                                             struct GNUNET_SERVER_Client *client,
 508                                             const struct GNUNET_MessageHeader *msg,
 509                                             int can_drop);
 510
 511
 512 /**
 513  * Send a message to all clients of this context.
 514  *
 515  * @param nc context to modify
 516  * @param msg message to send
 517  * @param can_drop can this message be dropped due to queue length limitations
 518  */
 519 void
 520 GNUNET_SERVER_notification_context_broadcast (struct GNUNET_SERVER_NotificationContext *nc,
 521                                               const struct GNUNET_MessageHeader *msg,
 522                                               int can_drop);
 523
 524
 525
 526 /**
 527  * Handle to a message stream tokenizer.
 528  */
 529 struct GNUNET_SERVER_MessageStreamTokenizer;
 530
 531 /**
 532  * Functions with this signature are called whenever a
 533  * complete message is received by the tokenizer.
 534  *
 535  * @param cls closure
 536  * @param client identification of the client
 537  * @param message the actual message
 538  */
 539 typedef void (*GNUNET_SERVER_MessageTokenizerCallback) (void *cls,
 540                                                         void *client,
 541                                                         const struct
 542                                                         GNUNET_MessageHeader *
 543                                                         message);
 544
 545
 546 /**
 547  * Create a message stream tokenizer.
 548  *
 549  * @param maxbuf maximum message size to support (typically
 550  *    GNUNET_SERVER_MAX_MESSAGE_SIZE)
 551  * @param cb function to call on completed messages
 552  * @param cb_cls closure for cb
 553  * @return handle to tokenizer
 554  */
 555 struct GNUNET_SERVER_MessageStreamTokenizer *
 556 GNUNET_SERVER_mst_create (size_t maxbuf,
 557                           GNUNET_SERVER_MessageTokenizerCallback cb,
 558                           void *cb_cls);
 559
 560
 561 /**
 562  * Add incoming data to the receive buffer and call the
 563  * callback for all complete messages.
 564  *
 565  * @param mst tokenizer to use
 566  * @param client_identity ID of client for which this is a buffer,
 567  *        can be NULL (will be passed back to 'cb')
 568  * @param buf input data to add
 569  * @param size number of bytes in buf
 570  * @param purge should any excess bytes in the buffer be discarded
 571  *       (i.e. for packet-based services like UDP)
 572  * @param one_shot only call callback once, keep rest of message in buffer
 573  * @return GNUNET_OK if we are done processing (need more data)
 574  *         GNUNET_NO if one_shot was set and we have another message ready
 575  *         GNUNET_SYSERR if the data stream is corrupt
 576  */
 577 int
 578 GNUNET_SERVER_mst_receive (struct GNUNET_SERVER_MessageStreamTokenizer *mst,
 579                            void *client_identity,
 580                            const char *buf,
 581                            size_t size,
 582                            int purge,
 583                            int one_shot);
 584
 585
 586 /**
 587  * Destroys a tokenizer.
 588  *
 589  * @param mst tokenizer to destroy
 590  */
 591 void
 592 GNUNET_SERVER_mst_destroy (struct GNUNET_SERVER_MessageStreamTokenizer *mst);
 593
 594
 595 #if 0                           /* keep Emacsens' auto-indent happy */
 596 {
 597 #endif
 598 #ifdef __cplusplus
 599 }
 600 #endif
 601
 602
 603 /* ifndef GNUNET_SERVER_LIB_H */
 604 #endif
 605 /* end of gnunet_server_lib.h */