lib/silcutil/silcsocketstream.h

   1 /*
   2
   3   silcsocketstream.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2005 - 2006 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  * SILC Socket Stream is not thread-safe.  If the same socket stream must be
  30  * used in multithreaded environment concurrency control must be employed.
  31  *
  32  ***/
  33
  34 #ifndef SILCSOCKETSTREAM_H
  35 #define SILCSOCKETSTREAM_H
  36
  37 /****d* silcutil/SilcSocketStreamAPI/SilcSocketStreamStatus
  38  *
  39  * NAME
  40  *
  41  *    typedef enum { ... } SilcStreamStatus;
  42  *
  43  * DESCRIPTION
  44  *
  45  *    Socket Stream status.  This status is returned into the
  46  *    SilcSocketStreamCallback function after the socket stream is
  47  *    created.
  48  *
  49  * SOURCE
  50  */
  51 typedef enum {
  52   SILC_SOCKET_OK,               /* Normal status */
  53   SILC_SOCKET_UNKNOWN_IP,       /* Remote does not have IP address */
  54   SILC_SOCKET_UNKNOWN_HOST,     /* Remote does not have host name */
  55   SILC_SOCKET_NO_MEMORY,        /* System out of memory */
  56   SILC_SOCKET_ERROR,            /* Unknown error */
  57 } SilcSocketStreamStatus;
  58 /***/
  59
  60 /****f* silcutil/SilcSocketStreamAPI/SilcSocketStreamCallback
  61  *
  62  * SYNOPSIS
  63  *
  64  *    typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
  65  *                                             SilcStream stream,
  66  *                                             void *context);
  67  *
  68  * DESCRIPTION
  69  *
  70  *    Callback function of this type is called after the socket stream
  71  *    creation is completed.  If the `stream' is NULL the socket stream could
  72  *    not be created or the socket connection is not otherwise allowed.  The
  73  *    `status' will indicate the error status.  The `stream' is socket stream
  74  *    representing the socket connection and silc_socket_stream_* functions
  75  *    can be used to access the stream.  All other silc_stream_* functions
  76  *    can also be used to read data, send data, and otherwise handle the
  77  *    stream.
  78  *
  79  ***/
  80 typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
  81                                          SilcStream stream, void *context);
  82
  83 /****f* silcutil/SilcSocketStreamAPI/silc_socket_tcp_stream_create
  84  *
  85  * SYNOPSIS
  86  *
  87  *    SilcAsyncOperation
  88  *    silc_socket_tcp_stream_create(int sock, SilcBool lookup,
  89  *                                  SilcBool require_fqdn,
  90  *                                  SilcSchedule schedule,
  91  *                                  SilcSocketStreamCallback callback,
  92  *                                  void *context);
  93  *
  94  * DESCRIPTION
  95  *
  96  *    Creates TCP socket stream of the TCP connection indicated by `sock'.
  97  *    The stream can be destroyed by calling the silc_stream_destroy.  Data
  98  *    can be sent and received from the stream by calling silc_stream_write
  99  *    and silc_stream_read.  The creation process is asynchronous since
 100  *    socket connection information, such as hostname and IP address are
 101  *    resolved, so SilcAsyncOperation is returned which can be used to cancel
 102  *    the creation process.  The `callback' will be called to return the
 103  *    created socket stream.  To destroy the stream call silc_stream_destroy.
 104  *
 105  *    If the `lookup' is TRUE then this will performed IP and hostname lookup
 106  *    for the socket.  If the `require_fqdn' is TRUE then the socket must
 107  *    have valid hostname and IP address, otherwise the stream creation will
 108  *    fail.  If it is FALSE then only valid IP address is required.  Note that,
 109  *    if the `lookup' is FALSE then the hostname, IP and port information
 110  *    will not be available from the socket stream.
 111  *
 112  ***/
 113 SilcAsyncOperation
 114 silc_socket_tcp_stream_create(int sock, SilcBool lookup,
 115                               SilcBool require_fqdn,
 116                               SilcSchedule schedule,
 117                               SilcSocketStreamCallback callback,
 118                               void *context);
 119
 120 /****f* silcutil/SilcSocketStreamAPI/silc_socket_udp_stream_create
 121  *
 122  * SYNOPSIS
 123  *
 124  *    SilcStream silc_socket_udp_stream_create(int sock, SilcBool ipv6,
 125  *                                             SilcSchedule schedule);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Creates UDP socket stream of the UDP connection indicated by `sock'.
 130  *    The stream can be destroyed by calling the silc_stream_destroy.
 131  *
 132  *    Note that, UDP packets may be read only through the notifier
 133  *    callback (see silc_stream_set_notifier), when SILC_STREAM_CAN_READ
 134  *    is returned to the callback.  Because of this the notifier callback
 135  *    must be set.
 136  *
 137  *    Note that, UDP packet sending using silc_stream_write and receiving
 138  *    with silc_stream_read works only if the `sock' is a UDP socket in a
 139  *    connected state.  If it is not the silc_net_udp_send function and
 140  *    silc_net_udp_receive functions must be used.  The SILC_STREAM_CAN_WRITE
 141  *    is never returned to the notifier callback.
 142  *
 143  *    This function returns the created SilcStream or NULL on error.
 144  *
 145  ***/
 146 SilcStream silc_socket_udp_stream_create(int sock, SilcBool ipv6,
 147                                          SilcSchedule schedule);
 148
 149 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_info
 150  *
 151  * SYNOPSIS
 152  *
 153  *    SilcBool
 154  *    silc_socket_stream_get_info(SilcStream stream,
 155  *                                int *sock, const char **hostname,
 156  *                                const char **ip, SilcUInt16 *port);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Returns socket stream information such as the socket number, hostname,
 161  *    IP address and the port of the remote socket connection.  Return FALSE
 162  *    if these informations are not available.
 163  *
 164  ***/
 165 SilcBool silc_socket_stream_get_info(SilcStream stream,
 166                                      int *sock, const char **hostname,
 167                                      const char **ip, SilcUInt16 *port);
 168
 169 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_info
 170  *
 171  * SYNOPSIS
 172  *
 173  *    SilcBool
 174  *    silc_socket_stream_set_info(SilcStream stream,
 175  *                                const char *hostname,
 176  *                                const char *ip, SilcUInt16 port);
 177  *
 178  * DESCRIPTION
 179  *
 180  *    Use this function to set the hostname, IP address and remote port
 181  *    information to the socket stream indicated by `stream' if you did not
 182  *    perform lookup in the silc_socket_create_stream.  This is not mandatory
 183  *    but if you would like to associate the information with the stream
 184  *    use this function.  If the lookup was performed when creating the
 185  *    stream then calling this function is not necessary.  Use the function
 186  *    silc_socket_stream_get_info to get the information from the stream.
 187  *
 188  ***/
 189 SilcBool silc_socket_stream_set_info(SilcStream stream,
 190                                      const char *hostname,
 191                                      const char *ip, SilcUInt16 port);
 192
 193 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_error
 194  *
 195  * SYNOPSIS
 196  *
 197  *    int silc_socket_stream_get_error(SilcStream stream);
 198  *
 199  * DESCRIPTION
 200  *
 201  *    If error occurred during socket stream operations, this function
 202  *    can be used to retrieve the error number that occurred.
 203  *
 204  ***/
 205 int silc_socket_stream_get_error(SilcStream stream);
 206
 207 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_qos
 208  *
 209  * SYNOPSIS
 210  *
 211  *    SilcBool silc_socket_stream_set_qos(SilcStream stream,
 212  *                                        SilcUInt32 read_rate,
 213  *                                        SilcUInt32 read_limit_bytes,
 214  *                                        SilcUInt32 limit_sec,
 215  *                                        SilcUInt32 limit_usec)
 216  *
 217  * DESCRIPTION
 218  *
 219  *    Sets a "Quality of Service" settings for socket stream `stream'.
 220  *    The `read_rate' specifies the maximum read operations per second.
 221  *    If more read operations are executed the limit will be applied for
 222  *    the reading.  The `read_limit_bytes' specifies the maximum data
 223  *    that is read.  It is guaranteed that silc_stream_read  never returns
 224  *    more than `read_limit_bytes' of data.  The `limit_sec' and `limit_usec'
 225  *    specifies the time limit that is applied if `read_rate' and/or
 226  *    `read_limit_bytes' is reached.  If all arguments except `stream'
 227  *    are zero this resets the QoS from the socket stream, all QoS for
 228  *    this socket stream that may be pending will be cancelled.
 229  *
 230  ***/
 231 SilcBool silc_socket_stream_set_qos(SilcStream stream,
 232                                     SilcUInt32 read_rate,
 233                                     SilcUInt32 read_limit_bytes,
 234                                     SilcUInt32 limit_sec,
 235                                     SilcUInt32 limit_usec);
 236
 237 #include "silcsocketstream_i.h"
 238
 239 #endif /* SILCSOCKETSTREAM_H */