5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2001 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; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
21 /****h* silcutil/SilcNetAPI
25 * SILC Net API provides various network routines for applications. It
26 * can be used to create TCP/IP connections and servers. Various utility
27 * functions for resolving various information is also provided.
29 * On WIN32 systems the SILC Net API must initialized by calling the
30 * silc_net_win32_init and uninitialized when the application ends by
31 * calling the silc_net_win32_uninit function. The initializing must be
32 * done in order to assure that the SILC Net API works correctly.
41 /****f* silcutil/SilcNetAPI/silc_net_create_server
45 * int silc_net_create_server(int port, char *ip_addr);
49 * This function creates server or daemon or listener or what ever. This
50 * does not fork a new process, it must be done by the caller if caller
51 * wants to create a child process. This is used by the SILC server.
52 * If argument `ip_addr' is NULL `any' address will be used. Returns
53 * the created socket or -1 on error.
56 int silc_net_create_server(int port, const char *ip_addr);
58 /****f* silcutil/SilcNetAPI/silc_net_close_server
62 * void silc_net_close_server(int sock);
66 * Closes the server by closing the socket connection.
69 void silc_net_close_server(int sock);
71 /****f* silcutil/SilcNetAPI/silc_net_create_connection
75 * int silc_net_create_connection(const char *local_ip, int port,
80 * Creates a connection (TCP/IP) to a remote host. Returns the connection
81 * socket or -1 on error. This blocks the process while trying to create
82 * the connection. If the `local_ip' is not NULL then this will bind
83 * the `local_ip' address to a port before creating the connection. If
84 * it is NULL then this will directly create the connection.
87 int silc_net_create_connection(const char *localhost, int port,
90 /****f* silcutil/SilcNetAPI/silc_net_create_connection_async
94 * int silc_net_create_connection_async(const char *local_ip, int port,
99 * Creates a connection (TCP/IP) to a remote host. Returns the connection
100 * socket or -1 on error. This creates non-blocking socket hence the
101 * connection returns directly. To get the result of the connect() one
102 * must select() the socket and read the result after it's ready. If the
103 * `local_ip' is not NULL then this will bind the `local_ip' address to
104 * a port before creating the connection. If it is NULL then this will
105 * directly create the connection.
108 int silc_net_create_connection_async(const char *local_ip, int port,
111 /****f* silcutil/SilcNetAPI/silc_net_close_connection
115 * void silc_net_close_connection(int sock);
119 * Closes the connection by closing the socket connection.
122 void silc_net_close_connection(int sock);
124 /****f* silcutil/SilcNetAPI/silc_net_accept_connection
128 * int silc_net_accept_connection(int sock);
132 * Accepts a connection from a particular socket.
135 int silc_net_accept_connection(int sock);
137 /****f* silcutil/SilcNetAPI/silc_net_set_socket_nonblock
141 * int silc_net_set_socket_nonblock(int sock);
145 * Sets the socket to non-blocking mode.
148 int silc_net_set_socket_nonblock(int sock);
150 /****f* silcutil/SilcNetAPI/silc_net_set_socket_opt
154 * int silc_net_set_socket_opt(int sock, int level, int option, int on);
158 * Sets a option for a socket. This function can be used to set
159 * various options for the socket. Some of the options might be
163 int silc_net_set_socket_opt(int sock, int level, int option, int on);
165 /****f* silcutil/SilcNetAPI/silc_net_get_socket_opt
169 * int silc_net_get_socket_opt(int sock, int level, int option,
170 * void *optval, int *opt_len);
174 * Return socket options to the `optval' and `opt_len'.
177 int silc_net_get_socket_opt(int sock, int level, int option,
178 void *optval, int *opt_len);
180 /****f* silcutil/SilcNetAPI/silc_net_is_ip4
184 * bool silc_net_is_ip4(const char *addr);
188 * Checks whether IP address sent as argument is valid IPv4 address.
191 bool silc_net_is_ip4(const char *addr);
193 /****f* silcutil/SilcNetAPI/silc_net_is_ip6
197 * bool silc_net_is_ip6(const char *addr);
201 * Checks whether IP address sent as argument is valid IPv6 address.
204 bool silc_net_is_ip6(const char *addr);
206 /****f* silcutil/SilcNetAPI/silc_net_is_ip
210 * bool silc_net_is_ip(const char *addr);
214 * Checks whether IP address sent as argument is valid IP address.
215 * This supports both IPv4 and IPv6 addresses.
218 bool silc_net_is_ip(const char *addr);
220 /****f* silcutil/SilcNetAPI/silc_net_addr2bin
224 * bool silc_net_addr2bin(const char *addr, void *bin, uint32 bin_len);
228 * Converts the IP number string from numbers-and-dots notation to
229 * binary form in network byte order. The address can be either
230 * IPv4 or IPv6 address.
233 bool silc_net_addr2bin(const char *addr, void *bin, uint32 bin_len);
235 /****f* silcutil/SilcNetAPI/silc_net_gethostbyname
239 * bool silc_net_gethostbyname(const char *name, char *address,
240 * uint32 address_len);
244 * Resolves the IP address of the hostname indicated by the `host'
245 * This returns TRUE and the IP address of the host, or FALSE
246 * if the address could not be resolved. This is synchronous
247 * function and will block the calling process.
250 bool silc_net_gethostbyname(const char *name, char *address,
253 /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr
257 * bool silc_net_gethostbyaddr(const char *addr, char *name,
262 * Resolves the hostname of the IP address indicated by the `addr'
263 * This returns TRUE and the resolved hostname, or FALSE on error.
264 * The `addr' may be either IPv4 or IPv6 address. This is
265 * synchronous function and will block the calling process.
268 bool silc_net_gethostbyaddr(const char *addr, char *name, uint32 name_len);
270 /****f* silcutil/SilcNetAPI/silc_net_check_host_by_sock
274 * bool silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
278 * Performs lookups for remote name and IP address. This peforms reverse
279 * lookup as well to verify that the IP has FQDN.
282 bool silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
284 /****f* silcutil/SilcNetAPI/silc_net_check_local_by_sock
288 * bool silc_net_check_local_by_sock(int sock, char **hostname, char **ip);
292 * Performs lookups for local name and IP address. This peforms reverse
293 * lookup as well to verify that the IP has FQDN.
296 bool silc_net_check_local_by_sock(int sock, char **hostname, char **ip);
298 /****f* silcutil/SilcNetAPI/silc_net_get_remote_port
302 * uint16 silc_net_get_remote_port(int sock);
306 * Return remote port by socket.
309 uint16 silc_net_get_remote_port(int sock);
311 /****f* silcutil/SilcNetAPI/silc_net_get_local_port
315 * uint16 silc_net_get_local_port(int sock);
319 * Return local port by socket.
322 uint16 silc_net_get_local_port(int sock);
324 /****f* silcutil/SilcNetAPI/silc_net_localhost
328 * char *silc_net_localhost(void);
332 * Return name of localhost. This will also attempt to resolve
333 * the real hostname by the local host's IP address. If unsuccessful
334 * the first found hostname is returned.
337 char *silc_net_localhost(void);
339 /****f* silcutil/SilcNetAPI/silc_net_localip
343 * char *silc_net_localip(void)
347 * Return IP of localhost.
350 char *silc_net_localip(void);
354 /****f* silcutil/SilcNetAPI/silc_net_win32_init
358 * bool silc_net_win32_init(void);
362 * This is WIN32 system specific function and is used to initialize
363 * the network. This must be called by all WIN32 applications. It
364 * is usually called at the application's main() or WinMain() before
365 * calling any other SILC routine. The application must also call
366 * the silc_net_win32_uninit when exiting the application. Returns
367 * FALSE on error. The network will not work if this function returns
371 bool silc_net_win32_init(void);
373 /****f* silcutil/SilcNetAPI/silc_net_win32_uninit
377 * void silc_net_win32_init(void);
381 * This is WIN32 system specific function and is used to uninitialize
382 * the network. This must be called by all WIN32 applications. It
383 * is usually called when the application is exiting. After calling
384 * this function the SILC Net API routines will not work anymore.
387 void silc_net_win32_uninit(void);