libnet.txi

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

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename libnet.info
@settitle Libnet Documentation
@setchapternewpage odd
@c %**end of header


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

Copyright @copyright{} 1997-1999 Chad Catlett and George Foot

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


@titlepage

@title Libnet Documentation
@subtitle Edition 10 for Libnet 0.10.2
@author by George Foot

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1997-1999 Chad Catlett and George Foot

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

@end titlepage


@ifnottex
@node Top, Basic Aims, (dir), (dir)
@top 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 @file{readme.txt} before this.

All parts of Libnet are Copyright @copyright{} 1997-1999 Chad Catlett 
and George Foot.

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

@menu
* Basic Aims::                  Aims of this project
* Functions::                   List of functions with descriptions
* Drivers::                     Notes on Libnet's drivers
* Configuration::               How to use config files
* Structs::                     Notes on Libnet's structs
* Improvements::                Future improvements to the library
* Contacting the Authors::      How to contact the authors
* Mailing List::                Information about the netgame list

* Variable/macro Index::        
* Concept Index::               
@end menu


@c ----------------------------------------------------------------
@node Basic Aims, Functions, Top, Top
@chapter Basic Aims
@cindex aims of Libnet
@cindex basic aims of Libnet
@cindex goals of Libnet

Aims of this project:

@itemize @bullet

@item
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.

@item
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.

@item
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.

@item
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.

@end itemize


@c ----------------------------------------------------------------
@node Functions, Drivers, Basic Aims, Top
@chapter Functions
@cindex functions

The Libnet library functions fall into the following categories:

@menu
* Core Functions::              e.g. initialisation, configuration
* Channel Functions::           Functions to work with channels
* Connection Functions::        Functions to work with connections
* Driver List Functions::       For manipulating driver lists

* Alphabetic List of Functions::  
@end menu



@c ----------------------------------------------------------------
@node Core Functions, Channel Functions, Functions, Functions
@section Core Functions
@cindex core functions
@cindex functions, core

These functions interact with the core of the library.

@menu
* net_init::                    
* net_register_driver::         
* net_loadconfig::              
* net_getdrivernames::          
* net_detectdrivers::           
* net_initdrivers::             
* net_shutdown::                
@end menu


@c ----------------------------------------------------------------
@node net_init, net_register_driver, Core Functions, Core Functions
@subsection net_init
@findex net_init

@subsubheading Prototype

@example
int net_init (void);
@end example

@subsubheading Purpose

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

@subsubheading Return Value

This function returns 0 on success.

@c ----------------------------------------------------------------
@node net_register_driver, net_loadconfig, net_init, Core Functions
@subsection net_register_driver
@findex net_register_driver

@subsubheading Prototype

@example
int net_register_driver (int num, NET_DRIVER *driver);
@end example

@subsubheading 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 
@code{net_loadconfig} (@pxref{net_loadconfig}); otherwise they 
won't get an opportunity to read the config file.

@subsubheading Parameters

@var{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
@code{net_drivers_all} has the same number.  Values from 0 to 
@code{NET_DRIVER_USER - 1} inclusive are reserved for Libnet's 
use.  You can use values from @code{NET_DRIVER_USER} to 
@code{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).

@var{driver} is a pointer to the new driver's function table.

@subsubheading Return Value

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


@c ----------------------------------------------------------------
@node net_loadconfig, net_getdrivernames, net_register_driver, Core Functions
@subsection net_loadconfig
@findex net_loadconfig

@subsubheading Prototype

@example
int net_loadconfig (char *filename);
@end example

@subsubheading Purpose

This loads a configuration file and invites the various drivers 
to extract information from it.  @xref{Configuration}.

@subsubheading Parameters

@var{filename} can be @code{NULL}, a directory name, or a filename
(with or without an explicit directory).

If @var{filename} is @code{NULL} the file @file{libnet.cfg} is 
read from the program's home directory (as in @code{argv[0]}).  If 
@var{filename} is a directory then the file @file{libnet.cfg} 
is loaded from that directory.  If @var{filename} names a file,
that file is loaded.

@subsubheading Return Value

This function returns 0 on success.  Other return values:

@table @asis

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

@item 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 
@code{errno} and/or @code{perror} to find out why.

@end table

@subsubheading Example

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

@c ----------------------------------------------------------------
@node net_getdrivernames, net_detectdrivers, net_loadconfig, Core Functions
@subsection net_getdrivernames
@findex net_getdrivernames

@subsubheading Prototype

@example
NET_DRIVERNAME *net_getdrivernames (NET_DRIVERLIST which);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

The @var{which} parameter specifies which drivers to query.  The 
type @code{NET_DRIVERLIST} is defined in @file{libnet.h}.  You can 
either pass a list you created yourself using the driver list 
functions (@pxref{Driver List Functions}), or the list 
@code{net_drivers_all} which contains all the drivers.

@subsubheading Return value

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

@subsubheading Example

@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);
@end example

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


@c ----------------------------------------------------------------
@node net_detectdrivers, net_initdrivers, net_getdrivernames, Core Functions
@subsection net_detectdrivers
@findex net_detectdrivers

@subsubheading Prototype

@example
NET_DRIVERLIST net_detectdrivers (NET_DRIVERLIST which);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

@var{which} is a driver list, as for @code{net_getdrivernames} -- see
@ref{net_getdrivernames}, and also @ref{Driver List Functions}.  It
indicates which drivers to try to detect.  @code{net_drivers_all} 
can be given to detect all drivers.

@subsubheading 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 @var{which} were detected; it does 
not include drivers detected on previous calls.  This 
contrasts with the behaviour of @code{net_initdrivers} 
(@pxref{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.

@subsubheading Example

@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);
@end example 


@c ----------------------------------------------------------------
@node net_initdrivers, net_shutdown, net_detectdrivers, Core Functions
@subsection net_initdrivers
@findex net_initdrivers

@subsubheading Prototype

@example
NET_DRIVERLIST net_initdrivers (NET_DRIVERLIST which);
@end example

@subsubheading Purpose

This function operates similarly to the @code{net_detectdrivers}
function (@pxref{net_detectdrivers}), but it initialises the 
specified drivers rather than detecting them.

@subsubheading Parameters

@var{which} is a driver list as in @code{net_detectdrivers} 
(@pxref{net_detectdrivers}), indicating which drivers to attempt 
to initialise.  @code{net_drivers_all} can be given to initialise 
all drivers.  Drivers will not be initialised unless they were
detected in a previous call to @code{net_detectdrivers}.  Previously
initialised drivers will not be reinitialised.

@subsubheading Return value

The function returns a list in the same format as its 
argument, just as @code{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.

@subsubheading Example

@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);