silcnet.h
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2000 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; either version 2 of the License, or
- (at your option) any later version.
-
+ 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
*/
+/****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 */
-int silc_net_create_server(int port, char *ip_addr);
-void silc_net_close_server(int sock);
-int silc_net_create_connection(int port, char *host);
-int silc_net_create_connection_async(int port, char *host);
+
+/****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);
-int silc_net_is_ip(const char *addr);
-void silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
-uint16 silc_net_get_remote_port(int sock);
-uint16 silc_net_get_local_port(int sock);
-char *silc_net_localhost();
-#endif
+/****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 */
projects / silc.git / blobdiff