libnet.html

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

<h3>2.3.13 net_ignore_rdm</h3>

<h4>Prototype</h4>

<pre>int net_ignore_rdm (NET_CONN *conn);
</pre>

<h4>Purpose</h4>

<p>If there are any incoming packets waiting to be read, this causes
the first to be dropped; otherwise nothing happens.  Note that the
sender isn't notified, and will have received a confirmation of the
packet's arrival.  This function is intended for use if a large
packet is in the queue and you weren't expecting to have to deal
with it; call this function to remove the packet.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to operate on.

<h4>Return value</h4>

<p>Non-zero if a packet was removed; zero if no packets were
queued, or if an error occured.

<pre>char buffer[1024];
int size = net_query_rdm (conn);
if (size &gt; 0) {                    /* got some data */
    if (size &gt; sizeof buffer)       /* too much data */
        net_ignore_rdm (conn);
    else {
        net_receive_rdm (conn, buffer, sizeof buffer);
        ...
    }
}
</pre>

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

<h3>2.3.14 net_conn_stats</h3>

<h4>Prototype</h4>

<pre>int net_conn_stats (NET_CONN *conn, int *in_q, int *out_q);
</pre>

<h4>Purpose</h4>

<p>This function fills in <var>*in_q</var> and <var>*out_q</var> with the
numbers of packets in the incoming and outgoing queues for the
conn.  If either pointer is <code>NULL</code>, its will not be filled in.

<p>I'm not entirely sure how useful this information is; maybe somebody
can use it to optimise the way their game treats the network.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to test; <var>in_q</var> and <var>out_q</var> are
pointers to integers which, if not <code>NULL</code>, will be filled
with the lengths of the incoming and outgoing queues respectively.

<h4>Return value</h4>

<p>Zero on success.

<pre>int in_queue, out_queue;
net_conn_stats (conn, &amp;in_queue, &amp;out_queue);
</pre>

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

<h3>2.3.15 net_getpeer</h3>

<h4>Prototype</h4>

<pre>char *net_getpeer (NET_CONN *conn);
</pre>

<h4>Purpose</h4>

<p>This function gives the address of the peer of this conn,
i.e. the computer at the other end.  The conn must be in the
connected state (a return value from <code>net_poll_listen</code> or
passed to a successful <code>net_poll_connect</code>).

<h4>Parameters</h4>

<p><var>conn</var> is the conn whose address will be returned.

<h4>Return value</h4>

<p>A pointer to a static array is returned.  Do not write through
the pointer.  <code>NULL</code> is returned on error.

<pre>printf ("Connection received from %s\n", net_getpeer (conn));
</pre>

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

<h2>2.4 Driver List Functions</h2>

<p>These functions are provided to manipulate driver lists.

<ul>
<li><a href="#net_driverlist_create">net_driverlist_create</a>: 
<li><a href="#net_driverlist_destroy">net_driverlist_destroy</a>: 
<li><a href="#net_driverlist_clear">net_driverlist_clear</a>: 
<li><a href="#net_driverlist_add">net_driverlist_add</a>: 
<li><a href="#net_driverlist_remove">net_driverlist_remove</a>: 
<li><a href="#net_driverlist_add_list">net_driverlist_add_list</a>: 
<li><a href="#net_driverlist_remove_list">net_driverlist_remove_list</a>: 
<li><a href="#net_driverlist_test">net_driverlist_test</a>: 
<li><a href="#net_driverlist_foreach">net_driverlist_foreach</a>: 
<li><a href="#net_driverlist_count">net_driverlist_count</a>: 
</ul>

<p><hr>
Node:<a name="net_driverlist_create">net_driverlist_create</a>,
Next:<a rel=next href="#net_driverlist_destroy">net_driverlist_destroy</a>,
Previous:<a rel=previous href="#Driver%20List%20Functions">Driver List Functions</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.1 net_driverlist_create</h3>

<h4>Prototype</h4>

<pre>NET_DRIVERLIST net_driverlist_create (void);
</pre>

<h4>Purpose</h4>

<p>This function creates a new driver list.  Initially the driver list will
be cleared.

<h4>Return value</h4>

<p>This function returns a pointer to the <code>NET_DRIVERLIST</code> struct it
creates, or <code>NULL</code> on error (extremely unlikely).

<p><hr>
Node:<a name="net_driverlist_destroy">net_driverlist_destroy</a>,
Next:<a rel=next href="#net_driverlist_clear">net_driverlist_clear</a>,
Previous:<a rel=previous href="#net_driverlist_create">net_driverlist_create</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.2 net_driverlist_destroy</h3>

<h4>Prototype</h4>

<pre>void net_driverlist_destroy (NET_DRIVERLIST list);
</pre>

<h4>Purpose</h4>

<p>Frees the memory occupied by a driver list.

<h4>Parameters</h4>

<p><var>list</var> is the driver list to free.

<p><hr>
Node:<a name="net_driverlist_clear">net_driverlist_clear</a>,
Next:<a rel=next href="#net_driverlist_add">net_driverlist_add</a>,
Previous:<a rel=previous href="#net_driverlist_destroy">net_driverlist_destroy</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.3 net_driverlist_clear</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_clear (NET_DRIVERLIST list);
</pre>

<h4>Purpose</h4>

<p>This function clears a driver list.

<h4>Parameters</h4>

<p><var>list</var> is the driver list to clear.

<h4>Return value</h4>

<p>This function always returns 1.

<p><hr>
Node:<a name="net_driverlist_add">net_driverlist_add</a>,
Next:<a rel=next href="#net_driverlist_remove">net_driverlist_remove</a>,
Previous:<a rel=previous href="#net_driverlist_clear">net_driverlist_clear</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.4 net_driverlist_add</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_add (NET_DRIVERLIST list, int driver);
</pre>

<h4>Purpose</h4>

<p>This function adds a driver to a driver list.

<h4>Parameters</h4>

<p><var>driver</var> is one of the <code>NET_DRIVER_*</code> constants, and will be
added to the driver list <var>list</var>.

<h4>Return value</h4>

<p>This function always returns 1.

<p><hr>
Node:<a name="net_driverlist_remove">net_driverlist_remove</a>,
Next:<a rel=next href="#net_driverlist_add_list">net_driverlist_add_list</a>,
Previous:<a rel=previous href="#net_driverlist_add">net_driverlist_add</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.5 net_driverlist_remove</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_remove (NET_DRIVERLIST list, int driver);
</pre>

<h4>Purpose</h4>

<p>This function removes a driver from a driver list.

<h4>Parameters</h4>

<p><var>list</var> is the driver list from which the driver <var>driver</var> will be
removed.

<h4>Return value</h4>

<p>This function always returns 1.

<p><hr>
Node:<a name="net_driverlist_add_list">net_driverlist_add_list</a>,
Next:<a rel=next href="#net_driverlist_remove_list">net_driverlist_remove_list</a>,
Previous:<a rel=previous href="#net_driverlist_remove">net_driverlist_remove</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.6 net_driverlist_add_list</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_add_list (NET_DRIVERLIST list1, NET_DRIVERLIST list2);
</pre>

<h4>Purpose</h4>

<p>This function adds the contents of one driver list to another driver
list.

<h4>Parameters</h4>

<p>The contents of driver list <var>list2</var> will be added into the contents
of driver list <var>list1</var>.  <var>list1</var> will be modified in place.

<h4>Return value</h4>

<p>This function always returns 1.

<p><hr>
Node:<a name="net_driverlist_remove_list">net_driverlist_remove_list</a>,
Next:<a rel=next href="#net_driverlist_test">net_driverlist_test</a>,
Previous:<a rel=previous href="#net_driverlist_add_list">net_driverlist_add_list</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.7 net_driverlist_remove_list</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_remove_list (NET_DRIVERLIST list1, NET_DRIVERLIST list2);
</pre>

<h4>Purpose</h4>

<p>This function removes the contents of one driver list from another
driver list.

<h4>Parameters</h4>

<p>The contents of driver list <var>list2</var> will be removed from driver list
<var>list1</var>.  <var>list1</var> will be modified in place.

<h4>Return value</h4>

<p>This function always returns 1.

<p><hr>
Node:<a name="net_driverlist_test">net_driverlist_test</a>,
Next:<a rel=next href="#net_driverlist_foreach">net_driverlist_foreach</a>,
Previous:<a rel=previous href="#net_driverlist_remove_list">net_driverlist_remove_list</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.8 net_driverlist_test</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_test (NET_DRIVERLIST list, int driver);
</pre>

<h4>Purpose</h4>

<p>This function tests if a specific driver is contained in a driver list.

<h4>Parameters</h4>

<p><var>list</var> is the driver list in which to look for the driver
<var>driver</var>.

<h4>Return value</h4>

<p>Returns non-zero if <var>list</var> contains <var>driver</var>, otherwise returns
zero.

<p><hr>
Node:<a name="net_driverlist_foreach">net_driverlist_foreach</a>,
Next:<a rel=next href="#net_driverlist_count">net_driverlist_count</a>,
Previous:<a rel=previous href="#net_driverlist_test">net_driverlist_test</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.9 net_driverlist_foreach</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_foreach (NET_DRIVERLIST list,
	int (*func)(int driver, void *dat), void *dat);
</pre>

<h4>Purpose</h4>

<p>This function iterates through a driver list, calling a callback
function for each driver in the list.

<h4>Parameters</h4>

<p><var>list</var> is the driver list to iterate through.

<p><var>func</var> is the callback function that will be called for each driver
in <var>list</var>.  It will be passed two arguments: the driver and
<var>dat</var>.  It should return an integer.  If the integer is non-zero,
<code>net_driverlist_foreach</code> will stop iterating through the list.

<p><var>dat</var> is a parameter which you can use to pass any data you want to
the callback function.

<h4>Return value</h4>

<p>Returns zero if iteration was terminated by the callback function,
otherwise returns non-zero.

<h4>Notes</h4>

<p>Note that Libnet driver lists do not preserve the order in which you add
or remove drivers.  Currently, <code>net_driverlist_foreach</code> iterates
from the driver with the smallest id number to the largest.  However,
this, and the assignment of id numbers, may change in future, so you
should not rely on any particular ordering.

<p><hr>
Node:<a name="net_driverlist_count">net_driverlist_count</a>,
Previous:<a rel=previous href="#net_driverlist_foreach">net_driverlist_foreach</a>,
Up:<a rel=up href="#Driver%20List%20Functions">Driver List Functions</a>
<br>

<h3>2.4.10 net_driverlist_count</h3>

<h4>Prototype</h4>

<pre>int net_driverlist_count (NET_DRIVERLIST list);
</pre>

<h4>Purpose</h4>

<p>Counts the number of drivers in a driver list.

<h4>Parameters</h4>

<p><var>list</var> is the driver list to count.

<h4>Return value</h4>

<p>The number of drivers in <var>list</var>.

<p><hr>
Node:<a name="Alphabetic%20List%20of%20Functions">Alphabetic List of Functions</a>,
Previous:<a rel=previous href="#Driver%20List%20Functions">Driver List Functions</a>,
Up:<a rel=up href="#Functions">Functions</a>
<br>

<h2>2.5 Alphabetic List of Functions</h2>

<p>This is an alphabetic list of all the interface functions of Libnet.