5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 - 2006 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/SILC 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 /****d* silcutil/SilcSocketStreamAPI/SilcSocketStreamStatus
42 * typedef enum { ... } SilcStreamStatus;
46 * Socket Stream status. This status is returned into the
47 * SilcSocketStreamCallback function after the socket stream is
53 SILC_SOCKET_OK, /* Normal status */
54 SILC_SOCKET_UNKNOWN_IP, /* Remote does not have IP address */
55 SILC_SOCKET_UNKNOWN_HOST, /* Remote does not have host name */
56 SILC_SOCKET_NO_MEMORY, /* System out of memory */
57 SILC_SOCKET_ERROR, /* Unknown error */
58 } SilcSocketStreamStatus;
61 /****f* silcutil/SilcSocketStreamAPI/SilcSocketStreamCallback
65 * typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
71 * Callback function of this type is called after the socket stream
72 * creation is completed. If the `stream' is NULL the socket stream could
73 * not be created or the socket connection is not otherwise allowed. The
74 * `status' will indicate the error status. The `stream' is socket stream
75 * representing the socket connection and silc_socket_stream_* functions
76 * can be used to access the stream. All other silc_stream_* functions
77 * can also be used to read data, send data, and otherwise handle the
81 typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
82 SilcStream stream, void *context);
84 /****f* silcutil/SilcSocketStreamAPI/silc_socket_tcp_stream_create
89 * silc_socket_tcp_stream_create(int sock, SilcBool lookup,
90 * SilcBool require_fqdn,
91 * SilcSchedule schedule,
92 * SilcSocketStreamCallback callback,
97 * Creates TCP socket stream of the TCP connection indicated by `sock'.
98 * The stream can be destroyed by calling the silc_stream_destroy. Data
99 * can be sent and received from the stream by calling silc_stream_write
100 * and silc_stream_read. The creation process is asynchronous since
101 * socket connection information, such as hostname and IP address are
102 * resolved, so SilcAsyncOperation is returned which can be used to cancel
103 * the creation process. The `callback' will be called to return the
104 * created socket stream. To destroy the stream call silc_stream_destroy.
106 * If the `lookup' is TRUE then this will perform IP and hostname lookup
107 * for the socket. If the `require_fqdn' is TRUE then the socket must
108 * have valid hostname and IP address, otherwise the stream creation will
109 * fail. If it is FALSE then only valid IP address is required. Note that,
110 * if the `lookup' is FALSE then the hostname, IP and port information
111 * will not be available from the socket stream. In that case this will
112 * also return NULL as the `callback' is called immediately.
116 silc_socket_tcp_stream_create(int sock, SilcBool lookup,
117 SilcBool require_fqdn,
118 SilcSchedule schedule,
119 SilcSocketStreamCallback callback,
122 /****f* silcutil/SilcSocketStreamAPI/silc_socket_udp_stream_create
126 * SilcStream silc_socket_udp_stream_create(int sock, SilcBool ipv6,
127 * SilcSchedule schedule);
131 * Creates UDP socket stream of the UDP connection indicated by `sock'.
132 * The stream can be destroyed by calling the silc_stream_destroy.
134 * Note that, UDP packets may be read only through the notifier
135 * callback (see silc_stream_set_notifier), when SILC_STREAM_CAN_READ
136 * is returned to the callback. Because of this the notifier callback
139 * Note that, UDP packet sending using silc_stream_write and receiving
140 * with silc_stream_read works only if the `sock' is a UDP socket in a
141 * connected state. If it is not the silc_net_udp_send function and
142 * silc_net_udp_receive functions must be used. The SILC_STREAM_CAN_WRITE
143 * is never returned to the notifier callback.
145 * This function returns the created SilcStream or NULL on error.
148 SilcStream silc_socket_udp_stream_create(int sock, SilcBool ipv6,
149 SilcSchedule schedule);
151 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_info
156 * silc_socket_stream_get_info(SilcStream stream,
157 * int *sock, const char **hostname,
158 * const char **ip, SilcUInt16 *port);
162 * Returns socket stream information such as the socket number, hostname,
163 * IP address and the port of the remote socket connection. Return FALSE
164 * if these informations are not available.
167 SilcBool silc_socket_stream_get_info(SilcStream stream,
168 int *sock, const char **hostname,
169 const char **ip, SilcUInt16 *port);
171 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_info
176 * silc_socket_stream_set_info(SilcStream stream,
177 * const char *hostname,
178 * const char *ip, SilcUInt16 port);
182 * Use this function to set the hostname, IP address and remote port
183 * information to the socket stream indicated by `stream' if you did not
184 * perform lookup in the silc_socket_tcp_stream_create. This is not
185 * mandatory but if you would like to associate the information with the
186 * stream use this function. If the lookup was performed when creating
187 * the stream then calling this function is not necessary. Use the
188 * function silc_socket_stream_get_info to get the information from the
192 SilcBool silc_socket_stream_set_info(SilcStream stream,
193 const char *hostname,
194 const char *ip, SilcUInt16 port);
196 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_error
200 * int silc_socket_stream_get_error(SilcStream stream);
204 * If error occurred during socket stream operations, this function
205 * can be used to retrieve the error number that occurred.
208 int silc_socket_stream_get_error(SilcStream stream);
210 /****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_qos
214 * SilcBool silc_socket_stream_set_qos(SilcStream stream,
215 * SilcUInt32 read_rate,
216 * SilcUInt32 read_limit_bytes,
217 * SilcUInt32 limit_sec,
218 * SilcUInt32 limit_usec)
222 * Sets a "Quality of Service" settings for socket stream `stream'.
223 * The `read_rate' specifies the maximum read operations per second.
224 * If more read operations are executed the limit will be applied for
225 * the reading. The `read_limit_bytes' specifies the maximum data
226 * that is read. It is guaranteed that silc_stream_read never returns
227 * more than `read_limit_bytes' of data. The `limit_sec' and `limit_usec'
228 * specifies the time limit that is applied if `read_rate' and/or
229 * `read_limit_bytes' is reached. If all arguments except `stream'
230 * are zero this resets the QoS from the socket stream, all QoS for
231 * this socket stream that may be pending will be cancelled.
234 SilcBool silc_socket_stream_set_qos(SilcStream stream,
235 SilcUInt32 read_rate,
236 SilcUInt32 read_limit_bytes,
237 SilcUInt32 limit_sec,
238 SilcUInt32 limit_usec);
240 #include "silcsocketstream_i.h"
242 #endif /* SILCSOCKETSTREAM_H */