* Implementation of SILC Socket Stream. SILC Socket Stream can be used
* read data from and write data to a socket connection. The SILC Socket
* Stream provides also Quality of Service (QoS) support that can be used
- * to control the throughput of the stream.
+ * to control the throughput of the stream. It also supports both TCP and
+ * UDP, and IPv4 and IPv6.
*
* SILC Socket Stream is not thread-safe. If the same socket stream must be
* used in multithreaded environment concurrency control must be employed.
* Callback function of this type is called after the socket stream
* creation is completed. If the `stream' is NULL the socket stream could
* not be created or the socket connection is not otherwise allowed. The
- * `status' will indicate the error status. The `stream' is socket stream
- * representing the socket connection and silc_socket_stream_* functions
- * can be used to access the stream. All other silc_stream_* functions
- * can also be used to read data, send data, and otherwise handle the
- * stream.
+ * `status' will indicate the error status. In case error ocurrs the
+ * associated socket has already been destroyed. The `stream' is socket
+ * stream representing the socket connection and silc_socket_stream_*
+ * functions can be used to access the stream. All other silc_stream_*
+ * functions can also be used to read data, send data, and otherwise
+ * handle the stream.
*
***/
typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status,
SilcStream stream, void *context);
-/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_create
+/****f* silcutil/SilcSocketStreamAPI/silc_socket_tcp_stream_create
*
* SYNOPSIS
*
* SilcAsyncOperation
- * silc_socket_stream_create(int sock, SilcBool lookup,
- * SilcBool require_fqdn,
- * SilcSchedule schedule,
- * SilcSocketStreamCallback callback,
- * void *context);
+ * silc_socket_tcp_stream_create(SilcSocket sock, SilcBool lookup,
+ * SilcBool require_fqdn,
+ * SilcSchedule schedule,
+ * SilcSocketStreamCallback callback,
+ * void *context);
*
* DESCRIPTION
*
- * Creates new socket stream of the socket connection indicated by `sock'.
+ * Creates TCP socket stream of the TCP connection indicated by `sock'.
* The stream can be destroyed by calling the silc_stream_destroy. Data
* can be sent and received from the stream by calling silc_stream_write
* and silc_stream_read. The creation process is asynchronous since
* the creation process. The `callback' will be called to return the
* created socket stream. To destroy the stream call silc_stream_destroy.
*
- * If the `lookup' is TRUE then this will performed IP and hostname lookup
+ * If the `lookup' is TRUE then this will perform IP and hostname lookup
* for the socket. If the `require_fqdn' is TRUE then the socket must
* have valid hostname and IP address, otherwise the stream creation will
* fail. If it is FALSE then only valid IP address is required. Note that,
* if the `lookup' is FALSE then the hostname, IP and port information
- * will not be available from the socket stream.
+ * will not be available from the socket stream. In that case this will
+ * also return NULL as the `callback' is called immediately.
*
***/
SilcAsyncOperation
-silc_socket_stream_create(int sock, SilcBool lookup,
- SilcBool require_fqdn,
- SilcSchedule schedule,
- SilcSocketStreamCallback callback,
- void *context);
-
-SilcAsyncOperation
-silc_socket_tcp_stream_create(int sock, SilcBool lookup,
+silc_socket_tcp_stream_create(SilcSocket sock, SilcBool lookup,
SilcBool require_fqdn,
SilcSchedule schedule,
SilcSocketStreamCallback callback,
void *context);
-SilcAsyncOperation
-silc_socket_udp_stream_create(int sock, SilcBool lookup,
- SilcBool require_fqdn,
- SilcSchedule schedule,
- SilcSocketStreamCallback callback,
- void *context);
+/****f* silcutil/SilcSocketStreamAPI/silc_socket_udp_stream_create
+ *
+ * SYNOPSIS
+ *
+ * SilcStream silc_socket_udp_stream_create(SilcSocket sock,
+ * SilcBool ipv6,
+ * SilcBool connected,
+ * SilcSchedule schedule);
+ *
+ * DESCRIPTION
+ *
+ * Creates UDP socket stream of the UDP connection indicated by `sock'.
+ * The stream can be destroyed by calling the silc_stream_destroy.
+ * The `connected' defines whether the socket is in connected or in
+ * connectionless state.
+ *
+ * Note that, UDP packets may be read only through the notifier
+ * callback (see silc_stream_set_notifier), when SILC_STREAM_CAN_READ
+ * is returned to the callback. Because of this the notifier callback
+ * must be set.
+ *
+ * Note that, UDP packet sending using silc_stream_write and receiving
+ * with silc_stream_read works only if the `sock' is a UDP socket in a
+ * connected state. In connectionless state sending packets with
+ * silc_stream_write is possible only if the remote address and port
+ * has been set with silc_socket_stream_set_info. If it is not set
+ * in connectionless state packets may be sent only by using the
+ * silc_net_udp_send function. In connectionless state packets may be
+ * received only by using silc_net_udp_receive.
+ *
+ * This function returns the created SilcStream or NULL on error.
+ *
+ ***/
+SilcStream silc_socket_udp_stream_create(SilcSocket sock,
+ SilcBool ipv6,
+ SilcBool connected,
+ SilcSchedule schedule);
+
+/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_info
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_socket_stream_is_udp(SilcStream stream,
+ * SilcBool *connected);
+ *
+ * DESCRIPTION
+ *
+ * Returns TRUE if the `stream' is UDP stream. If the `connected' pointer
+ * is non-NULL indication whether the UDP stream is in connected state.
+ * If it is then packets can be read and written using silc_stream_read
+ * and silc_stream_write. If it is not then packets need to read and
+ * written by using silc_net_udp_receive and silc_net_udp_send.
+ *
+ ***/
+SilcBool silc_socket_stream_is_udp(SilcStream stream, SilcBool *connected);
/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_info
*
*
* SilcBool
* silc_socket_stream_get_info(SilcStream stream,
- * int *sock, const char **hostname,
+ * SilcSocket *sock, const char **hostname,
* const char **ip, SilcUInt16 *port);
*
* DESCRIPTION
*
- * Returns socket stream information such as the socket number, hostname,
- * IP address and the port of the remote socket connection. Return FALSE
- * if these informations are not available.
+ * Returns socket stream information such as the socket, remote hostname,
+ * remote IP address and the remote port of the remote socket connection.
+ * Return FALSE if these informations are not available.
*
***/
SilcBool silc_socket_stream_get_info(SilcStream stream,
- int *sock, const char **hostname,
+ SilcSocket *sock, const char **hostname,
const char **ip, SilcUInt16 *port);
/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_set_info
*
* Use this function to set the hostname, IP address and remote port
* information to the socket stream indicated by `stream' if you did not
- * perform lookup in the silc_socket_create_stream. This is not mandatory
- * but if you would like to associate the information with the stream
- * use this function. If the lookup was performed when creating the
- * stream then calling this function is not necessary. Use the function
- * silc_socket_stream_get_info to get the information from the stream.
+ * perform lookup in the silc_socket_tcp_stream_create. This is not
+ * mandatory but if you would like to associate the information with the
+ * stream use this function. If the lookup was performed when creating
+ * the stream then calling this function is not necessary. Use the
+ * function silc_socket_stream_get_info to get the information from the
+ * stream.
*
***/
SilcBool silc_socket_stream_set_info(SilcStream stream,
projects / silc.git / blobdiff