ANTINAT
Section: Antinat Programmer's Manual (3)Updated: 2005-01-05
Index Return to Main Contents
NAME
antinat - Use proxy-aware networking
DESCRIPTION
Antinat provides a library replacement for the BSD-socket library. This new API has the advantages of being simpler, but more importantly, proxy-aware. Many other products implement BSD-compatible libraries that are capable of using proxies; antinat does not attempt to remain source compatible with BSD sockets. This means that applications can support proxy features that would not be available in a transparent library; server-side name resolution and authentication are two classic examples.
In order to use this library in your applications, remember to #include <antinat.h> in your application source files. The interfaces are designed to be compatible with many languages, however, non-C/C++ bindings have not yet been produced. When linking your application, link against antinat library on your platform. Typically, functions follow a generalised order of use:
1. Create a new proxy-aware socket handle with an_new_connection(3).
2. Change socket characteristics to be those desired, using an_clear_authschemes(3), an_set_authscheme(3), an_set_credentials(3), an_set_proxy(3), an_set_proxy_url(3) and/or an_unset_proxy(3).
3. Engage with the remote host in the desired way, using an_bind_tohostname(3), an_bind_tosockaddr(3), an_connect_tohostname(3), or an_connect_tosockaddr(3).
4. If the operation was a bind, follow up with an_getsockname(3), an_listen(3) and an_accept(3).
5. Having been connected, communicate with the remote host using an_recv(3) and/or an_send(3). If there are multiple connections in a single thread, determine which of these need attention with a standard select call; use AN_FD_CLR(3), AN_FD_ISSET(3), and/or AN_FD_SET(3) to manipulate the lists which select requires.
6. When the connection is no longer required, it can be terminated using an_close(3). At this point, the connection handle can be re-used, by proceeding from step 2. onwards; all settings done previously in step 2. will be preserved.
7. When there is no further use for the connection handle, destroy it using an_destroy(3).
Most of the Antinat functions give Antinat-style error returns. These can be converted to human text using the an_geterror(3) function. Manual pages often provide more detailed information about what may have caused each error in the context in which it was used.
If no proxy information is set by the application using these APIs, the default proxy information can be found in the AN_PROXY, AN_USERand AN_PASS environment variables.
Although applications should avoid performing name-resolution, and leave this to the proxy wherever possible, where this is unavoidable applications should call an_gethostbyname(3). This function has the advantage of being threadsafe, even where no underlying threadsafe implementation exists. Take great care, however, if your platform does not support a threadsafe gethostbyname; all calls to gethostbyname in your application, including dependent libraries, must use an_gethostbyname or potential race conditions will exist.
SEE ALSO
an_accept(3), an_bind_tohostname(3), an_bind_tosockaddr(3), an_clear_authschemes(3), an_close(3), an_connect_tohostname(3), an_connect_tosockaddr(3), an_destroy(3), an_geterror(3), an_gethostbyname(3), an_getpeername(3), an_getsockname(3), an_listen(3), an_new_connection(3), an_recv(3), an_send(3), an_set_authscheme(3), an_set_blocking(3), an_set_credentials(3), an_set_proxy(3), an_set_proxy_url(3), an_unset_proxy(3)
AUTHOR
Malcolm Smith <[email protected]>
Index
Time: 14:19:44 GMT, January 09, 2005