src/include/gnunet_server_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009 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 void GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s);
 143
 144
 145 /**
 146  * Add additional handlers to an existing server.
 147  *
 148  * @param server the server to add handlers to
 149  * @param handlers array of message handlers for
 150  *        incoming messages; the last entry must
 151  *        have "NULL" for the "callback"; multiple
 152  *        entries for the same type are allowed,
 153  *        they will be called in order of occurence.
 154  *        These handlers can be removed later;
 155  *        the handlers array must exist until removed
 156  *        (or server is destroyed).
 157  */
 158 void
 159 GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
 160                             const struct GNUNET_SERVER_MessageHandler
 161                             *handlers);
 162
 163
 164 /**
 165  * Notify us when the server has enough space to transmit
 166  * a message of the given size to the given client.
 167  *
 168  * @param client client to transmit message to
 169  * @param size requested amount of buffer space
 170  * @param timeout after how long should we give up (and call
 171  *        notify with buf NULL and size 0)?
 172  * @param callback function to call when space is available
 173  * @param callback_cls closure for callback
 174  * @return non-NULL if the notify callback was queued; can be used
 175  *           to cancel the request using
 176  *           GNUNET_CONNECTION_notify_transmit_ready_cancel.
 177  *         NULL if we are already going to notify someone else (busy)
 178  */
 179 struct GNUNET_CONNECTION_TransmitHandle
 180   *GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client,
 181                                         size_t size,
 182                                         struct GNUNET_TIME_Relative timeout,
 183                                         GNUNET_CONNECTION_TransmitReadyNotify
 184                                         callback, void *callback_cls);
 185
 186
 187 /**
 188  * Resume receiving from this client, we are done processing the
 189  * current request.  This function must be called from within each
 190  * GNUNET_SERVER_MessageCallback (or its respective continuations).
 191  *
 192  * @param client client we were processing a message of
 193  * @param success GNUNET_OK to keep the connection open and
 194  *                          continue to receive
 195  *                GNUNET_SYSERR to close the connection (signal
 196  *                          serious error)
 197  */
 198 void
 199 GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success);
 200
 201
 202 /**
 203  * Inject a message into the server, pretend it came
 204  * from the specified client.  Delivery of the message
 205  * will happen instantly (if a handler is installed;
 206  * otherwise the call does nothing).
 207  *
 208  * @param server the server receiving the message
 209  * @param sender the "pretended" sender of the message
 210  *        can be NULL!
 211  * @param message message to transmit
 212  * @return GNUNET_OK if the message was OK and the
 213  *                   connection can stay open
 214  *         GNUNET_SYSERR if the connection to the
 215  *         client should be shut down
 216  */
 217 int
 218 GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
 219                       struct GNUNET_SERVER_Client *sender,
 220                       const struct GNUNET_MessageHeader *message);
 221
 222
 223 /**
 224  * Add a TCP socket-based connection to the set of handles managed by
 225  * this server.  Use this function for outgoing (P2P) connections that
 226  * we initiated (and where this server should process incoming
 227  * messages).
 228  *
 229  * @param server the server to use
 230  * @param connection the connection to manage (client must
 231  *        stop using this connection from now on)
 232  * @return the client handle (client should call
 233  *         "client_drop" on the return value eventually)
 234  */
 235 struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_socket (struct
 236                                                            GNUNET_SERVER_Handle
 237                                                            *server,
 238                                                            struct
 239                                                            GNUNET_CONNECTION_Handle
 240                                                            *connection);
 241
 242
 243 /**
 244  * Receive data from the given connection.  This function should call
 245  * "receiver" asynchronously using the scheduler.  It must return
 246  * "immediately".
 247  *
 248  * @param cls closure
 249  * @param sched scheduler to use
 250  * @param max maximum number of bytes to read
 251  * @param timeout maximum amount of time to wait (use -1 for "forever")
 252  * @param receiver function to call with received data
 253  * @param receiver_cls closure for receiver
 254  */
 255 typedef void
 256   (*GNUNET_SERVER_ReceiveCallback) (void *cls,
 257                                     size_t max,
 258                                     struct GNUNET_TIME_Relative timeout,
 259                                     GNUNET_CONNECTION_Receiver
 260                                     receiver, void *receiver_cls);
 261
 262
 263 /**
 264  * Cancel receive request.
 265  *
 266  * @param cls closure
 267  */
 268 typedef void (*GNUNET_SERVER_ReceiveCancelCallback) (void *cls);
 269
 270
 271 /**
 272  * Notify us when the connection is ready to transmit size bytes.
 273  *
 274  * @param cls closure
 275  * @param size number of bytes to be ready for sending
 276  * @param timeout after how long should we give up (and call
 277  *        notify with buf NULL and size 0)?
 278  * @param notify function to call
 279  * @param notify_cls closure for notify
 280  * @return a handle that can be used to cancel
 281  *         the transmission request or NULL if
 282  *         queueing a transmission request failed
 283  */
 284 typedef void *(*GNUNET_SERVER_TransmitReadyCallback) (void *cls,
 285                                                       size_t size,
 286                                                       struct
 287                                                       GNUNET_TIME_Relative
 288                                                       timeout,
 289                                                       GNUNET_CONNECTION_TransmitReadyNotify
 290                                                       notify,
 291                                                       void *notify_cls);
 292
 293
 294 /**
 295  * Cancel an earlier transmit notification request.
 296  *
 297  * @param cls closure
 298  * @param ctx handle that was returned by the TransmitReadyCallback
 299  */
 300 typedef void (*GNUNET_SERVER_TransmitReadyCancelCallback) (void *cls,
 301                                                            void *ctx);
 302
 303
 304 /**
 305  * Check if connection is still valid (no fatal errors have happened so far).
 306  *
 307  * @param cls closure
 308  * @return GNUNET_YES if valid, GNUNET_NO otherwise
 309  */
 310 typedef int (*GNUNET_SERVER_CheckCallback) (void *cls);
 311
 312
 313 /**
 314  * Destroy this connection (free resources).
 315  *
 316  * @param cls closure
 317  */
 318 typedef void (*GNUNET_SERVER_DestroyCallback) (void *cls);
 319
 320
 321 /**
 322  * Add an arbitrary connection to the set of handles managed by this
 323  * server.  This can be used if a sending and receiving does not
 324  * really go over the network (internal transmission) or for servers
 325  * using UDP.
 326  *
 327  * @param server the server to use
 328  * @param chandle opaque handle for the connection
 329  * @param creceive receive function for the connection
 330  * @param ccancel cancel receive function for the connection
 331  * @param cnotify transmit notification function for the connection
 332  * @param cnotify_cancel transmit notification cancellation function for the connection
 333  * @param ccheck function to test if the connection is still up
 334  * @param cdestroy function to close and free the connection
 335  * @return the client handle (client should call
 336  *         "client_drop" on the return value eventually)
 337  */
 338 struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_callback (struct
 339                                                              GNUNET_SERVER_Handle
 340                                                              *server,
 341                                                              void *chandle,
 342                                                              GNUNET_SERVER_ReceiveCallback
 343                                                              creceive,
 344                                                              GNUNET_SERVER_ReceiveCancelCallback
 345                                                              ccancel,
 346                                                              GNUNET_SERVER_TransmitReadyCallback
 347                                                              cnotify,
 348                                                              GNUNET_SERVER_TransmitReadyCancelCallback
 349                                                              cnotify_cancel,
 350                                                              GNUNET_SERVER_CheckCallback
 351                                                              ccheck,
 352                                                              GNUNET_SERVER_DestroyCallback
 353                                                              cdestroy);
 354
 355
 356 /**
 357  * Notify the server that the given client handle should
 358  * be kept (keeps the connection up if possible, increments
 359  * the internal reference counter).
 360  *
 361  * @param client the client to keep
 362  */
 363 void GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client);
 364
 365
 366 /**
 367  * Notify the server that the given client handle is no
 368  * longer required.  Decrements the reference counter.  If
 369  * that counter reaches zero an inactive connection maybe
 370  * closed.
 371  *
 372  * @param client the client to drop
 373  */
 374 void GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);
 375
 376
 377 /**
 378  * Obtain the network address of the other party.
 379  *
 380  * @param client the client to get the address for
 381  * @param addr where to store the address
 382  * @param addrlen where to store the length of the address
 383  * @return GNUNET_OK on success
 384  */
 385 int GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
 386                                       void **addr, size_t * addrlen);
 387
 388
 389 /**
 390  * Functions with this signature are called whenever a client
 391  * is disconnected on the network level.
 392  *
 393  * @param cls closure
 394  * @param client identification of the client
 395  */
 396 typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
 397                                                   struct GNUNET_SERVER_Client
 398                                                   * client);
 399
 400
 401 /**
 402  * Ask the server to notify us whenever a client disconnects.
 403  * This function is called whenever the actual network connection
 404  * is closed; the reference count may be zero or larger than zero
 405  * at this point.
 406  *
 407  * @param server the server manageing the clients
 408  * @param callback function to call on disconnect
 409  * @param callback_cls closure for callback
 410  */
 411 void GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
 412                                       GNUNET_SERVER_DisconnectCallback
 413                                       callback, void *callback_cls);
 414
 415
 416 /**
 417  * Ask the server to disconnect from the given client.
 418  * This is the same as returning GNUNET_SYSERR from a message
 419  * handler, except that it allows dropping of a client even
 420  * when not handling a message from that client.
 421  *
 422  * @param client the client to disconnect from
 423  */
 424 void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);
 425
 426
 427 /**
 428  * Configure this server's connections to continue handling client
 429  * requests as usual even after we get a shutdown signal.  The change
 430  * only applies to clients that connect to the server from the outside
 431  * using TCP after this call.  Clients managed previously or those
 432  * added using GNUNET_SERVER_connect_socket and
 433  * GNUNET_SERVER_connect_callback are not affected by this option.
 434  *
 435  * @param h server handle
 436  * @param do_ignore GNUNET_YES to ignore, GNUNET_NO to restore default
 437  */
 438 void
 439 GNUNET_SERVER_ignore_shutdown (struct GNUNET_SERVER_Handle *h,
 440                                int do_ignore);
 441
 442
 443 /**
 444  * The tansmit context is the key datastructure for a conveniance API
 445  * used for transmission of complex results to the client followed
 446  * ONLY by signaling receive_done with success or error
 447  */
 448 struct GNUNET_SERVER_TransmitContext;
 449
 450
 451 /**
 452  * Create a new transmission context for the
 453  * given client.
 454  *
 455  * @param client client to create the context for.
 456  * @return NULL on error
 457  */
 458 struct GNUNET_SERVER_TransmitContext
 459   *GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client
 460                                           *client);
 461
 462
 463 /**
 464  * Append a message to the transmission context.
 465  * All messages in the context will be sent by
 466  * the transmit_context_run method.
 467  *
 468  * @param tc context to use
 469  * @param data what to append to the result message
 470  * @param length length of data
 471  * @param type type of the message
 472  */
 473 void
 474 GNUNET_SERVER_transmit_context_append (struct GNUNET_SERVER_TransmitContext
 475                                        *tc, const void *data, size_t length,
 476                                        uint16_t type);
 477
 478 /**
 479  * Execute a transmission context.  If there is
 480  * an error in the transmission, the receive_done
 481  * method will be called with an error code (GNUNET_SYSERR),
 482  * otherwise with GNUNET_OK.
 483  *
 484  * @param tc transmission context to use
 485  * @param timeout when to time out and abort the transmission
 486  */
 487 void
 488 GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
 489                                     struct GNUNET_TIME_Relative timeout);
 490
 491
 492
 493 #if 0                           /* keep Emacsens' auto-indent happy */
 494 {
 495 #endif
 496 #ifdef __cplusplus
 497 }
 498 #endif
 499
 500
 501 /* ifndef GNUNET_SERVER_LIB_H */
 502 #endif
 503 /* end of gnunet_server_lib.h */