libnet.html

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

<ul compact>
<li><code>net_assigntarget</code>: <a href="#net_assigntarget">net_assigntarget</a>
<li><code>net_closechannel</code>: <a href="#net_closechannel">net_closechannel</a>
<li><code>net_closeconn</code>: <a href="#net_closeconn">net_closeconn</a>
<li><code>net_conn_stats</code>: <a href="#net_conn_stats">net_conn_stats</a>
<li><code>net_connect</code>: <a href="#net_connect">net_connect</a>
<li><code>net_connect_wait_cb</code>: <a href="#net_connect_wait_cb">net_connect_wait_cb</a>
<li><code>net_connect_wait_cb_time</code>: <a href="#net_connect_wait_cb_time">net_connect_wait_cb_time</a>
<li><code>net_connect_wait_time</code>: <a href="#net_connect_wait_time">net_connect_wait_time</a>
<li><code>net_detectdrivers</code>: <a href="#net_detectdrivers">net_detectdrivers</a>
<li><code>net_driverlist_add</code>: <a href="#net_driverlist_add">net_driverlist_add</a>
<li><code>net_driverlist_add_list</code>: <a href="#net_driverlist_add_list">net_driverlist_add_list</a>
<li><code>net_driverlist_clear</code>: <a href="#net_driverlist_clear">net_driverlist_clear</a>
<li><code>net_driverlist_count</code>: <a href="#net_driverlist_count">net_driverlist_count</a>
<li><code>net_driverlist_create</code>: <a href="#net_driverlist_create">net_driverlist_create</a>
<li><code>net_driverlist_destroy</code>: <a href="#net_driverlist_destroy">net_driverlist_destroy</a>
<li><code>net_driverlist_foreach</code>: <a href="#net_driverlist_foreach">net_driverlist_foreach</a>
<li><code>net_driverlist_remove</code>: <a href="#net_driverlist_remove">net_driverlist_remove</a>
<li><code>net_driverlist_remove_list</code>: <a href="#net_driverlist_remove_list">net_driverlist_remove_list</a>
<li><code>net_driverlist_test</code>: <a href="#net_driverlist_test">net_driverlist_test</a>
<li><code>net_getdrivernames</code>: <a href="#net_getdrivernames">net_getdrivernames</a>
<li><code>net_getlocaladdress</code>: <a href="#net_getlocaladdress">net_getlocaladdress</a>
<li><code>net_getpeer</code>: <a href="#net_getpeer">net_getpeer</a>
<li><code>net_ignore_rdm</code>: <a href="#net_ignore_rdm">net_ignore_rdm</a>
<li><code>net_init</code>: <a href="#net_init">net_init</a>
<li><code>net_initdrivers</code>: <a href="#net_initdrivers">net_initdrivers</a>
<li><code>net_listen</code>: <a href="#net_listen">net_listen</a>
<li><code>net_loadconfig</code>: <a href="#net_loadconfig">net_loadconfig</a>
<li><code>net_openchannel</code>: <a href="#net_openchannel">net_openchannel</a>
<li><code>net_openconn</code>: <a href="#net_openconn">net_openconn</a>
<li><code>net_poll_connect</code>: <a href="#net_poll_connect">net_poll_connect</a>
<li><code>net_poll_listen</code>: <a href="#net_poll_listen">net_poll_listen</a>
<li><code>net_query</code>: <a href="#net_query">net_query</a>
<li><code>net_query_rdm</code>: <a href="#net_query_rdm">net_query_rdm</a>
<li><code>net_receive</code>: <a href="#net_receive">net_receive</a>
<li><code>net_receive_rdm</code>: <a href="#net_receive_rdm">net_receive_rdm</a>
<li><code>net_register_driver</code>: <a href="#net_register_driver">net_register_driver</a>
<li><code>net_send</code>: <a href="#net_send">net_send</a>
<li><code>net_send_rdm</code>: <a href="#net_send_rdm">net_send_rdm</a>
<li><code>net_shutdown</code>: <a href="#net_shutdown">net_shutdown</a>
</ul>

<p><hr>
Node:<a name="Drivers">Drivers</a>,
Next:<a rel=next href="#Configuration">Configuration</a>,
Previous:<a rel=previous href="#Functions">Functions</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>3. Notes on Drivers in Libnet</h1>

<p>The drivers fall into the following categories:

<ul>
<li><a href="#nonet">nonet</a>:                        No networking
<li><a href="#template">template</a>:                     Template for custom drivers

<p>Internet drivers:  These communicate over the Internet using
UDP.

</p><li><a href="#socks">socks</a>:                        Berkeley sockets (Unix)
<li><a href="#wsockwin">wsockwin</a>:                     Winsock (Windows)
<li><a href="#wsockdos">wsockdos</a>:                     Winsock (DOS)

<p>IPX drivers:       These communicate over an IPX network.

</p><li><a href="#ipxdos">ipxdos</a>:                       DOS-based IPX

<p>Serial drivers:    These communicate through a serial link.

</p><li><a href="#serialdos">serialdos</a>:                    DOS-based Serial

<p>Local host driver: This driver lets a program talk to itself.

</p><li><a href="#localhost">localhost</a>:                    Local host

<p>Future drivers:    These haven't been written yet.

</p><li><a href="#Other%20drivers">Other drivers</a>:                PPP, serial, etc

</ul>

<p><hr>
Node:<a name="nonet">nonet</a>,
Next:<a rel=next href="#template">template</a>,
Previous:<a rel=previous href="#Drivers">Drivers</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.1 No networking</h2>

<dl>
<dt>Network type
<dd>No networking
<br><dt>Environment
<dd>Any
<br><dt>Code
<dd><code>NET_DRIVER_NONET</code>
<br><dt>Description
<dd>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</code>. 
<br><dt>Principal author
<dd>George Foot
</dl>

<p><hr>
Node:<a name="template">template</a>,
Next:<a rel=next href="#socks">socks</a>,
Previous:<a rel=previous href="#nonet">nonet</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.2 Template driver</h2>

<dl>
<dt>Network type
<dd>No networking
<br><dt>Environment
<dd>Any
<br><dt>Code
<dd>n/a
<br><dt>Description
<dd>This driver is very similar to the <code>nonet</code> driver.  It
exists to show implementors how to write new drivers.  See the
source code (<code>lib/drivers/template.c</code>), which is well
commented.  If anything is not clear, please contact me so that
I can correct the problem. 
<br><dt>Principal author
<dd>George Foot
</dl>

<p><hr>
Node:<a name="socks">socks</a>,
Next:<a rel=next href="#wsockwin">wsockwin</a>,
Previous:<a rel=previous href="#template">template</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.3 Berkeley sockets</h2>

<dl>
<dt>Network type
<dd>Internet
<br><dt>Environment
<dd>Unix
<br><dt>Code
<dd><code>NET_DRIVER_SOCKETS</code>
<br><dt>Description
<dd>This driver uses Berkeley sockets on Unix machines to access
the Internet.

<p>It has been tested at various times on Linux (i386), OSF1
(DEC Alpha) and FreeBSD. 
<br><dt>Principal author
<dd>George Foot
</dl>

<p><hr>
Node:<a name="wsockwin">wsockwin</a>,
Next:<a rel=next href="#wsockdos">wsockdos</a>,
Previous:<a rel=previous href="#socks">socks</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.4 Winsock from Windows</h2>

<dl>
<dt>Network type
<dd>Internet
<br><dt>Environment
<dd>Windows (native)
<br><dt>Code
<dd><code>NET_DRIVER_WSOCKWIN</code>
<br><dt>Description
<dd>This driver uses the Winsock from Windows to access
the Internet.

<p>It has been tested with RSXNTDJ+DJGPP and MSVC++. 
<br><dt>Principal author
<dd>George Foot
</dl>

<p><hr>
Node:<a name="wsockdos">wsockdos</a>,
Next:<a rel=next href="#ipxdos">ipxdos</a>,
Previous:<a rel=previous href="#wsockwin">wsockwin</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.5 Winsock from a DOS box</h2>

<dl>
<dt>Network type
<dd>Internet
<br><dt>Environment
<dd>DOS (under Windows)
<br><dt>Code
<dd><code>NET_DRIVER_WSOCK_DOS</code>
<br><dt>Description
<dd>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.

<p>It has been tested with DJGPP but this was some time ago (i.e. 
before the author used Windows 98). 
<br><dt>Principal author
<dd>George Foot
</dl>

<p><hr>
Node:<a name="ipxdos">ipxdos</a>,
Next:<a rel=next href="#serialdos">serialdos</a>,
Previous:<a rel=previous href="#wsockdos">wsockdos</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.6 IPX from DOS</h2>

<dl>
<dt>Network type
<dd>IPX
<br><dt>Environment
<dd>DOS
<br><dt>Code
<dd><code>NET_DRIVER_IPX_DOS</code>
<br><dt>Description
<dd>This driver uses BIOS level routines to access an IPX
network.

<p>It has been tested on DOS and a DOS box under Windows 95/98. 
<br><dt>Principal author
<dd>Ralph Deane
</dl>

<p><hr>
Node:<a name="serialdos">serialdos</a>,
Next:<a rel=next href="#localhost">localhost</a>,
Previous:<a rel=previous href="#ipxdos">ipxdos</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.7 Serial link from DOS</h2>

<dl>
<dt>Network type
<dd>Serial
<br><dt>Environment
<dd>DOS
<br><dt>Code
<dd><code>NET_DRIVER_SERIAL_DOS</code>
<br><dt>Description
<dd>This driver sends its data over serial ports. 
<br><dt>Principal author
<dd>Peter Wang
</dl>

<p><hr>
Node:<a name="localhost">localhost</a>,
Next:<a rel=next href="#Other%20drivers">Other drivers</a>,
Previous:<a rel=previous href="#serialdos">serialdos</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.8 Local host</h2>

<dl>
<dt>Network type
<dd>Local host (no real network)
<br><dt>Environment
<dd>All
<br><dt>Code
<dd><code>NET_DRIVER_LOCAL</code>
<br><dt>Description
<dd>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.

<p>It will work on all platforms. 
<br><dt>Principal author
<dd>Ralph Deane
</dl>

<p><hr>
Node:<a name="Other%20drivers">Other drivers</a>,
Previous:<a rel=previous href="#localhost">localhost</a>,
Up:<a rel=up href="#Drivers">Drivers</a>
<br>

<h2>3.9 Other drivers</h2>

<p>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.

<p>Any other useful drivers would be much appreciated. 
See <a href="#Contacting%20the%20Authors">Contacting the Authors</a>.

<p><hr>
Node:<a name="Configuration">Configuration</a>,
Next:<a rel=next href="#Structs">Structs</a>,
Previous:<a rel=previous href="#Drivers">Drivers</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>4. Config files</h1>

<p>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.

<p>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.

<ul>
<li>Config files are plain text files

<li>They are split into several sections

<li>Each section starts with a line containing only a title
in square brackets (<code>[</code>,<code>]</code>) and ends with the next such
title

<li>Inside the sections there may be several settings of the
form:  option = setting
</ul>

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

<p>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.

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

<p>To load a config file you use the <code>net_loadconfig</code> function,
<em>before calling <code>net_init</code></em>,
passing it one of:

<ol type=a start=1>
</p><li>a filename (with or without a path) to load
<li>a path with no filename
<li><code>NULL</code>
</ol>

<p>For [b] and [c] a default filename of <code>libnet.cfg</code> 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).

<p><hr>
Node:<a name="Structs">Structs</a>,
Next:<a rel=next href="#Improvements">Improvements</a>,
Previous:<a rel=previous href="#Configuration">Configuration</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>5. Notes on Libnet's structs</h1>

<p><code>libnet.h</code> declares several structs -- <code>NET_CHANNEL</code>,
<code>NET_CONN</code>,
<code>NET_DRIVER</code> and <code>NET_DRIVERNAME</code>. <code>NET_CHANNEL</code>
and <code>NET_CONN</code> 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</code> is used internally to hold information
about network drivers.  <code>NET_DRIVERNAME</code> is used to hold a
driver's reference number and name; an array of these is returned
by the <code>net_getdrivernames</code> function.

<p>The definitions of these structs are in <code>lib/include/internal.h</code>. 
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.

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

<p><hr>
Node:<a name="Improvements">Improvements</a>,
Next:<a rel=next href="#Contacting%20the%20Authors">Contacting the Authors</a>,
Previous:<a rel=previous href="#Structs">Structs</a>,
Up:<a rel=up href="#Top">Top</a>
<br>

<h1>6. Future improvements to the library</h1>

<p>Here are some possible enhancements for the future.  Other
suggestions for improvement are of course always
welcome.  See <a href="#Contacting%20the%20Authors">Contacting the Authors</a>.

<ul>
<li>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</code> struct if data is waiting.  The
user program could then issue one query call, and afterwards
just check this flag. 
</ul