lib/silcutil/silcsocketstream.h

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