path: root/src/include/gnunet_server_lib.h

/*
     This file is part of GNUnet.
     (C) 2009 Christian Grothoff (and other contributing authors)

     GNUnet is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published
     by the Free Software Foundation; either version 2, or (at your
     option) any later version.

     GNUnet is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with GNUnet; see the file COPYING.  If not, write to the
     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
*/

/**
 * @file include/gnunet_server_lib.h
 * @brief library for building GNUnet network servers
 *
 * @author Christian Grothoff
 */

#ifndef GNUNET_SERVER_LIB_H
#define GNUNET_SERVER_LIB_H

#ifdef __cplusplus
extern "C"
{
#if 0                           /* keep Emacsens' auto-indent happy */
}
#endif
#endif

#include "gnunet_common.h"
#include "gnunet_network_lib.h"
#include "gnunet_scheduler_lib.h"


/**
 * Largest supported message.
 */
#define GNUNET_SERVER_MAX_MESSAGE_SIZE 65536


/**
 * @brief handle for a server
 */
struct GNUNET_SERVER_Handle;


/**
 * @brief opaque handle for a client of the server
 */
struct GNUNET_SERVER_Client;


/**
 * Functions with this signature are called whenever a message is
 * received.
 *
 * @param cls closure
 * @param server the server handling the message
 * @param client identification of the client
 * @param message the actual message
 */
typedef void (*GNUNET_SERVER_MessageCallback) (void *cls,
                                               struct GNUNET_SERVER_Handle *
                                               server,
                                               struct GNUNET_SERVER_Client *
                                               client,
                                               const struct
                                               GNUNET_MessageHeader *
                                               message);



/**
 * Message handler.  Each struct specifies how to handle on particular
 * type of message received.
 */
struct GNUNET_SERVER_MessageHandler
{
  /**
   * Function to call for messages of "type".
   */
  GNUNET_SERVER_MessageCallback callback;

  /**
   * Closure argument for "callback".
   */
  void *callback_cls;

  /**
   * Type of the message this handler covers.
   */
  uint16_t type;

  /**
   * Expected size of messages of this type.  Use 0 for
   * variable-size.  If non-zero, messages of the given
   * type will be discarded (and the connection closed)
   * if they do not have the right size.
   */
  uint16_t expected_size;

};


/**
 * Create a new server.
 *
 * @param sched scheduler to use
 * @param access function for access control
 * @param access_cls closure for access
 * @param serverAddr address to listen on (including port), use NULL
 *        for internal server (no listening)
 * @param socklen length of serverAddr
 * @param maxbuf maximum write buffer size for accepted sockets
 * @param idle_timeout after how long should we timeout idle connections?
 * @param require_found if YES, connections sending messages of unknown type
 *        will be closed
 * @return handle for the new server, NULL on error
 *         (typically, "port" already in use)
 */
struct GNUNET_SERVER_Handle *GNUNET_SERVER_create (struct
                                                   GNUNET_SCHEDULER_Handle
                                                   *sched,
                                                   GNUNET_NETWORK_AccessCheck
                                                   access, void *access_cls,
                                                   const struct sockaddr
                                                   *serverAddr,
                                                   socklen_t socklen,
                                                   size_t maxbuf,
                                                   struct GNUNET_TIME_Relative
                                                   idle_timeout,
                                                   int require_found);


/**
 * Free resources held by this server.
 */
void GNUNET_SERVER_destroy (struct GNUNET_SERVER_Handle *s);


/**
 * Add additional handlers to an existing server.
 *
 * @param server the server to add handlers to
 * @param handlers array of message handlers for
 *        incoming messages; the last entry must
 *        have "NULL" for the "callback"; multiple
 *        entries for the same type are allowed,
 *        they will be called in order of occurence.
 *        These handlers can be removed later;
 *        the handlers array must exist until removed
 *        (or server is destroyed).
 */
void
GNUNET_SERVER_add_handlers (struct GNUNET_SERVER_Handle *server,
                            const struct GNUNET_SERVER_MessageHandler
                            *handlers);


/**
 * Notify us when the server has enough space to transmit
 * a message of the given size to the given client.
 *
 * @param client client to transmit message to
 * @param size requested amount of buffer space
 * @param timeout after how long should we give up (and call
 *        notify with buf NULL and size 0)?
 * @param callback function to call when space is available
 * @param callback_cls closure for callback
 * @return non-NULL if the notify callback was queued; can be used
 *           to cancel the request using
 *           GNUNET_NETWORK_notify_transmit_ready_cancel.
 *         NULL if we are already going to notify someone else (busy)
 */
struct GNUNET_NETWORK_TransmitHandle
  *GNUNET_SERVER_notify_transmit_ready (struct GNUNET_SERVER_Client *client,
                                        size_t size,
                                        struct GNUNET_TIME_Relative timeout,
                                        GNUNET_NETWORK_TransmitReadyNotify
                                        callback, void *callback_cls);


/**
 * Resume receiving from this client, we are done processing the
 * current request.  This function must be called from within each
 * GNUNET_SERVER_MessageCallback (or its respective continuations).
 *
 * @param client client we were processing a message of
 * @param success GNUNET_OK to keep the connection open and
 *                          continue to receive
 *                GNUNET_SYSERR to close the connection (signal
 *                          serious error)
 */
void
GNUNET_SERVER_receive_done (struct GNUNET_SERVER_Client *client, int success);


/**
 * Inject a message into the server, pretend it came
 * from the specified client.  Delivery of the message
 * will happen instantly (if a handler is installed;
 * otherwise the call does nothing).
 *
 * @param server the server receiving the message
 * @param sender the "pretended" sender of the message
 *        can be NULL!
 * @param message message to transmit
 * @return GNUNET_OK if the message was OK and the
 *                   connection can stay open
 *         GNUNET_SYSERR if the connection to the
 *         client should be shut down
 */
int
GNUNET_SERVER_inject (struct GNUNET_SERVER_Handle *server,
                      struct GNUNET_SERVER_Client *sender,
                      const struct GNUNET_MessageHeader *message);


/**
 * Add a TCP socket-based connection to the set of handles managed by
 * this server.  Use this function for outgoing (P2P) connections that
 * we initiated (and where this server should process incoming
 * messages).
 *
 * @param server the server to use
 * @param connection the connection to manage (client must
 *        stop using this connection from now on)
 * @return the client handle (client should call
 *         "client_drop" on the return value eventually)
 */
struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_socket (struct
                                                           GNUNET_SERVER_Handle
                                                           *server,
                                                           struct
                                                           GNUNET_NETWORK_SocketHandle
                                                           *connection);


/**
 * Receive data from the given connection.  This function should call
 * "receiver" asynchronously using the scheduler.  It must return
 * "immediately".
 *
 * @param cls closure
 * @param sched scheduler to use
 * @param max maximum number of bytes to read
 * @param timeout maximum amount of time to wait (use -1 for "forever")
 * @param receiver function to call with received data
 * @param receiver_cls closure for receiver
 * @return task identifier that can be used to cancel the receive,
 *         GNUNET_SCHEDULER_NO_PREREQUISITE_TASK should be returned
 *         if the receiver function was already called
 */
typedef GNUNET_SCHEDULER_TaskIdentifier
  (*GNUNET_SERVER_ReceiveCallback) (void *cls,
                                    size_t max,
                                    struct GNUNET_TIME_Relative timeout,
                                    GNUNET_NETWORK_Receiver
                                    receiver, void *receiver_cls);


/**
 * Cancel receive request.
 *
 * @param cls closure
 * @param ti task identifier from the receive callback
 */
typedef void (*GNUNET_SERVER_ReceiveCancelCallback) (void *cls,
                                                     GNUNET_SCHEDULER_TaskIdentifier
                                                     ti);


/**
 * Notify us when the connection is ready to transmit size bytes.
 *
 * @param cls closure
 * @param size number of bytes to be ready for sending
 * @param timeout after how long should we give up (and call
 *        notify with buf NULL and size 0)?
 * @param notify function to call
 * @param notify_cls closure for notify
 * @return a handle that can be used to cancel
 *         the transmission request or NULL if
 *         queueing a transmission request failed
 */
typedef void *(*GNUNET_SERVER_TransmitReadyCallback) (void *cls,
                                                      size_t size,
                                                      struct
                                                      GNUNET_TIME_Relative
                                                      timeout,
                                                      GNUNET_NETWORK_TransmitReadyNotify
                                                      notify,
                                                      void *notify_cls);


/**
 * Cancel an earlier transmit notification request.
 *
 * @param cls closure
 * @param ctx handle that was returned by the TransmitReadyCallback
 */
typedef void (*GNUNET_SERVER_TransmitReadyCancelCallback) (void *cls,
                                                           void *ctx);


/**
 * Check if connection is still valid (no fatal errors have happened so far).
 *
 * @param cls closure
 * @return GNUNET_YES if valid, GNUNET_NO otherwise
 */
typedef int (*GNUNET_SERVER_CheckCallback) (void *cls);


/**
 * Destroy this connection (free resources).
 *
 * @param cls closure
 */
typedef void (*GNUNET_SERVER_DestroyCallback) (void *cls);


/**
 * Add an arbitrary connection to the set of handles managed by this
 * server.  This can be used if a sending and receiving does not
 * really go over the network (internal transmission) or for servers
 * using UDP.
 *
 * @param server the server to use
 * @param chandle opaque handle for the connection
 * @param creceive receive function for the connection
 * @param creceive_cancel cancel receive function for the connection
 * @param cnotify transmit notification function for the connection
 * @param cnotify_cancel transmit notification cancellation function for the connection
 * @param ccheck function to test if the connection is still up
 * @param cdestroy function to close and free the connection
 * @return the client handle (client should call
 *         "client_drop" on the return value eventually)
 */
struct GNUNET_SERVER_Client *GNUNET_SERVER_connect_callback (struct
                                                             GNUNET_SERVER_Handle
                                                             *server,
                                                             void *chandle,
                                                             GNUNET_SERVER_ReceiveCallback
                                                             creceive,
                                                             GNUNET_SERVER_ReceiveCancelCallback
                                                             ccancel,
                                                             GNUNET_SERVER_TransmitReadyCallback
                                                             cnotify,
                                                             GNUNET_SERVER_TransmitReadyCancelCallback
                                                             cnotify_cancel,
                                                             GNUNET_SERVER_CheckCallback
                                                             ccheck,
                                                             GNUNET_SERVER_DestroyCallback
                                                             cdestroy);


/**
 * Notify the server that the given client handle should
 * be kept (keeps the connection up if possible, increments
 * the internal reference counter).
 *
 * @param client the client to keep
 */
void GNUNET_SERVER_client_keep (struct GNUNET_SERVER_Client *client);


/**
 * Notify the server that the given client handle is no
 * longer required.  Decrements the reference counter.  If
 * that counter reaches zero an inactive connection maybe
 * closed.
 *
 * @param client the client to drop
 */
void GNUNET_SERVER_client_drop (struct GNUNET_SERVER_Client *client);


/**
 * Obtain the network address of the other party.
 *
 * @param client the client to get the address for
 * @param addr where to store the address
 * @param addrlen where to store the length of the address
 * @return GNUNET_OK on success
 */
int GNUNET_SERVER_client_get_address (struct GNUNET_SERVER_Client *client,
                                      void **addr, size_t * addrlen);


/**
 * Functions with this signature are called whenever a client
 * is disconnected on the network level.
 *
 * @param cls closure
 * @param client identification of the client
 */
typedef void (*GNUNET_SERVER_DisconnectCallback) (void *cls,
                                                  struct GNUNET_SERVER_Client
                                                  * client);


/**
 * Ask the server to notify us whenever a client disconnects.
 * This function is called whenever the actual network connection
 * is closed; the reference count may be zero or larger than zero
 * at this point.
 *
 * @param server the server manageing the clients
 * @param callback function to call on disconnect
 * @param callback_cls closure for callback
 */
void GNUNET_SERVER_disconnect_notify (struct GNUNET_SERVER_Handle *server,
                                      GNUNET_SERVER_DisconnectCallback
                                      callback, void *callback_cls);


/**
 * Ask the server to disconnect from the given client.
 * This is the same as returning GNUNET_SYSERR from a message
 * handler, except that it allows dropping of a client even
 * when not handling a message from that client.
 *
 * @param client the client to disconnect from
 */
void GNUNET_SERVER_client_disconnect (struct GNUNET_SERVER_Client *client);


/**
 * The tansmit context is the key datastructure for a conveniance API
 * used for transmission of complex results to the client followed
 * ONLY by signaling receive_done with success or error
 */
struct GNUNET_SERVER_TransmitContext;


/**
 * Create a new transmission context for the
 * given client.
 *
 * @param client client to create the context for.
 * @return NULL on error
 */
struct GNUNET_SERVER_TransmitContext
  *GNUNET_SERVER_transmit_context_create (struct GNUNET_SERVER_Client
                                          *client);


/**
 * Append a message to the transmission context.
 * All messages in the context will be sent by
 * the transmit_context_run method.
 *
 * @param tc context to use
 * @param data what to append to the result message
 * @param length length of data
 * @param type type of the message
 */
void
GNUNET_SERVER_transmit_context_append (struct GNUNET_SERVER_TransmitContext
                                       *tc, const void *data, size_t length,
                                       uint16_t type);

/**
 * Execute a transmission context.  If there is
 * an error in the transmission, the receive_done
 * method will be called with an error code (GNUNET_SYSERR),
 * otherwise with GNUNET_OK.
 *
 * @param tc transmission context to use
 * @param timeout when to time out and abort the transmission
 */
void
GNUNET_SERVER_transmit_context_run (struct GNUNET_SERVER_TransmitContext *tc,
                                    struct GNUNET_TIME_Relative timeout);



#if 0                           /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
}
#endif


/* ifndef GNUNET_SERVER_LIB_H */
#endif
/* end of gnunet_server_lib.h */