lib/silcutil/silcsocketstream.h

   1 /*
   2
   3   silcsocketstream.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Socket Stream Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementation of SILC Socket Stream.  SILC Socket Stream can be used
  25  * read data from and write data to a socket connection.  The SILC Socket
  26  * Stream provides also Quality of Service (QoS) support that can be used
  27  * to control the throughput of the stream.
  28  *
  29  ***/
  30
  31 #ifndef SILCSOCKETSTREAM_H
  32 #define SILCSOCKETSTREAM_H
  33
  34 /****d* silcutil/SilcSocketStreamAPI/SilcSocketStreamStatus
  35  *
  36  * NAME
  37  *
  38  *    typedef enum { ... } SilcStreamStatus;
  39  *
  40  * DESCRIPTION
  41  *
  42  *    Socket Stream status.  This status is returned into the
  43  *    SilcSocketStreamCallback function after the socket stream is
  44  *    created.
  45  *
  46  * SOURCE
  47  */
  48 typedef enum {
  49   SILC_SOCKET_OK,               /* Normal status */
  50   SILC_SOCKET_UNKNOWN_IP,       /* Remote does not have IP address */
  51   SILC_SOCKET_UNKNOWN_HOST,     /* Remote does not have host name */
  52   SILC_SOCKET_NO_MEMORY,        /* System out of memory */
  53   SILC_SOCKET_ERROR,            /* Unknown error */
  54 } SilcSocketStreamStatus;
  55 /***/
  56
  57 /****f* silcutil/SilcSocketStreamAPI/SilcSocketStreamCallback
  58  *
  59  * SYNOPSIS
  60  *
  61  *    typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
  62  *                                             SilcStream stream,
  63  *                                             void *context);
  64  *
  65  * DESCRIPTION
  66  *
  67  *    Callback function of this type is called after the socket stream
  68  *    creation is completed.  If the `stream' is NULL the socket stream could
  69  *    not be created of the socket connection is not otherwise allowed.  The
  70  *    `status' will indicate the error status.  The `stream' is socket stream
  71  *    representing the socket connection and silc_socket_stream_* functions
  72  *    can be used to access the stream.  All other silc_stream_* functions
  73  *    can also be used to read data, send data, and otherwise handle the
  74  *    stream.
  75  *
  76  ***/
  77 typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
  78                                          SilcStream stream, void *context);
  79
  80 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_create
  81  *
  82  * SYNOPSIS
  83  *
  84  *    SilcAsyncOperation
  85  *    silc_socket_stream_create(int sock, bool lookup, bool require_fqdn,
  86  *                              SilcSchedule schedule,
  87  *                              SilcSocketStreamCallback callback,
  88  *                              void *context);
  89  *
  90  * DESCRIPTION
  91  *
  92  *    Creates new socket stream of the socket connection indicated by `sock'.
  93  *    The stream can be destroyed by calling the silc_stream_destroy.  Data
  94  *    can be sent and received from the stream by calling silc_stream_write
  95  *    and silc_stream_read.  The creation process is asynchronous since
  96  *    socket connection information, such as hostname and IP address are
  97  *    resolved, so SilcAsyncOperation is returned which can be used to cancel
  98  *    the creationg process.  The `callback' will be called to return the
  99  *    created socket stream.  To destroy the stream call silc_stream_destroy.
 100  *
 101  *    If the `lookup' is TRUE then this will performed IP and hostname lookup
 102  *    for the socket.  If the `require_fqdn' is TRUE then the socket must
 103  *    have valid hostname and IP address, otherwise the stream creation will
 104  *    fail.  If it is FALSE then only valid IP address is required.  Note that,
 105  *    if the `lookup' is FALSE then the hostname, IP and port information
 106  *    will not be available from the socket stream.
 107  *
 108  ***/
 109 SilcAsyncOperation
 110 silc_socket_stream_create(int sock, bool lookup, bool require_fqdn,
 111                           SilcSchedule schedule,
 112                           SilcSocketStreamCallback callback,
 113                           void *context);
 114
 115 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_info
 116  *
 117  * SYNOPSIS
 118  *
 119  *    bool
 120  *    silc_socket_stream_get_info(SilcStream stream,
 121  *                                int *sock, const char **hostname,
 122  *                                const char **ip, SilcUInt16 *port);
 123  *
 124  * DESCRIPTION
 125  *
 126  *    Returns socket stream information such as the socket number, hostname,
 127  *    IP address and the port of the remote socket connection.  Return FALSE
 128  *    if these informations are not available.
 129  *
 130  ***/
 131 bool silc_socket_stream_get_info(SilcStream stream,
 132                                  int *sock, const char **hostname,
 133                                  const char **ip, SilcUInt16 *port);
 134
 135 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_info
 136  *
 137  * SYNOPSIS
 138  *
 139  *    bool
 140  *    silc_socket_stream_set_info(SilcStream stream,
 141  *                                const char *hostname,
 142  *                                const char *ip, SilcUInt16 port);
 143  *
 144  * DESCRIPTION
 145  *
 146  *    Use this function to set the hostname, IP address and remote port
 147  *    information to the socket stream indicated by `stream' if you did not
 148  *    perform lookup in the silc_socket_create_stream.  This is not mandatory
 149  *    but if you would like to associate the information with the stream
 150  *    use this function.  If the lookup was performed when creating the
 151  *    stream then calling this function is not necessary.  Use the function
 152  *    silc_socket_stream_get_info to get the information from the stream.
 153  *
 154  ***/
 155 bool silc_socket_stream_set_info(SilcStream stream,
 156                                  const char *hostname,
 157                                  const char *ip, SilcUInt16 port);
 158
 159 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_error
 160  *
 161  * SYNOPSIS
 162  *
 163  *    int silc_socket_stream_get_error(SilcStream stream);
 164  *
 165  * DESCRIPTION
 166  *
 167  *    If error occurred during socket stream operations, this function
 168  *    can be used to retrieve the error number that occurred.
 169  *
 170  ***/
 171 int silc_socket_stream_get_error(SilcStream stream);
 172
 173 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_qos
 174  *
 175  * SYNOPSIS
 176  *
 177  *    bool silc_socket_stream_set_qos(SilcStream stream,
 178  *                                    SilcUInt32 read_rate,
 179  *                                    SilcUInt32 read_limit_bytes,
 180  *                                    SilcUInt32 limit_sec,
 181  *                                    SilcUInt32 limit_usec)
 182  *
 183  * DESCRIPTION
 184  *
 185  *    Sets a "Quality of Service" settings for socket stream `stream'.
 186  *    The `read_rate' specifies the maximum read operations per second.
 187  *    If more read operations are executed the limit will be applied for
 188  *    the reading.  The `read_limit_bytes' specifies the maximum data
 189  *    that is read.  It is guaranteed that silc_stream_read  never returns
 190  *    more than `read_limit_bytes' of data.  The `limit_sec' and `limit_usec'
 191  *    specifies the time limit that is applied if `read_rate' and/or
 192  *    `read_limit_bytes' is reached.  If all arguments except `stream'
 193  *    are zero this resets the QoS from the socket stream, all QoS for
 194  *    this socket stream that may be pending will be cancelled.
 195  *
 196  ***/
 197 bool silc_socket_stream_set_qos(SilcStream stream,
 198                                 SilcUInt32 read_rate,
 199                                 SilcUInt32 read_limit_bytes,
 200                                 SilcUInt32 limit_sec,
 201                                 SilcUInt32 limit_usec);
 202
 203 #include "silcsocketstream_i.h"
 204
 205 #endif /* SILCSOCKETSTREAM_H */