libnet.txt

Libnet is a cross-platform library aimed at game developers. It has an abstract high level API, whic

This is the Libnet Documentation, edition 10 for Libnet 0.10.2.

   Copyright (C) 1997-1999 Chad Catlett and George Foot

   Permission is granted to distribute this documentation
verbatim in any form. Please do not distribute modified copies.

Libnet documentation
********************

   This is the main documentation for Libnet.  Most of it is
relevant to end-users, but some of it is more relevant to
driver authors.  You should read the instructions in
`readme.txt' before this.

   All parts of Libnet are Copyright (C) 1997-1999 Chad Catlett
and George Foot.

   This is edition 10 of the Libnet documentation, consistent
with Libnet version 0.10.2.

1. Basic Aims
*************

   Aims of this project:

   * Make a generic interface to a variety of network drivers.

     Such an interface will enable people to write programs with
     networking capabilities without having to tie them down to
     particular types of network.  The same program code will be
     able to use any supported network (e.g. Winsock, IPX,
     serial, ...) neither becoming cluttered nor requiring much
     effort to adapt.

   * Offer basic functionality only.

     Restricting the functionality means that more classes of
     network can be implemented and makes it easy for new users
     to get used to.

   * Make addition of new drivers painless.

     Naturally, writing a new driver will require an amount of
     research and testing; however, adding new drivers to the
     library should not be a painful process.

   * Start with a core library, and a few sample drivers; invite
     other people to contribute new drivers.

     We can test whether the theory is workable, as well as
     creating sample programs to show people how to use the
     library.  Hopefully they will then contribute missing
     drivers.


2. Functions
************

   The Libnet library functions fall into the following
categories:

2.1 Core Functions
==================

   These functions interact with the core of the library.

2.1.1 net_init
--------------

Prototype
.........

     int net_init (void);

Purpose
.......

   This function initialises the library, and should be called
before any others.

Return Value
............

   This function returns 0 on success.

2.1.2 net_register_driver
-------------------------

Prototype
.........

     int net_register_driver (int num, NET_DRIVER *driver);

Purpose
.......

   This function is primarily used internally by Libnet to
register its own drivers, but it is a public function so you
can use it too if you want to register custom drivers.

   You should register any custom drivers before calling
`net_loadconfig' (see Subsec 2.1.3: net_loadconfig); otherwise
they won't get an opportunity to read the config file.

Parameters
..........

   NUM is a unique reference number.  Make sure it is unique!
You can check this by seeing whether or not a driver in the
driver list `net_drivers_all' has the same number.  Values from
0 to `NET_DRIVER_USER - 1' inclusive are reserved for Libnet's
use.  You can use values from `NET_DRIVER_USER' to
`NET_DRIVER_MAX - 1'.  If you specify 0, Libnet will allocate a
unique number on your behalf, out of its reserved range
(subject to availability).

   DRIVER is a pointer to the new driver's function table.

Return Value
............

   This function returns the number associated with your driver
on success, or 0 on failure.  (0 is a reserved driver number.)

2.1.3 net_loadconfig
--------------------

Prototype
.........

     int net_loadconfig (char *filename);

Purpose
.......

   This loads a configuration file and invites the various
drivers to extract information from it.  See Chapter 4:
Configuration.

Parameters
..........

   FILENAME can be `NULL', a directory name, or a filename
(with or without an explicit directory).

   If FILENAME is `NULL' the file `libnet.cfg' is read from the
program's home directory (as in `argv[0]').  If FILENAME is a
directory then the file `libnet.cfg' is loaded from that
directory.  If FILENAME names a file, that file is loaded.

Return Value
............

   This function returns 0 on success.  Other return values:

1
     The resulting filename (i.e. after mangling as above)
     could not be statted.  The `errno' variable should be set,
     so you can use `perror' or make comparisons yourself.

2
     The file could not be opened.  More than likely this is an
     access problem, but maybe you ran out of file handles.
     Again, use `errno' and/or `perror' to find out why.

Example
.......

     if (net_loadconfig(NULL)) {
        perror("Error loading config file");
        exit (1);
     }

2.1.4 net_getdrivernames
------------------------

Prototype
.........

     NET_DRIVERNAME *net_getdrivernames (NET_DRIVERLIST which);

Purpose
.......

   This function gets the names of some or all of the drivers.

Parameters
..........

   The WHICH parameter specifies which drivers to query.  The
type `NET_DRIVERLIST' is defined in `libnet.h'.  You can either
pass a list you created yourself using the driver list
functions (see Section 2.4: Driver List Functions), or the list
`net_drivers_all' which contains all the drivers.

Return value
............

   This function returns a pointer to an array of
`NET_DRIVERNAME' structs which contain the reference numbers
and names of the drivers specified by WHICH, plus the `nonet'
driver and a terminating entry with a `NULL' pointer for the
driver name.  This list is malloced, and should be freed by the
caller.

Example
.......

     NET_DRIVERNAME *names;
     int i;
     NET_DRIVERLIST drivers;
     
     /* Get names of all drivers */
     names = net_getdrivernames (net_drivers_all);
     
     /* Print all entries in the array */
     for (i = 0; names[i].name; i++)
        printf ("%d: %s\n", names[i].num, names[i].name);
     
     /* Free the array */
     free (names);
     
     /* Get names of the Unix sockets and the Winsock driver driver */
     /* So, first make a list containing them... */
     drivers = net_driverlist_create();                   /* creates empty list */
     net_driverlist_add (drivers, NET_DRIVER_SOCKS);      /* adds sockets driver */
     net_driverlist_add (drivers, NET_DRIVER_WSOCK_WIN);  /* adds Winsock driver */
     
     /* ... and then pass it to the function */
     names = net_getdrivernames (drivers);
     
     /* Print the names, as before, and free them */
     for (i = 0; names[i].name; i++)
        printf ("%d: %s\n", names[i].num, names[i].name);
     free (names);
     
     /* We don't need the driver list any more */
     net_driverlist_destroy (drivers);

   For more real-life examples please refer to the test programs
`tests/getdrvnm.c' and `tests/gentest.c', and the client-server
chat example in `examples/chat', where both `client.c' and
`server.c' use this function in a useful way.

2.1.5 net_detectdrivers
-----------------------

Prototype
.........

     NET_DRIVERLIST net_detectdrivers (NET_DRIVERLIST which);

Purpose
.......

   This function detects whether or not the given drivers can
be used.

Parameters
..........

   WHICH is a driver list, as for `net_getdrivernames' - see
Subsec 2.1.4: net_getdrivernames, and also Section 2.4: Driver
List Functions.  It indicates which drivers to try to detect.
`net_drivers_all' can be given to detect all drivers.

Return value
............

   The function returns a similar type showing which of the
specified drivers were actually detected.  Note that if you
call this function several times (e.g. once for each driver you
want to detect) its return value only shows which of the
drivers you specified in WHICH were detected; it does not
include drivers detected on previous calls.  This contrasts
with the behaviour of `net_initdrivers' (see Subsec 2.1.6:
net_initdrivers).

   Note that the return value is valid only until the next call
to this function (or until you shut down the library, of
course).  You don't need to destroy this list manually.

Example
.......

     NET_DRIVERLIST drivers;
     NET_DRIVERNAME *names;
     int i;
     
     drivers = net_detectdrivers (net_drivers_all);
     names = net_getdrivernames (drivers);
     for (i = 0; names[i].name; i++)
        printf ("%d: %s\n", names[i].num, names[i].name);
     free (names);

2.1.6 net_initdrivers
---------------------

Prototype
.........

     NET_DRIVERLIST net_initdrivers (NET_DRIVERLIST which);

Purpose
.......

   This function operates similarly to the `net_detectdrivers'
function (see Subsec 2.1.5: net_detectdrivers), but it
initialises the specified drivers rather than detecting them.

Parameters
..........

   WHICH is a driver list as in `net_detectdrivers' (see Subsec
2.1.5: net_detectdrivers), indicating which drivers to attempt
to initialise.  `net_drivers_all' can be given to initialise
all drivers.  Drivers will not be initialised unless they were
detected in a previous call to `net_detectdrivers'.  Previously
initialised drivers will not be reinitialised.

Return value
............

   The function returns a list in the same format as its
argument, just as `net_detectdrivers' does.  Note that it
returns the complete list of initialised (i.e. ready-for-use)
drivers, not just those you specified in the call.  Again, don't
destroy or modify this list.  It is valid until the next call to
this function only.

Example
.......

     NET_DRIVERNAME *names;
     NET_DRIVERLIST drivers, detected, initialised;
     int i;
     
     drivers = net_driverlist_create(); /* create the list for use later */
     names = net_getdrivernames (net_drivers_all);
     for (i = 0; names[i].name; i++) {
        printf ("%d: %s ", names[i].num, names[i].name);
        net_driverlist_clear (drivers);
        net_driverlist_add (drivers, names[i].num);
        detected = net_detectdrivers (drivers);
        if (net_driverlist_test (detected, names[i].num)) {
           printf ("(detected) ");
           initialised = net_initdrivers (drivers);
           if (net_driverlist_test (initialised, names[i].num))
              printf ("(initialised) ");
        }
        printf ("\n");
     }
     free (names);
     
     /* Destroy the `drivers' list, but not the other lists. */
     net_driverlist_destroy (drivers);

2.1.7 net_shutdown
------------------

Prototype
.........

     int net_shutdown (void);

Purpose
.......

   Shuts everything down nicely, closing any open channels and
shutting down all initialised drivers.  `net_init' installs an
exit function that calls this, so you don't normally need to
call it.  You do need to call it if for some reason you want to
reinitialise the library with a different driver set, maybe -
for example, if you need to reinitialise the drivers with a new
config file.

Return value
............

   Returns 0 on success.

2.2 Channel Functions
=====================

   These functions work with communication channels.  Whenever
you send or receive data, you do so through a channel.  Each
channel has an associated network type (which can't be changed
after the channel is created), a local address (which is
controlled by the driver) and a target address (which the user
can change at will).

   Channels are referred to through pointers to `NET_CHANNEL'
objects.

2.2.1 net_openchannel
---------------------

Prototype
.........

     NET_CHANNEL *net_openchannel(int type, char *binding);

Purpose
.......

   This function opens a communications channel for use over
the specified network type.

Parameters
..........

   TYPE is one of the `NET_DRIVER_*' constants, for example it
could be one of the set bits returned by `net_initdrivers', or
the `num' entry for one of the elements in a `NET_DRIVERNAME'
array.

   BINDING determines the local binding for the channel.  Pass
`NULL' if you don't care.  Otherwise, pass a string.  The empty
string always causes a default binding to be used; otherwise
the string's meaning depends upon the driver in use.

Return value
............

   This function returns a pointer to the `NET_CHANNEL' struct
it creates, or `NULL' on error.

Compatibility with older versions
.................................

   In Libnet versions before 0.9.13 this function did not have
the `binding' parameter, and there was another function,
`net_openinputchannel'.  To make that code work with the new
API you need to change calls to these two functions:

net_openchannel (chan)
     Change to `net_openchannel (chan, NULL)'

net_openinputchannel (chan)
     Change to `net_openchannel (chan, "")'

Notes
.....

   The meaning of the `binding' parameter may seem a bit misty.
As a general rule, if a channel is going to receive
first-contact data from other computers, you must specify its
binding.  If it's going to be used to send/receive data after
initial contact has been established then its binding doesn't
matter.

   As an analogy, let's consider a group of people who want to
communicate through email.  The people represent the computers
in your game.

   First imagine that none of the people know any of the email
addresses.  Obviously, nobody can communicate.  This represents
a situation where all channels were opened with `binding =
NULL'.

   Now suppose A knows B's email address.  Then A can
communicate with B in both directions, because as soon as A
sends B an email, B can look at the return address to discover
A's address.  This represents a situation where computer B
initialised a channel with a specific binding.  A's channel did
not need a specific binding, since he made first contact, not B.

   Now for a more accurate analogy.  Imagine each person has a
whole domain to themself, but nobody knows which users exist at
each domain.  So nobody can send messages; this is the first
scenario again.

   In the second scenario, A knows that B has a user called
"default".  So A can send email to that user from any of his
own users.  And then B can send email back to whichever of A's
users have already sent email to B, from any of his [B's]
users.  Again, only one of them needed to have a channel of
known binding.  This represents the situation where B
initialised a channel with the empty string as `binding'.  He
got the default binding (i.e. "default" as username).

   So why don't we initialise all channels with the default
binding?  Well, only one channel could then exist per computer
(actually per network type per computer).  You can't have two
users both called "default".

   Next consider the situation where B has two domains, one on
net1 and one on net2, while A has only one, on net1, and C has
only one, on net2.  Assume that A and B are communicating and B
and C are communicating; then B knows email addresses for A and
C.  Can A and C then communicate, if B tells them what each
other's addresses are?  No, because they're on different
networks.

   In this situation, B might want to explicitly bind channels
to networks net1 and net2, rather than letting the driver make a
(possibly) bad choice.  This is a reason why you might want to
let the user choose the binding.  B is a gateway here, and this
is a fairly unusual situation for a multiplayer game, but it can
be a useful feature.  An example of B is a machine on a LAN
(which runs Internet Protocol), with a modem connection to the
Internet itself.  A is out on the Internet and C is on the LAN.
In fact, the machine on which I am typing this is in this
situation.

2.2.2 net_closechannel
----------------------

Prototype
.........

     int net_closechannel(NET_CHANNEL *channel);

Purpose
.......

   Closes a previously opened channel. This will not
necessarily inform the remote machine; it will simply discard
the channel record, after inviting the network driver
responsible to tidy things up.

Parameters
..........

   CHANNEL is the channel to close.

Return value
............

   Returns 0 on success.

Example
.......

     NET_CHANNEL *chan = net_openchannel (driver, binding);
     net_closechannel (chan);

2.2.3 net_assigntarget
----------------------

Prototype
.........

     int net_assigntarget(NET_CHANNEL *channel, char *target);

Purpose
.......

   Sets the target of the given channel.

Parameters
..........

   CHANNEL is the channel whose target address needs changing.
TARGET is the new target address.  The format of the target
address depends upon the network type being used by the channel.

Return value
............

   Zero on success, nonzero on error (i.e. address in wrong
format).  A zero return does not indicate that the target can
necessarily be reached.

Example
.......

     NET_CHANNEL *chan = net_openchannel (NET_DRIVER_WSOCK, NULL);