/* silcnet.h Author: Pekka Riikonen Copyright (C) 1997 - 2005 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 the Free Software Foundation; version 2 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. */ /****h* silcutil/SILC Net Interface * * DESCRIPTION * * SILC Net API provides various network routines for applications. It * can be used to create TCP/IP connections and servers. Various utility * functions for resolving various information is also provided. * * On WIN32 systems the SILC Net API must initialized by calling the * silc_net_win32_init and uninitialized when the application ends by * calling the silc_net_win32_uninit function. The initializing must be * done in order to assure that the SILC Net API works correctly. * ***/ #ifndef SILCNET_H #define SILCNET_H /* Prototypes */ /****s* silcutil/SilcNetAPI/SilcNetServer * * NAME * * typedef struct SilcNetServerStruct *SilcNetServer; * * DESCRIPTION * * The network server (daemon, listener, etc.) context. This context * is created with the silc_net_create_server function and destroyed * with silc_net_close_server function. * ***/ typedef struct SilcNetServerStruct *SilcNetServer; /****d* silcutil/SilcNetAPI/SilcNetStatus * * NAME * * typedef enum { ... } SilcNetStatus; * * DESCRIPTION * * Status to indicate the result of the network operation creation. This * type is returned in the SilcNetCallback callback function. * * SOURCE */ typedef enum { SILC_NET_OK, /* Everything Ok */ SILC_NET_UNKNOWN_IP, /* Unknown IP address */ SILC_NET_UNKNOWN_HOST, /* Unknown hostname */ SILC_NET_HOST_UNREACHABLE, /* Destination unreachable */ SILC_NET_CONNECTION_REFUSED, /* Connection refused */ SILC_NET_CONNECTION_TIMEOUT, /* Connection timedout */ SILC_NET_NO_MEMORY, /* System out of memory */ SILC_NET_ERROR, /* Unknown error */ } SilcNetStatus; /***/ /****f* silcutil/SilcNetAPI/SilcNetCallback * * SYNOPSIS * * typedef void (*SilcNetCallback)(SilcNetStatus status, * SilcStream stream, void *context); * * DESCRIPTION * * A callback function of this type is returned by silc_net_create_server * and silc_net_connect_async functions. For silc_net_create_server this * callback means that new incoming connection was accepted, and the * `stream' is the socket stream representing the socket connection. * * For silc_net_connect_async this means that we have connected to the * remote host and the `stream' is the socket stream for the socket * connection. The SILC Stream API (such as silc_stream_read, etc.) * can be used to read and write to the stream. The created stream * is socket stream so various SilcSocketStream API functions can be * used with the `stream'. * ***/ typedef void (*SilcNetCallback)(SilcNetStatus status, SilcStream stream, void *context); /****f* silcutil/SilcNetAPI/silc_net_create_server * * SYNOPSIS * * SilcNetServer * silc_net_create_server(const char **local_ip_addr, * SilcUInt32 local_ip_count, * int port, bool require_fqdn, * SilcSchedule schedule, * SilcNetCallback callback, void *context); * * DESCRIPTION * * This function creates server or daemon or listener etc. This is used * to create network listener for incoming connections, and `callback' * will be called everytime new connection is received. If `local_ip_addr' * is NULL any address is used. If provided it can be used bind the * server to `local_ip_count' many IP addresses provided in `local_ip_addr' * table. On success returns the SilcNetServer context, or NULL on error. * If `require_fqdn' is TRUE the server will require that the incoming * connection has FQDN to be able to connect. * ***/ SilcNetServer silc_net_create_server(const char **local_ip_addr, SilcUInt32 local_ip_count, int port, bool require_fqdn, SilcSchedule schedule, SilcNetCallback callback, void *context); /****f* silcutil/SilcNetAPI/silc_net_close_server * * SYNOPSIS * * void silc_net_close_server(SilcNetServer server); * * DESCRIPTION * * Closes the network server listener indicated by `server'. * ***/ void silc_net_close_server(SilcNetServer server); /****f* silcutil/SilcNetAPI/silc_net_connect * * SYNOPSIS * * SilcAsyncOperation silc_net_tcp_connect(const char *local_ip_addr, * const char *remote_ip_addr, * int remote_port, * SilcSchedule schedule, * SilcNetCallback callback, * void *context); * * DESCRIPTION * * Creates TCP/IP connection to the remote host indicated by `remote_host' * which may be hostname or IP address, on the port indicated by * `remote_port'. If the `local_ip_addr' is provided the local host is * bound to that address before creating the connection. This is * asynchronous call, and this function returns before the connection is * actually established. The `callback' will be called after the * connection is created to deliver the SilcStream for the created * connection. * * The returned SilcAsyncOperation context can be used to control the * asynchronous connecting, such as to abort it. If it is aborted * using silc_async_abort the `callback' will not be called. If NULL * is returned the operation cannot be aborted and the `callback' will * be called eventually. * */ SilcAsyncOperation silc_net_tcp_connect(const char *local_ip_addr, const char *remote_ip_addr, int remote_port, SilcSchedule schedule, SilcNetCallback callback, void *context); SilcAsyncOperation silc_net_udp_connect(const char *local_ip_addr, const char *remote_ip_addr, int remote_port, SilcSchedule schedule, SilcNetCallback callback, void *context); /****f* silcutil/SilcNetAPI/silc_net_close_connection * * SYNOPSIS * * void silc_net_close_connection(int sock); * * DESCRIPTION * * Closes the connection by closing the socket connection. * ***/ void silc_net_close_connection(int sock); /****f* silcutil/SilcNetAPI/silc_net_accept_connection * * SYNOPSIS * * int silc_net_accept_connection(int sock); * * DESCRIPTION * * Accepts a connection from a particular socket. * ***/ int silc_net_accept_connection(int sock); /****f* silcutil/SilcNetAPI/silc_net_set_socket_nonblock * * SYNOPSIS * * int silc_net_set_socket_nonblock(int sock); * * DESCRIPTION * * Sets the socket to non-blocking mode. * ***/ int silc_net_set_socket_nonblock(int sock); /****f* silcutil/SilcNetAPI/silc_net_set_socket_opt * * SYNOPSIS * * int silc_net_set_socket_opt(int sock, int level, int option, int on); * * DESCRIPTION * * Sets a option for a socket. This function can be used to set * various options for the socket. Some of the options might be * system specific. * ***/ int silc_net_set_socket_opt(int sock, int level, int option, int on); /****f* silcutil/SilcNetAPI/silc_net_get_socket_opt * * SYNOPSIS * * int silc_net_get_socket_opt(int sock, int level, int option, * void *optval, int *opt_len); * * DESCRIPTION * * Return socket options to the `optval' and `opt_len'. * ***/ int silc_net_get_socket_opt(int sock, int level, int option, void *optval, int *opt_len); /****f* silcutil/SilcNetAPI/silc_net_is_ip4 * * SYNOPSIS * * bool silc_net_is_ip4(const char *addr); * * DESCRIPTION * * Checks whether IP address sent as argument is valid IPv4 address. * ***/ bool silc_net_is_ip4(const char *addr); /****f* silcutil/SilcNetAPI/silc_net_is_ip6 * * SYNOPSIS * * bool silc_net_is_ip6(const char *addr); * * DESCRIPTION * * Checks whether IP address sent as argument is valid IPv6 address. * ***/ bool silc_net_is_ip6(const char *addr); /****f* silcutil/SilcNetAPI/silc_net_is_ip * * SYNOPSIS * * bool silc_net_is_ip(const char *addr); * * DESCRIPTION * * Checks whether IP address sent as argument is valid IP address. * This supports both IPv4 and IPv6 addresses. * ***/ bool silc_net_is_ip(const char *addr); /****f* silcutil/SilcNetAPI/silc_net_addr2bin * * SYNOPSIS * * bool silc_net_addr2bin(const char *addr, void *bin, SilcUInt32 bin_len); * * DESCRIPTION * * Converts the IP number string from numbers-and-dots notation to * binary form in network byte order. The address can be either * IPv4 or IPv6 address. * ***/ bool silc_net_addr2bin(const char *addr, void *bin, SilcUInt32 bin_len); /****f* silcutil/SilcNetAPI/SilcNetResolveCallback * * SYNOPSIS * * typedef void (*SilcNetResolveCallback)(const char *result, * void *context); * * DESCRIPTION * * A callback function of this type is called after the asynchronous * resolving operation has been completed. This callback is used * when asynchronously resolving IP addresses and hostnames. * ***/ typedef void (*SilcNetResolveCallback)(const char *result, void *context); /****f* silcutil/SilcNetAPI/silc_net_gethostbyname * * SYNOPSIS * * bool silc_net_gethostbyname(const char *name, bool prefer_ipv6, * char *address, SilcUInt32 address_len); * * DESCRIPTION * * Resolves the IP address of the hostname indicated by the `name'. * This returns TRUE and the IP address of the host to the `address' * buffer, or FALSE if the address could not be resolved. This is * synchronous function and will block the calling process. If the * `prefer_ipv6' is TRUE then this will return IPv6 address if it * finds. If FALSE if returns IPv4 address even if it found IPv6 * address also. * ***/ bool silc_net_gethostbyname(const char *name, bool prefer_ipv6, char *address, SilcUInt32 address_len); /****f* silcutil/SilcNetAPI/silc_net_gethostbyname_async * * SYNOPSIS * * void silc_net_gethostbyname_async(const char *name, * bool prefer_ipv6, * SilcSchedule schedule, * SilcNetResolveCallback completion, * void *context) * * DESCRIPTION * * Asynchronously resolves the IP address of the hostname indicated * by the `name'. This function returns immediately, and the * `completion' callback will be called after the resolving is * completed. * * If the `prefer_ipv6' is TRUE then this will return IPv6 address if it * finds. If FALSE if returns IPv4 address even if it found IPv6 * address also. * ***/ void silc_net_gethostbyname_async(const char *name, bool prefer_ipv6, SilcSchedule schedule, SilcNetResolveCallback completion, void *context); /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr * * SYNOPSIS * * bool silc_net_gethostbyaddr(const char *addr, char *name, * SilcUInt32 name_len); * * DESCRIPTION * * Resolves the hostname for the IP address indicated by the `addr' * This returns TRUE and the resolved hostname to the `name' buffer, * or FALSE on error. The `addr' may be either IPv4 or IPv6 address. * This is synchronous function and will block the calling process. * ***/ bool silc_net_gethostbyaddr(const char *addr, char *name, SilcUInt32 name_len); /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr_async * * SYNOPSIS * * void silc_net_gethostbyaddr_async(const char *addr, * SilcSchedule schedule, * SilcNetResolveCallback completion, * void *context) * * DESCRIPTION * * Asynchronously resolves the hostname for the IP address indicated * by the `addr'. This function returns immediately, and the * `completion' callback will be called after the resolving is * completed. * ***/ void silc_net_gethostbyaddr_async(const char *addr, SilcSchedule schedule, SilcNetResolveCallback completion, void *context); /****f* silcutil/SilcNetAPI/silc_net_check_host_by_sock * * SYNOPSIS * * bool silc_net_check_host_by_sock(int sock, char **hostname, char **ip); * * DESCRIPTION * * Performs lookups for remote name and IP address. This peforms reverse * lookup as well to verify that the IP has FQDN. * ***/ bool silc_net_check_host_by_sock(int sock, char **hostname, char **ip); /****f* silcutil/SilcNetAPI/silc_net_check_local_by_sock * * SYNOPSIS * * bool silc_net_check_local_by_sock(int sock, char **hostname, char **ip); * * DESCRIPTION * * Performs lookups for local name and IP address. This peforms reverse * lookup as well to verify that the IP has FQDN. * ***/ bool silc_net_check_local_by_sock(int sock, char **hostname, char **ip); /****f* silcutil/SilcNetAPI/silc_net_get_remote_port * * SYNOPSIS * * SilcUInt16 silc_net_get_remote_port(int sock); * * DESCRIPTION * * Return remote port by socket. * ***/ SilcUInt16 silc_net_get_remote_port(int sock); /****f* silcutil/SilcNetAPI/silc_net_get_local_port * * SYNOPSIS * * SilcUInt16 silc_net_get_local_port(int sock); * * DESCRIPTION * * Return local port by socket. * ***/ SilcUInt16 silc_net_get_local_port(int sock); /****f* silcutil/SilcNetAPI/silc_net_localhost * * SYNOPSIS * * char *silc_net_localhost(void); * * DESCRIPTION * * Return name of localhost. This will also attempt to resolve * the real hostname by the local host's IP address. If unsuccessful * the first found hostname is returned. The caller must free * returned hostname. * ***/ char *silc_net_localhost(void); /****f* silcutil/SilcNetAPI/silc_net_localip * * SYNOPSIS * * char *silc_net_localip(void) * * DESCRIPTION * * Return IP of localhost. The caller must free the returned IP. * ***/ char *silc_net_localip(void); /****f* silcutil/SilcNetAPI/silc_net_win32_init * * SYNOPSIS * * bool silc_net_win32_init(void); * * DESCRIPTION * * This is WIN32 system specific function and is used to initialize * the network. This must be called by all WIN32 applications. It * is usually called at the application's main() or WinMain() before * calling any other SILC routine. The application must also call * the silc_net_win32_uninit when exiting the application. Returns * FALSE on error. The network will not work if this function returns * FALSE. * * NOTES * * This routines is available only on Win32 platform. * ***/ bool silc_net_win32_init(void); /****f* silcutil/SilcNetAPI/silc_net_win32_uninit * * SYNOPSIS * * void silc_net_win32_init(void); * * DESCRIPTION * * This is WIN32 system specific function and is used to uninitialize * the network. This must be called by all WIN32 applications. It * is usually called when the application is exiting. After calling * this function the SILC Net API routines will not work anymore. * * NOTES * * This routines is available only on Win32 platform. * ***/ void silc_net_win32_uninit(void); #include "silcnet_i.h" #endif /* SILCNET_H */