5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2005 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; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Net Interface
24 * SILC Net API provides various network routines for applications. It
25 * can be used to create TCP/IP connections and servers. Various utility
26 * functions for resolving various information is also provided.
28 * On WIN32 systems the SILC Net API must initialized by calling the
29 * silc_net_win32_init and uninitialized when the application ends by
30 * calling the silc_net_win32_uninit function. The initializing must be
31 * done in order to assure that the SILC Net API works correctly.
40 /****f* silcutil/SilcNetAPI/silc_net_create_server
44 * int silc_net_create_server(int port, char *ip_addr);
48 * This function creates server or daemon or listener or what ever. This
49 * does not fork a new process, it must be done by the caller if caller
50 * wants to create a child process. This is used by the SILC server.
51 * If argument `ip_addr' is NULL `any' address will be used. Returns
52 * the created socket or -1 on error.
55 int silc_net_create_server(int port, const char *ip_addr);
57 /****f* silcutil/SilcNetAPI/silc_net_close_server
61 * void silc_net_close_server(int sock);
65 * Closes the server by closing the socket connection.
68 void silc_net_close_server(int sock);
70 /****f* silcutil/SilcNetAPI/silc_net_create_connection
74 * int silc_net_create_connection(const char *local_ip, int port,
79 * Creates a connection (TCP/IP) to a remote host. Returns the connection
80 * socket or -1 on error. This blocks the process while trying to create
81 * the connection. If the `local_ip' is not NULL then this will bind
82 * the `local_ip' address to a port before creating the connection. If
83 * it is NULL then this will directly create the connection.
86 int silc_net_create_connection(const char *localhost, int port,
89 /****f* silcutil/SilcNetAPI/silc_net_create_connection_async
93 * int silc_net_create_connection_async(const char *local_ip, int port,
98 * Creates a connection (TCP/IP) to a remote host. Returns the connection
99 * socket or -1 on error. This creates non-blocking socket hence the
100 * connection returns directly. To get the result of the connect() one
101 * must select() the socket and read the result after it's ready. If the
102 * `local_ip' is not NULL then this will bind the `local_ip' address to
103 * a port before creating the connection. If it is NULL then this will
104 * directly create the connection.
107 int silc_net_create_connection_async(const char *local_ip, int port,
110 /****f* silcutil/SilcNetAPI/silc_net_close_connection
114 * void silc_net_close_connection(int sock);
118 * Closes the connection by closing the socket connection.
121 void silc_net_close_connection(int sock);
123 /****f* silcutil/SilcNetAPI/silc_net_accept_connection
127 * int silc_net_accept_connection(int sock);
131 * Accepts a connection from a particular socket.
134 int silc_net_accept_connection(int sock);
136 /****f* silcutil/SilcNetAPI/silc_net_set_socket_nonblock
140 * int silc_net_set_socket_nonblock(int sock);
144 * Sets the socket to non-blocking mode.
147 int silc_net_set_socket_nonblock(int sock);
149 /****f* silcutil/SilcNetAPI/silc_net_set_socket_opt
153 * int silc_net_set_socket_opt(int sock, int level, int option, int on);
157 * Sets a option for a socket. This function can be used to set
158 * various options for the socket. Some of the options might be
162 int silc_net_set_socket_opt(int sock, int level, int option, int on);
164 /****f* silcutil/SilcNetAPI/silc_net_get_socket_opt
168 * int silc_net_get_socket_opt(int sock, int level, int option,
169 * void *optval, int *opt_len);
173 * Return socket options to the `optval' and `opt_len'.
176 int silc_net_get_socket_opt(int sock, int level, int option,
177 void *optval, int *opt_len);
179 /****f* silcutil/SilcNetAPI/silc_net_is_ip4
183 * bool silc_net_is_ip4(const char *addr);
187 * Checks whether IP address sent as argument is valid IPv4 address.
190 bool silc_net_is_ip4(const char *addr);
192 /****f* silcutil/SilcNetAPI/silc_net_is_ip6
196 * bool silc_net_is_ip6(const char *addr);
200 * Checks whether IP address sent as argument is valid IPv6 address.
203 bool silc_net_is_ip6(const char *addr);
205 /****f* silcutil/SilcNetAPI/silc_net_is_ip
209 * bool silc_net_is_ip(const char *addr);
213 * Checks whether IP address sent as argument is valid IP address.
214 * This supports both IPv4 and IPv6 addresses.
217 bool silc_net_is_ip(const char *addr);
219 /****f* silcutil/SilcNetAPI/silc_net_addr2bin
223 * bool silc_net_addr2bin(const char *addr, void *bin, SilcUInt32 bin_len);
227 * Converts the IP number string from numbers-and-dots notation to
228 * binary form in network byte order. The address can be either
229 * IPv4 or IPv6 address.
232 bool silc_net_addr2bin(const char *addr, void *bin, SilcUInt32 bin_len);
234 /****f* silcutil/SilcNetAPI/SilcNetResolveCallback
238 * typedef void (*SilcNetResolveCallback)(const char *result,
243 * A callback function of this type is called after the asynchronous
244 * resolving operation has been completed. This callback is used
245 * when asynchronously resolving IP addresses and hostnames.
248 typedef void (*SilcNetResolveCallback)(const char *result, void *context);
250 /****f* silcutil/SilcNetAPI/silc_net_gethostbyname
254 * bool silc_net_gethostbyname(const char *name, bool prefer_ipv6,
255 * char *address, SilcUInt32 address_len);
259 * Resolves the IP address of the hostname indicated by the `name'.
260 * This returns TRUE and the IP address of the host to the `address'
261 * buffer, or FALSE if the address could not be resolved. This is
262 * synchronous function and will block the calling process. If the
263 * `prefer_ipv6' is TRUE then this will return IPv6 address if it
264 * finds. If FALSE if returns IPv4 address even if it found IPv6
268 bool silc_net_gethostbyname(const char *name, bool prefer_ipv6, char *address,
269 SilcUInt32 address_len);
271 /****f* silcutil/SilcNetAPI/silc_net_gethostbyname_async
275 * void silc_net_gethostbyname_async(const char *name,
277 * SilcSchedule schedule,
278 * SilcNetResolveCallback completion,
283 * Asynchronously resolves the IP address of the hostname indicated
284 * by the `name'. This function returns immediately, and the
285 * `completion' callback will be called after the resolving is
288 * If the `prefer_ipv6' is TRUE then this will return IPv6 address if it
289 * finds. If FALSE if returns IPv4 address even if it found IPv6
293 void silc_net_gethostbyname_async(const char *name,
295 SilcSchedule schedule,
296 SilcNetResolveCallback completion,
299 /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr
303 * bool silc_net_gethostbyaddr(const char *addr, char *name,
304 * SilcUInt32 name_len);
308 * Resolves the hostname for the IP address indicated by the `addr'
309 * This returns TRUE and the resolved hostname to the `name' buffer,
310 * or FALSE on error. The `addr' may be either IPv4 or IPv6 address.
311 * This is synchronous function and will block the calling process.
314 bool silc_net_gethostbyaddr(const char *addr, char *name, SilcUInt32 name_len);
316 /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr_async
320 * void silc_net_gethostbyaddr_async(const char *addr,
321 * SilcSchedule schedule,
322 * SilcNetResolveCallback completion,
327 * Asynchronously resolves the hostname for the IP address indicated
328 * by the `addr'. This function returns immediately, and the
329 * `completion' callback will be called after the resolving is
333 void silc_net_gethostbyaddr_async(const char *addr,
334 SilcSchedule schedule,
335 SilcNetResolveCallback completion,
338 /****f* silcutil/SilcNetAPI/silc_net_check_host_by_sock
342 * bool silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
346 * Performs lookups for remote name and IP address. This peforms reverse
347 * lookup as well to verify that the IP has FQDN.
350 bool silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
352 /****f* silcutil/SilcNetAPI/silc_net_check_local_by_sock
356 * bool silc_net_check_local_by_sock(int sock, char **hostname, char **ip);
360 * Performs lookups for local name and IP address. This peforms reverse
361 * lookup as well to verify that the IP has FQDN.
364 bool silc_net_check_local_by_sock(int sock, char **hostname, char **ip);
366 /****f* silcutil/SilcNetAPI/silc_net_get_remote_port
370 * SilcUInt16 silc_net_get_remote_port(int sock);
374 * Return remote port by socket.
377 SilcUInt16 silc_net_get_remote_port(int sock);
379 /****f* silcutil/SilcNetAPI/silc_net_get_local_port
383 * SilcUInt16 silc_net_get_local_port(int sock);
387 * Return local port by socket.
390 SilcUInt16 silc_net_get_local_port(int sock);
392 /****f* silcutil/SilcNetAPI/silc_net_localhost
396 * char *silc_net_localhost(void);
400 * Return name of localhost. This will also attempt to resolve
401 * the real hostname by the local host's IP address. If unsuccessful
402 * the first found hostname is returned. The caller must free
406 char *silc_net_localhost(void);
408 /****f* silcutil/SilcNetAPI/silc_net_localip
412 * char *silc_net_localip(void)
416 * Return IP of localhost. The caller must free the returned IP.
419 char *silc_net_localip(void);
421 /****f* silcutil/SilcNetAPI/silc_net_win32_init
425 * bool silc_net_win32_init(void);
429 * This is WIN32 system specific function and is used to initialize
430 * the network. This must be called by all WIN32 applications. It
431 * is usually called at the application's main() or WinMain() before
432 * calling any other SILC routine. The application must also call
433 * the silc_net_win32_uninit when exiting the application. Returns
434 * FALSE on error. The network will not work if this function returns
439 * This routines is available only on Win32 platform.
442 bool silc_net_win32_init(void);
444 /****f* silcutil/SilcNetAPI/silc_net_win32_uninit
448 * void silc_net_win32_init(void);
452 * This is WIN32 system specific function and is used to uninitialize
453 * the network. This must be called by all WIN32 applications. It
454 * is usually called when the application is exiting. After calling
455 * this function the SILC Net API routines will not work anymore.
459 * This routines is available only on Win32 platform.
462 void silc_net_win32_uninit(void);