]> for GNet &version; David Helder

dhelder@umich.edu

2000-2005 David Helder Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. This manual documents GNet, a network library. It gives an overview of GNet, discusses examples that come with GNet, and includes detailed documentation of the GNet API. GNet is a network library. It is written in C, object-oriented, and built upon GLib. It is intended to be easy to use and port. Features: TCP "client" and "server" sockets UDP and IP Multicast sockets High-level TCP connection and server objects Asynchronous socket IO HTTP client object Internet address abstraction Asynchronous DNS lookup IPv4 and IPv6 support Byte packing and unpacking URI parsing SHA and MD5 hashes Base64 encoding and decoding SOCKS support GNet is licensed under the GNU Lesser General Public License. Read COPYING for information on the license (this file comes with the GNet distribution). If you are a developer and you want to use GNet in your program, you can use the pkg-config script to figure out which flags need to set when compiling. For example, type gcc main.c `pkg-config gnet --cflags --libs` to compile the program main.c with GNet and link it to GNet. If you use autoconf and automake, you can the pkg-config macros to set the appropriate variables. Just add this to your configure.in: PKG_CHECK_MODULES(GNET, gnet > 2.0.0, [LIBS="$LIBS $GNET_LIBS" CFLAGS="$CFLAGS $GNET_CFLAGS"], AC_MSG_ERROR(Cannot find GNet: Is gnet-config in path?)) GNet was designed so that most of the implementation is hidden from the programmer. You should not have to include any network header files other than gnet.h. By convention, integers are usually transfered in big-endian, or network-byte, order. GLib has conversion functions for shorts and ints: g_ntohs (network-to-host short), g_htons (host-to network short), g_ntohl (network-to-host long), and g_htonl (host-to-network long). Many GNet functions block. That is, they do not return immediately. For example gnet_inetaddr_new performs a DNS lookup that may take several seconds. This is acceptable for many programs. But, it is not tolerable in interactive GUI programs or high-performance servers. There are two ways to hide blocking. The first is to use threads. Pthreads is a common thread library available on most systems. GLib 2.0 also includes thread support. The second method is to use asynchronous functions. Asynchronous functions return immediately and call a callback when the operation is completed. For example, gnet_inetaddr_new_async begins an asynchronous DNS lookup and returns immediately. When the lookup is complete, a callback is called with the GInetAddr. Most blocking function in GNet have an asynchronous counterpart. To use GNet's asynchronous functions, you must also use the GLib main event loop. Most GTK and Gnome program already do this. Another common blocking operation is reading or writing to a GIOChannel (a GLib object). g_io_channel_read blocks until there is data available to read. g_io_channel_write blocks until there is OS buffer space to write to. To determine when a GIOChannel can be read to or written from without blocking, use GLib's g_io_add_watch to set a watch. A callback is called when the GIOChannel becomes readable or writable. See the GLib documentation for more information and GNet's echoclient-async and echoserver-async for an example. GNet comes with several example programs. They are intended to be used by developers as examples of how to use GNet. The example programs are in the examples directory that comes with the source code. The tests in the tests directory also demonstrate to use several modules: MD5/SHA, InetAddr, IPv6, Pack/Unpack, and URI. The echoclient connects to the echoserver and sends data it reads in from the user. echoserver then sends it back and echoclient prints it out. These programs demonstrate how to write a basic client and server. There are three versions of the TCP echoclient and echoserver. Each demonstrates a different method of using GNet: blocking, asynchronous, and object GConn/GServer. There is also a blocking UDP example and a Unix sockets example. echoclient/echoserver. The blocking echoserver accepts a connection and reads and writes to the socket until the socket is closed. No more than one echoclient can be connected at once. A good, robust server wouldn't use this method, but it is suitable for many simple applications. echoclient-async/echoserver-async. The asynchronous server does not block while reading or writing to a socket or waiting for a connect. Since it's never blocked, it can accept new connections when it isn't reading or writing to another socket. The advantage of the this method is that multiple clients can be served at once. echoclient-gconn/echoserver-gserver. echoclient-gconn uses GNet's GConn object. echoserver-gserver uses GNet's GServer object. GConn and GServer are high-level wrappers around GTcpSocket. Using GConn and GServer is not as flexible as using GTcpSocket directly, but it is much easier and is flexible enough for most applications. There is no example using threads. If you would like to contribute one, please send it to us. dnslookup. dnslookup performs a DNS lookup of a hostname or a reverse DNS lookup of an address. It demonstrates how to use both the blocking and asynchronous methods of DNS lookups. hash. hash computes the MD5 and SHA hashes of a file. hfetch. hfetch is a simple HTTP file fetcher. hostinfo. hostinfo prints information about the host including it's domain name and interfaces. SDR. SDR prints multimedia session announcements. It demonstrates how to use multicast sockets in GNet. SDR will only work if your network supports IP Multicast. In fact, SDR is a good test for this. If the network supports multicast, SDR will print announcements after a few seconds, otherwise, it will print nothing. This section contains the API reference for gnet. All the public interfaces are documented here. This reference guide is built by extracting comments from the code sources. &gnet-gnet; &gnet-inetaddr; &gnet-tcp; &gnet-udp; &gnet-mcast; &gnet-conn-http; &gnet-conn; &gnet-server; &gnet-iochannel; &gnet-uri; &gnet-base64; &gnet-pack; &gnet-md5; &gnet-sha; &gnet-unix; &gnet-ipv6; &gnet-socks;