src/include/gnunet_server_lib.h

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