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 /****s* silcutil/SilcNetAPI/SilcNetServer
44 * typedef struct SilcNetServerStruct *SilcNetServer;
48 * The network server (daemon, listener, etc.) context. This context
49 * is created with the silc_net_create_server function and destroyed
50 * with silc_net_close_server function.
53 typedef struct SilcNetServerStruct *SilcNetServer;
55 /****d* silcutil/SilcNetAPI/SilcNetStatus
59 * typedef enum { ... } SilcNetStatus;
63 * Status to indicate the result of the network operation creation. This
64 * type is returned in the SilcNetCallback callback function.
69 SILC_NET_OK, /* Everything Ok */
70 SILC_NET_UNKNOWN_IP, /* Unknown IP address */
71 SILC_NET_UNKNOWN_HOST, /* Unknown hostname */
72 SILC_NET_HOST_UNREACHABLE, /* Destination unreachable */
73 SILC_NET_CONNECTION_REFUSED, /* Connection refused */
74 SILC_NET_CONNECTION_TIMEOUT, /* Connection timedout */
75 SILC_NET_NO_MEMORY, /* System out of memory */
76 SILC_NET_ERROR, /* Unknown error */
80 /****f* silcutil/SilcNetAPI/SilcNetCallback
84 * typedef void (*SilcNetCallback)(SilcNetStatus status,
85 * SilcStream stream, void *context);
89 * A callback function of this type is returned by silc_net_create_server
90 * and silc_net_connect_async functions. For silc_net_create_server this
91 * callback means that new incoming connection was accepted, and the
92 * `stream' is the socket stream representing the socket connection.
94 * For silc_net_connect_async this means that we have connected to the
95 * remote host and the `stream' is the socket stream for the socket
96 * connection. The SILC Stream API (such as silc_stream_read, etc.)
97 * can be used to read and write to the stream. The created stream
98 * is socket stream so various SilcSocketStream API functions can be
99 * used with the `stream'.
102 typedef void (*SilcNetCallback)(SilcNetStatus status,
103 SilcStream stream, void *context);
105 /****f* silcutil/SilcNetAPI/silc_net_create_server
110 * silc_net_create_server(const char **local_ip_addr,
111 * SilcUInt32 local_ip_count,
112 * int port, SilcBool require_fqdn,
113 * SilcSchedule schedule,
114 * SilcNetCallback callback, void *context);
118 * This function creates server or daemon or listener etc. This is used
119 * to create network listener for incoming connections, and `callback'
120 * will be called everytime new connection is received. If `local_ip_addr'
121 * is NULL any address is used. If provided it can be used bind the
122 * server to `local_ip_count' many IP addresses provided in `local_ip_addr'
123 * table. On success returns the SilcNetServer context, or NULL on error.
124 * If `require_fqdn' is TRUE the server will require that the incoming
125 * connection has FQDN to be able to connect.
129 silc_net_create_server(const char **local_ip_addr, SilcUInt32 local_ip_count,
130 int port, SilcBool require_fqdn, SilcSchedule schedule,
131 SilcNetCallback callback, void *context);
133 /****f* silcutil/SilcNetAPI/silc_net_close_server
137 * void silc_net_close_server(SilcNetServer server);
141 * Closes the network server listener indicated by `server'.
144 void silc_net_close_server(SilcNetServer server);
146 /****f* silcutil/SilcNetAPI/silc_net_connect
150 * SilcAsyncOperation silc_net_tcp_connect(const char *local_ip_addr,
151 * const char *remote_ip_addr,
153 * SilcSchedule schedule,
154 * SilcNetCallback callback,
159 * Creates TCP/IP connection to the remote host indicated by `remote_host'
160 * which may be hostname or IP address, on the port indicated by
161 * `remote_port'. If the `local_ip_addr' is provided the local host is
162 * bound to that address before creating the connection. This is
163 * asynchronous call, and this function returns before the connection is
164 * actually established. The `callback' will be called after the
165 * connection is created to deliver the SilcStream for the created
168 * The returned SilcAsyncOperation context can be used to control the
169 * asynchronous connecting, such as to abort it. If it is aborted
170 * using silc_async_abort the `callback' will not be called. If NULL
171 * is returned the operation cannot be aborted and the `callback' will
172 * be called eventually.
175 SilcAsyncOperation silc_net_tcp_connect(const char *local_ip_addr,
176 const char *remote_ip_addr,
178 SilcSchedule schedule,
179 SilcNetCallback callback,
182 SilcAsyncOperation silc_net_udp_connect(const char *local_ip_addr,
183 const char *remote_ip_addr,
185 SilcSchedule schedule,
186 SilcNetCallback callback,
189 /****f* silcutil/SilcNetAPI/silc_net_close_connection
193 * void silc_net_close_connection(int sock);
197 * Closes the connection by closing the socket connection.
200 void silc_net_close_connection(int sock);
202 /****f* silcutil/SilcNetAPI/silc_net_accept_connection
206 * int silc_net_accept_connection(int sock);
210 * Accepts a connection from a particular socket.
213 int silc_net_accept_connection(int sock);
215 /****f* silcutil/SilcNetAPI/silc_net_set_socket_nonblock
219 * int silc_net_set_socket_nonblock(int sock);
223 * Sets the socket to non-blocking mode.
226 int silc_net_set_socket_nonblock(int sock);
228 /****f* silcutil/SilcNetAPI/silc_net_set_socket_opt
232 * int silc_net_set_socket_opt(int sock, int level, int option, int on);
236 * Sets a option for a socket. This function can be used to set
237 * various options for the socket. Some of the options might be
241 int silc_net_set_socket_opt(int sock, int level, int option, int on);
243 /****f* silcutil/SilcNetAPI/silc_net_get_socket_opt
247 * int silc_net_get_socket_opt(int sock, int level, int option,
248 * void *optval, int *opt_len);
252 * Return socket options to the `optval' and `opt_len'.
255 int silc_net_get_socket_opt(int sock, int level, int option,
256 void *optval, int *opt_len);
258 /****f* silcutil/SilcNetAPI/silc_net_is_ip4
262 * SilcBool silc_net_is_ip4(const char *addr);
266 * Checks whether IP address sent as argument is valid IPv4 address.
269 SilcBool silc_net_is_ip4(const char *addr);
271 /****f* silcutil/SilcNetAPI/silc_net_is_ip6
275 * SilcBool silc_net_is_ip6(const char *addr);
279 * Checks whether IP address sent as argument is valid IPv6 address.
282 SilcBool silc_net_is_ip6(const char *addr);
284 /****f* silcutil/SilcNetAPI/silc_net_is_ip
288 * SilcBool silc_net_is_ip(const char *addr);
292 * Checks whether IP address sent as argument is valid IP address.
293 * This supports both IPv4 and IPv6 addresses.
296 SilcBool silc_net_is_ip(const char *addr);
298 /****f* silcutil/SilcNetAPI/silc_net_addr2bin
302 * SilcBool silc_net_addr2bin(const char *addr, void *bin, SilcUInt32 bin_len);
306 * Converts the IP number string from numbers-and-dots notation to
307 * binary form in network byte order. The address can be either
308 * IPv4 or IPv6 address.
311 SilcBool silc_net_addr2bin(const char *addr, void *bin, SilcUInt32 bin_len);
313 /****f* silcutil/SilcNetAPI/SilcNetResolveCallback
317 * typedef void (*SilcNetResolveCallback)(const char *result,
322 * A callback function of this type is called after the asynchronous
323 * resolving operation has been completed. This callback is used
324 * when asynchronously resolving IP addresses and hostnames.
327 typedef void (*SilcNetResolveCallback)(const char *result, void *context);
329 /****f* silcutil/SilcNetAPI/silc_net_gethostbyname
333 * SilcBool silc_net_gethostbyname(const char *name, SilcBool prefer_ipv6,
334 * char *address, SilcUInt32 address_len);
338 * Resolves the IP address of the hostname indicated by the `name'.
339 * This returns TRUE and the IP address of the host to the `address'
340 * buffer, or FALSE if the address could not be resolved. This is
341 * synchronous function and will block the calling process. If the
342 * `prefer_ipv6' is TRUE then this will return IPv6 address if it
343 * finds. If FALSE if returns IPv4 address even if it found IPv6
347 SilcBool silc_net_gethostbyname(const char *name, SilcBool prefer_ipv6, char *address,
348 SilcUInt32 address_len);
350 /****f* silcutil/SilcNetAPI/silc_net_gethostbyname_async
354 * void silc_net_gethostbyname_async(const char *name,
355 * SilcBool prefer_ipv6,
356 * SilcSchedule schedule,
357 * SilcNetResolveCallback completion,
362 * Asynchronously resolves the IP address of the hostname indicated
363 * by the `name'. This function returns immediately, and the
364 * `completion' callback will be called after the resolving is
367 * If the `prefer_ipv6' is TRUE then this will return IPv6 address if it
368 * finds. If FALSE if returns IPv4 address even if it found IPv6
372 void silc_net_gethostbyname_async(const char *name,
373 SilcBool prefer_ipv6,
374 SilcSchedule schedule,
375 SilcNetResolveCallback completion,
378 /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr
382 * SilcBool silc_net_gethostbyaddr(const char *addr, char *name,
383 * SilcUInt32 name_len);
387 * Resolves the hostname for the IP address indicated by the `addr'
388 * This returns TRUE and the resolved hostname to the `name' buffer,
389 * or FALSE on error. The `addr' may be either IPv4 or IPv6 address.
390 * This is synchronous function and will block the calling process.
393 SilcBool silc_net_gethostbyaddr(const char *addr, char *name, SilcUInt32 name_len);
395 /****f* silcutil/SilcNetAPI/silc_net_gethostbyaddr_async
399 * void silc_net_gethostbyaddr_async(const char *addr,
400 * SilcSchedule schedule,
401 * SilcNetResolveCallback completion,
406 * Asynchronously resolves the hostname for the IP address indicated
407 * by the `addr'. This function returns immediately, and the
408 * `completion' callback will be called after the resolving is
412 void silc_net_gethostbyaddr_async(const char *addr,
413 SilcSchedule schedule,
414 SilcNetResolveCallback completion,
417 /****f* silcutil/SilcNetAPI/silc_net_check_host_by_sock
421 * SilcBool silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
425 * Performs lookups for remote name and IP address. This peforms reverse
426 * lookup as well to verify that the IP has FQDN.
429 SilcBool silc_net_check_host_by_sock(int sock, char **hostname, char **ip);
431 /****f* silcutil/SilcNetAPI/silc_net_check_local_by_sock
435 * SilcBool silc_net_check_local_by_sock(int sock, char **hostname, char **ip);
439 * Performs lookups for local name and IP address. This peforms reverse
440 * lookup as well to verify that the IP has FQDN.
443 SilcBool silc_net_check_local_by_sock(int sock, char **hostname, char **ip);
445 /****f* silcutil/SilcNetAPI/silc_net_get_remote_port
449 * SilcUInt16 silc_net_get_remote_port(int sock);
453 * Return remote port by socket.
456 SilcUInt16 silc_net_get_remote_port(int sock);
458 /****f* silcutil/SilcNetAPI/silc_net_get_local_port
462 * SilcUInt16 silc_net_get_local_port(int sock);
466 * Return local port by socket.
469 SilcUInt16 silc_net_get_local_port(int sock);
471 /****f* silcutil/SilcNetAPI/silc_net_localhost
475 * char *silc_net_localhost(void);
479 * Return name of localhost. This will also attempt to resolve
480 * the real hostname by the local host's IP address. If unsuccessful
481 * the first found hostname is returned. The caller must free
485 char *silc_net_localhost(void);
487 /****f* silcutil/SilcNetAPI/silc_net_localip
491 * char *silc_net_localip(void)
495 * Return IP of localhost. The caller must free the returned IP.
498 char *silc_net_localip(void);
500 /****f* silcutil/SilcNetAPI/silc_net_win32_init
504 * SilcBool silc_net_win32_init(void);
508 * This is WIN32 system specific function and is used to initialize
509 * the network. This must be called by all WIN32 applications. It
510 * is usually called at the application's main() or WinMain() before
511 * calling any other SILC routine. The application must also call
512 * the silc_net_win32_uninit when exiting the application. Returns
513 * FALSE on error. The network will not work if this function returns
518 * This routines is available only on Win32 platform.
521 SilcBool silc_net_win32_init(void);
523 /****f* silcutil/SilcNetAPI/silc_net_win32_uninit
527 * void silc_net_win32_init(void);
531 * This is WIN32 system specific function and is used to uninitialize
532 * the network. This must be called by all WIN32 applications. It
533 * is usually called when the application is exiting. After calling
534 * this function the SILC Net API routines will not work anymore.
538 * This routines is available only on Win32 platform.
541 void silc_net_win32_uninit(void);
543 #include "silcnet_i.h"
545 #endif /* SILCNET_H */