X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcsocketstream.h;h=e9fd435782959fd2e3298047571d4c2c77e9e3bb;hb=e9374395ec9747bddd3ea0bfd3e5a17717e97b31;hp=f135ca54755a618ad9dbab2386ebcfa9f90d0b3b;hpb=29befa9059ca8b9d2f0f1b415c6b99b34cdcb6fd;p=silc.git diff --git a/lib/silcutil/silcsocketstream.h b/lib/silcutil/silcsocketstream.h index f135ca54..e9fd4357 100644 --- a/lib/silcutil/silcsocketstream.h +++ b/lib/silcutil/silcsocketstream.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2005 - 2006 Pekka Riikonen + Copyright (C) 2005 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -71,11 +71,15 @@ typedef enum { * 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. + * + * If the silc_stream_set_notifier is called the stream will be set to + * non-blocking mode. * ***/ typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status, @@ -86,7 +90,7 @@ typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status, * SYNOPSIS * * 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, @@ -101,7 +105,7 @@ typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status, * socket connection information, such as hostname and IP address are * resolved, so SilcAsyncOperation is returned which can be used to cancel * the creation process. The `callback' will be called to return the - * created socket stream. To destroy the stream call silc_stream_destroy. + * created socket stream. * * 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 @@ -111,9 +115,12 @@ typedef void (*SilcSocketStreamCallback)(SilcSocketStreamStatus status, * will not be available from the socket stream. In that case this will * also return NULL as the `callback' is called immediately. * + * If the silc_stream_set_notifier is called the stream is set to + * non-blocking mode. + * ***/ 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, @@ -123,13 +130,17 @@ silc_socket_tcp_stream_create(int sock, SilcBool lookup, * * SYNOPSIS * - * SilcStream silc_socket_udp_stream_create(int sock, SilcBool ipv6, + * 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 @@ -138,34 +149,61 @@ silc_socket_tcp_stream_create(int sock, SilcBool lookup, * * 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. If it is not the silc_net_udp_send function and - * silc_net_udp_receive functions must be used. The SILC_STREAM_CAN_WRITE - * is never returned to the notifier callback. + * 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. * + * If the silc_stream_set_notifier is called the stream is set to + * non-blocking mode. + * ***/ -SilcStream silc_socket_udp_stream_create(int sock, SilcBool ipv6, +SilcStream silc_socket_udp_stream_create(SilcSocket sock, + SilcBool ipv6, + SilcBool connected, SilcSchedule schedule); +/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_is_udp + * + * 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 it will have 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 * * SYNOPSIS * * 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