libnet.html

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

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);
</pre>

<p><hr>
Node:<a name="net_shutdown">net_shutdown</a>,
Previous:<a rel=previous href="#net_initdrivers">net_initdrivers</a>,
Up:<a rel=up href="#Core%20Functions">Core Functions</a>
<br>

<h3>2.1.7 net_shutdown</h3>

<h4>Prototype</h4>

<pre>int net_shutdown (void);
</pre>

<h4>Purpose</h4>

<p>Shuts everything down nicely, closing any open channels and
shutting down all initialised drivers.  <code>net_init</code>
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.

<h4>Return value</h4>

<p>Returns 0 on success.

<p><hr>
Node:<a name="Channel%20Functions">Channel Functions</a>,
Next:<a rel=next href="#Connection%20Functions">Connection Functions</a>,
Previous:<a rel=previous href="#Core%20Functions">Core Functions</a>,
Up:<a rel=up href="#Functions">Functions</a>
<br>

<h2>2.2 Channel Functions</h2>

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

<p>Channels are referred to through pointers to <code>NET_CHANNEL</code>
objects.

<ul>
<li><a href="#net_openchannel">net_openchannel</a>: 
<li><a href="#net_closechannel">net_closechannel</a>: 
<li><a href="#net_assigntarget">net_assigntarget</a>: 
<li><a href="#net_getlocaladdress">net_getlocaladdress</a>: 
<li><a href="#net_send">net_send</a>: 
<li><a href="#net_receive">net_receive</a>: 
<li><a href="#net_query">net_query</a>: 
</ul>

<p><hr>
Node:<a name="net_openchannel">net_openchannel</a>,
Next:<a rel=next href="#net_closechannel">net_closechannel</a>,
Previous:<a rel=previous href="#Channel%20Functions">Channel Functions</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.1 net_openchannel</h3>

<h4>Prototype</h4>

<pre>NET_CHANNEL *net_openchannel(int type, char *binding);
</pre>

<h4>Purpose</h4>

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

<h4>Parameters</h4>

<p><var>type</var> is one of the <code>NET_DRIVER_*</code> constants, for
example it could be one of the set bits returned by
<code>net_initdrivers</code>, or the <code>num</code> entry for one of the
elements in a <code>NET_DRIVERNAME</code> array.

<p><var>binding</var> determines the local binding for the channel.  Pass
<code>NULL</code> 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.

<h4>Return value</h4>

<p>This function returns a pointer to the <code>NET_CHANNEL</code>
struct it creates, or <code>NULL</code> on error.

<h4>Compatibility with older versions</h4>

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

<dl>
<dt>net_openchannel (chan)
<dd>Change to <code>net_openchannel (chan, NULL)</code>
<br><dt>net_openinputchannel (chan)
<dd>Change to <code>net_openchannel (chan, "")</code>
</dl>

<h4>Notes</h4>

<p>The meaning of the <code>binding</code> 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.

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

<p>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
<code>binding = NULL</code>.

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

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

<p>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 <code>binding</code>.  He got the
default binding (i.e. "default" as username).

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

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

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

<p><hr>
Node:<a name="net_closechannel">net_closechannel</a>,
Next:<a rel=next href="#net_assigntarget">net_assigntarget</a>,
Previous:<a rel=previous href="#net_openchannel">net_openchannel</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.2 net_closechannel</h3>

<h4>Prototype</h4>

<pre>int net_closechannel(NET_CHANNEL *channel);
</pre>

<h4>Purpose</h4>

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

<h4>Parameters</h4>

<p><var>channel</var> is the channel to close.

<h4>Return value</h4>

<p>Returns 0 on success.

<h4>Example</h4>

<pre>NET_CHANNEL *chan = net_openchannel (driver, binding);
net_closechannel (chan);
</pre>

<p><hr>
Node:<a name="net_assigntarget">net_assigntarget</a>,
Next:<a rel=next href="#net_getlocaladdress">net_getlocaladdress</a>,
Previous:<a rel=previous href="#net_closechannel">net_closechannel</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.3 net_assigntarget</h3>

<h4>Prototype</h4>

<pre>int net_assigntarget(NET_CHANNEL *channel, char *target);
</pre>

<h4>Purpose</h4>

<p>Sets the target of the given channel.

<h4>Parameters</h4>

<p><var>channel</var> is the channel whose target address needs
changing.  <var>target</var> is the new target address.  The
format of the target address depends upon the network
type being used by the channel.

<h4>Return value</h4>

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

<h4>Example</h4>

<pre>NET_CHANNEL *chan = net_openchannel (NET_DRIVER_WSOCK, NULL);
net_assigntarget (chan, "127.0.0.1:12345");
</pre>

<p><hr>
Node:<a name="net_getlocaladdress">net_getlocaladdress</a>,
Next:<a rel=next href="#net_send">net_send</a>,
Previous:<a rel=previous href="#net_assigntarget">net_assigntarget</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.4 net_getlocaladdress</h3>

<h4>Prototype</h4>

<pre>char *net_getlocaladdress(NET_CHANNEL *channel);
</pre>

<h4>Purpose</h4>

<p>This function is used to discover the local address of a
channel.

<h4>Parameters</h4>

<p><var>channel</var> is the channel whose local address is wanted.

<h4>Return value</h4>

<p>The address of <var>channel</var> is returned in the driver's
normal address format.

<h4>Notes</h4>

<p><dfn>local address</dfn> means the address of the channel
according to this computer.  This might not be the
address other computers should use; for example, a
serial port driver would have no way of knowing what
port the other computer should use.  The Internet
sockets drivers have a bit of trouble with this too,
since a computer can have more than one IP address
and it's not trivial to find out even one of these.

<p>Because of all this, it's probably best to tell the
user this local address and let them figure out what
the other computer should use.

<h4>Example</h4>

<pre>NET_CHANNEL *chan;
chan = net_openchannel (driver, binding);
printf ("Local address of channel: %s\n", net_getlocaladdress (chan));
</pre>

<p><hr>
Node:<a name="net_send">net_send</a>,
Next:<a rel=next href="#net_receive">net_receive</a>,
Previous:<a rel=previous href="#net_getlocaladdress">net_getlocaladdress</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.5 net_send</h3>

<h4>Prototype</h4>

<pre>int net_send(CHANNEL *channel,void *buffer,int size);
</pre>

<h4>Purpose</h4>

<p>Sends data down a channel.

<h4>Parameters</h4>

<p><var>channel</var> is the channel to send the data through.  <var>buffer</var>
points to the data to send.  <var>size</var> is the size of the data in
bytes.

<h4>Return value</h4>

<p>Zero on success, non-zero on error.

<h4>Example</h4>

<p>See <a href="#net_receive">net_receive</a>.

<p><hr>
Node:<a name="net_receive">net_receive</a>,
Next:<a rel=next href="#net_query">net_query</a>,
Previous:<a rel=previous href="#net_send">net_send</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.6 net_receive</h3>

<h4>Prototype</h4>

<pre>int net_receive(CHANNEL *channel,void *buffer,int maxsize,char *from);
</pre>

<h4>Purpose</h4>

<p>Receives data from a channel.

<h4>Parameters</h4>

<p><var>channel</var> is the channel to receive from.  <var>buffer</var>
is a buffer to hold the data, of length <var>maxsize</var>.  If
<var>from</var> is not <code>NULL</code>, the address of the source of
the data will be stored in the buffer it points to (which
should be able to hold NET_MAX_ADDRESS_LENGTH characters).

<h4>Return value</h4>

<p>Returns the number of bytes received.  0 is valid; there
was no data to read.  -1 indicates that an error occured.

<h4>Example</h4>

<pre>NET_CHANNEL *chan;
char buffer1[32] = "Data to send";
char buffer2[32] = "";
int x;

chan = net_openchannel (NET_DRIVER_WSOCK, "");
net_assigntarget (chan, "127.0.0.1");

net_send (chan, buffer1, strlen (buffer1) + 1);

do {
   x = net_receive (chan, buffer2, 32, NULL);
} while (x == 0);

if (x &gt; 0)
   printf ("Received data: %s\n", buffer2);
else
   printf ("Error receiving data.\n");
</pre>

<p><hr>
Node:<a name="net_query">net_query</a>,
Previous:<a rel=previous href="#net_receive">net_receive</a>,
Up:<a rel=up href="#Channel%20Functions">Channel Functions</a>
<br>

<h3>2.2.7 net_query</h3>

<h4>Prototype</h4>

<pre>int net_query(CHANNEL *channel);
</pre>

<h4>Purpose</h4>

<p>This function checks to see if there is data waiting to be
read from the channel.

<h4>Parameters</h4>

<p><var>channel</var> is the channel to query.

<h4>Return value</h4>