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