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