5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcutil/Socket Stream Interface
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.
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.
35 #ifndef SILCSOCKETSTREAM_H
36 #define SILCSOCKETSTREAM_H
38 /****f* silcutil/SilcSocketStreamCallback
42 * typedef void (*SilcSocketStreamCallback)(SilcResult status,
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
58 * If the silc_stream_set_notifier is called the stream will be set to
62 typedef void (*SilcSocketStreamCallback)(SilcResult status,
63 SilcStream stream, void *context);
65 /****f* silcutil/silc_socket_tcp_stream_create
70 * silc_socket_tcp_stream_create(SilcSocket sock, SilcBool lookup,
71 * SilcBool require_fqdn,
72 * SilcSchedule schedule,
73 * SilcSocketStreamCallback callback,
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.
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.
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.
101 silc_socket_tcp_stream_create(SilcSocket sock, SilcBool lookup,
102 SilcBool require_fqdn,
103 SilcSchedule schedule,
104 SilcSocketStreamCallback callback,
107 /****f* silcutil/silc_socket_udp_stream_create
111 * SilcStream silc_socket_udp_stream_create(SilcSocket sock,
113 * SilcBool connected,
114 * SilcSchedule schedule);
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.
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
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.
137 * This function returns the created SilcStream or NULL on error.
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.
144 SilcStream silc_socket_udp_stream_create(SilcSocket sock,
147 SilcSchedule schedule);
149 /****f* silcutil/silc_socket_stream_is_udp
153 * SilcBool silc_socket_stream_is_udp(SilcStream stream,
154 * SilcBool *connected);
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
166 SilcBool silc_socket_stream_is_udp(SilcStream stream, SilcBool *connected);
168 /****f* silcutil/silc_socket_stream_get_info
173 * silc_socket_stream_get_info(SilcStream stream,
174 * SilcSocket *sock, const char **hostname,
175 * const char **ip, SilcUInt16 *port);
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.
184 SilcBool silc_socket_stream_get_info(SilcStream stream,
185 SilcSocket *sock, const char **hostname,
186 const char **ip, SilcUInt16 *port);
188 /****f* silcutil/silc_socket_stream_set_info
193 * silc_socket_stream_set_info(SilcStream stream,
194 * const char *hostname,
195 * const char *ip, SilcUInt16 port);
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
209 SilcBool silc_socket_stream_set_info(SilcStream stream,
210 const char *hostname,
211 const char *ip, SilcUInt16 port);
213 /****f* silcutil/silc_socket_stream_set_qos
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)
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 data for
234 * this socket stream that may be pending will be cancelled.
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);
243 #include "silcsocketstream_i.h"
245 #endif /* SILCSOCKETSTREAM_H */