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