libnet.txi

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

@cindex no networking (dummy) driver
@cindex dummy (no networking) driver
@cindex nonet driver
@vindex NET_DRIVER_NONET

@table @asis
@item Network type
No networking
@item Environment
Any
@item Code
@samp{NET_DRIVER_NONET}
@item Description
This driver will return success codes for everything, but
won't actually do anything.  It's a dummy driver, in case
no others are available.  Target and return addresses are
meaningless; send an empty string to @code{net_assigntarget}.
@item Principal author
George Foot
@end table

@c ----------------------------------------------------------------
@node template, socks, nonet, Drivers
@section Template driver
@cindex template driver
@cindex how to write a driver
@cindex writing your own drivers

@table @asis
@item Network type
No networking
@item Environment
Any
@item Code
n/a
@item Description
This driver is very similar to the @samp{nonet} driver.  It 
exists to show implementors how to write new drivers.  See the
source code (@file{lib/drivers/template.c}), which is well
commented.  If anything is not clear, please contact me so that
I can correct the problem.
@item Principal author
George Foot
@end table

@c ---------------------------------------------------------------
@node socks, wsockwin, template, Drivers
@section Berkeley sockets
@cindex Berkeley sockets (Unix Internet) driver
@cindex BSD sockets (Unix Internet) driver
@cindex Unix-based Internet (Berkeley sockets) driver
@cindex Linux-based Internet (Berkeley sockets) driver
@cindex FreeBSD-based Internet (Berkeley sockets) driver
@vindex NET_DRIVER_SOCKETS
@cindex Internet from Unix/Linux/FreeBSD
@cindex TCP/IP support in Unix/Linux/FreeBSD
@cindex UDP/IP support in Unix/Linux/FreeBSD
@cindex IP support in Unix/Linux/FreeBSD

@table @asis
@item Network type
Internet
@item Environment
Unix
@item Code
@samp{NET_DRIVER_SOCKETS}
@item Description
This driver uses Berkeley sockets on Unix machines to access 
the Internet.  

It has been tested at various times on Linux (i386), OSF1 
(DEC Alpha) and FreeBSD.
@item Principal author
George Foot
@end table


@c ---------------------------------------------------------------
@node wsockwin, wsockdos, socks, Drivers
@section Winsock from Windows
@cindex Winsock driver for Windows
@cindex Windows-based Winsock driver
@vindex NET_DRIVER_WSOCK_WIN
@cindex Internet from Windows
@cindex Windows-based Internet (Winsock) driver
@cindex TCP/IP support in Windows
@cindex UDP/IP support in Windows
@cindex IP support in Windows

@table @asis
@item Network type
Internet
@item Environment
Windows (native)
@item Code
@samp{NET_DRIVER_WSOCKWIN}
@item Description
This driver uses the Winsock from Windows to access 
the Internet.  

It has been tested with RSXNTDJ+DJGPP and MSVC++.
@item Principal author
George Foot
@end table


@c ---------------------------------------------------------------
@node wsockdos, ipxdos, wsockwin, Drivers
@section Winsock from a DOS box
@cindex Winsock driver for DOS
@cindex DOS-based Winsock driver
@vindex NET_DRIVER_WSOCK_DOS
@cindex Winsock 2 in DOS (lack of support)
@cindex Internet from a DOS box
@cindex DOS-based Internet (Winsock) driver
@cindex TCP/IP support in DOS boxes
@cindex UDP/IP support in DOS boxes
@cindex IP support in DOS boxes

@table @asis
@item Network type
Internet
@item Environment
DOS (under Windows)
@item Code
@samp{NET_DRIVER_WSOCK_DOS}
@item Description
This driver uses the Winsock from DOS to access 
the Internet.  It only works with version 1.x of Winsock ---
in particular it does not work with Winsock 2, as distributed
with Windows 98.  Obviously this only works from a DOS prompt
under Windows.

It has been tested with DJGPP but this was some time ago (i.e. 
before the author used Windows 98).
@item Principal author
George Foot
@end table


@c ----------------------------------------------------------
@node ipxdos, serialdos, wsockdos, Drivers
@section IPX from DOS
@cindex IPX driver
@vindex NET_DRIVER_IPX_DOS
@cindex Ethernet (IPX) driver
@cindex DOS-based IPX driver
@cindex LAN (IPX) driver

@table @asis
@item Network type
IPX
@item Environment
DOS
@item Code
@samp{NET_DRIVER_IPX_DOS}
@item Description
This driver uses BIOS level routines to access an IPX
network.

It has been tested on DOS and a DOS box under Windows 95/98.
@item Principal author
Ralph Deane
@end table


@c ----------------------------------------------------------
@node serialdos, localhost, ipxdos, Drivers
@section Serial link from DOS
@cindex serial driver
@cindex null modem driver
@cindex modem driver
@vindex NET_DRIVER_SERIAL_DOS
@cindex DOS-based serial driver

@table @asis
@item Network type
Serial
@item Environment
DOS
@item Code
@samp{NET_DRIVER_SERIAL_DOS}
@item Description
This driver sends its data over serial ports.
@item Principal author
Peter Wang
@end table


@c ----------------------------------------------------------
@node localhost, Other drivers, serialdos, Drivers
@section Local host 
@cindex local host driver
@cindex loopback (local host) driver
@cindex internal loopback (local host) driver
@vindex NET_DRIVER_LOCAL

@table @asis
@item Network type
Local host (no real network)
@item Environment
All
@item Code
@samp{NET_DRIVER_LOCAL}
@item Description
This driver provides a local network for the passing of data from
one part of a program to another. It is mostly used in a
server/client program to provide a network link to the local
client.

It will work on all platforms.
@item Principal author
Ralph Deane
@end table


@c ----------------------------------------------------------
@node Other drivers,  , localhost, Drivers
@section Other drivers
@cindex future drivers
@cindex other drivers
@cindex PPP driver
@cindex DOS-based Internet
@cindex Internet from plain DOS
@cindex Kali and Libnet

DOS-based Internet drivers via PPP and through network cards 
were once being worked on by Ove Kaaven.  Currently the only
way to play over the Internet from plain DOS using Libnet is
to run Kali, which emulates IPX over an Internet connection.
You still need to have Internet software for DOS.  Libnet's
IPX driver should be able to use this emulated IPX, but it
hasn't been tested yet.  If you try it, please let me (gfoot)
know how you get on.

Any other useful drivers would be much appreciated.
@xref{Contacting the Authors}.


@c ----------------------------------------------------------------
@node Configuration, Structs, Drivers, Top
@chapter Config files
@cindex config files
@cindex settings in config files

The library will work without config files by using hardwired
defaults, but if you want to use other settings config files
are what you need.

The system for config files was designed to allow other non-Libnet 
data to be included in the same file.  It uses a 
similar system to many other packages, like Windows' *.ini
files.

@itemize @bullet
@item
Config files are plain text files

@item
They are split into several sections

@item
Each section starts with a line containing only a title
in square brackets (@samp{[},@samp{]}) and ends with the next such
title

@item
Inside the sections there may be several settings of the
form:  option = setting
@end itemize

In fact what goes on inside the sections is entirely up to the
driver that owns the section; the above system is recommended
though.

Libnet drivers won't mind at all if you put garbage at the 
start or end of the file provided you don't duplicate any of
its section headings and the trailing garbage has a section
name separating it from the last Libnet driver.

For full details of what sections each driver looks for and
which settings within those sections it recognises please see
the drivers' documentation.

To load a config file you use the @code{net_loadconfig} function,
@emph{before calling @code{net_init}},
passing it one of:

@enumerate a
@item
a filename (with or without a path) to load
@item
a path with no filename
@item
@code{NULL}
@end enumerate

For [b] and [c] a default filename of @file{libnet.cfg} will be
used.  For [c] the file will be checked for in various platform-dependent
locations (e.g. the current directory, or the directory containing the
program, or the user's home directory).


@c ----------------------------------------------------------------
@node Structs, Improvements, Configuration, Top
@chapter Notes on Libnet's structs
@cindex structs
@cindex internals --- structs
@cindex NET_CHANNEL struct
@cindex NET_DRIVER struct
@cindex NET_CONN struct
@cindex NET_DRIVERNAME struct

@file{libnet.h} declares several structs --- @code{NET_CHANNEL}, 
@code{NET_CONN},
@code{NET_DRIVER} and @code{NET_DRIVERNAME}. @code{NET_CHANNEL} 
and @code{NET_CONN} are
used by user programs and internally to hold information about 
channels and conns; the user doesn't see inside the struct.  
@code{NET_DRIVER} is used internally to hold information 
about network drivers.  @code{NET_DRIVERNAME} is used to hold a 
driver's reference number and name; an array of these is returned 
by the @code{net_getdrivernames} function.

The definitions of these structs are in @file{lib/include/internal.h}.
Beware that these definitions may change from version to version;
it's best not to use them in user programs.  If you really need 
something and think the API should publicise it, let me (gfoot) know
and we can talk about extending the API.

The documentation about the structs has not yet been converted to
Texinfo format.


@c ----------------------------------------------------------------
@node Improvements, Contacting the Authors, Structs, Top
@chapter Future improvements to the library
@cindex improvements
@cindex future developments
@cindex plans for the future

Here are some possible enhancements for the future.  Other 
suggestions for improvement are of course always 
welcome.  @xref{Contacting the Authors}.

@itemize @bullet
@item
Rather than querying all channels one by one, there could
be a function to query them all at once, perhaps setting a
flag in the @code{NET_CHANNEL} struct if data is waiting.  The 
user program could then issue one query call, and afterwards
just check this flag.
@end itemize


@c ----------------------------------------------------------------
@node Contacting the Authors, Mailing List, Improvements, Top
@chapter Contacting the authors
@cindex contacting the authors
@cindex emailing the authors
@cindex authors
@cindex contributors

Authors' email addresses:

@itemize @bullet
@item
George Foot (gfoot):  george.foot@@merton.oxford.ac.uk
@item
Chad Catlett (dwi):  catlettc@@canvaslink.com
@item
Ralph Deane
@item
Peter Wang:  tjaden@@users.sourceforge.net
@end itemize

Before making queries about specific drivers, please look for 
documentation on the driver in question, e.g. in this document 
or in the `text' directory.  Also see the following chapter, 
which discusses the netgame mailing list.


@c ----------------------------------------------------------------
@node Mailing List, Variable/macro Index, Contacting the Authors, Top
@chapter The netgame mailing list
@cindex mailing list
@cindex netgame mailing list
@cindex subscribing to the netgame mailing list

The netgame mailing list was created in Spring 1998.  You can
discuss any aspect of networked game programming.  Libnet 
discussion is on topic, but the list is not just about 
Libnet.  The list does not generate a lot of traffic, but there 
are people on the list with experience writing games using Libnet
and other libraries, including the authors of Libnet, so asking 
this mailing list is better than asking the authors directly.

To subscribe to the mailing list, please send an email to 
listserv@@canvaslink.com with no subject, putting in the body
of the message:

@example
subscribe netgame name
@end example
@noindent

replacing @samp{name} with your name.  You'll be sent more 
information about the mailing list when your subscription is
processed.

The administrator of this mailing list is George Foot.









@node Variable/macro Index, Concept Index, Mailing List, Top
@unnumbered Variable/macro Index

@printindex vr

@node Concept Index,  , Variable/macro Index, Top
@unnumbered Concept Index

@printindex cp


@contents

@bye