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