libnet.html

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

<p>Returns nonzero if data is waiting, zero if not.

<h4>Example</h4>

<pre>if (net_query (chan)) get_data(chan);
</pre>

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

<h2>2.3 Connection Functions</h2>

<p>Libnet's channels are unreliable -- there's no guarantee that
a packet will arrive at its destination, nor that packets won't
get duplicated en route, nor that packets will arrive in the
right order.  If you bear those facts in mind, channels should
be fine for most uses (in particular, cases where data is made
redundant very quickly by new incoming data).

<p>Sometimes though you want to be able to send a packet and be
sure that it will reach its destination.  Libnet's second type
of communicator is the <dfn>connection</dfn>.  A connection is a
fixed link between two computers.  You can't assign a new
target.  Packets sent along a connection are guaranteed to
arrive precisely once, and in the correct order.

<p>Conns are referred to through pointers to <code>NET_CONN</code> objects.

<ul>
<li><a href="#net_openconn">net_openconn</a>: 
<li><a href="#net_closeconn">net_closeconn</a>: 
<li><a href="#net_listen">net_listen</a>: 
<li><a href="#net_poll_listen">net_poll_listen</a>: 
<li><a href="#net_connect">net_connect</a>: 
<li><a href="#net_poll_connect">net_poll_connect</a>: 
<li><a href="#net_connect_wait_time">net_connect_wait_time</a>: 
<li><a href="#net_connect_wait_cb">net_connect_wait_cb</a>: 
<li><a href="#net_connect_wait_cb_time">net_connect_wait_cb_time</a>: 
<li><a href="#net_send_rdm">net_send_rdm</a>: 
<li><a href="#net_receive_rdm">net_receive_rdm</a>: 
<li><a href="#net_query_rdm">net_query_rdm</a>: 
<li><a href="#net_ignore_rdm">net_ignore_rdm</a>: 
<li><a href="#net_conn_stats">net_conn_stats</a>: 
<li><a href="#net_getpeer">net_getpeer</a>: 
</ul>

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

<h3>2.3.1 net_openconn</h3>

<h4>Prototype</h4>

<pre>NET_CONN *net_openconn (int type, char *binding);
</pre>

<h4>Purpose</h4>

<p>Opens a conn over the specified network type.

<h4>Parameters</h4>

<p><var>type</var> is the type of the network to use.  <var>binding</var> can
determine the local binding.  See <a href="#net_openchannel">net_openchannel</a>, for more
information about the binding.

<h4>Return value</h4>

<p>The function returns a pointer to the NET_CONN struct created, or
NULL on error.

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

<h3>2.3.2 net_closeconn</h3>

<h4>Prototype</h4>

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

<h4>Purpose</h4>

<p>Closes a previously opened conn.

<h4>Parameters</h4>

<p><var>conn</var> is the connection to be closed.

<h4>Return value</h4>

<p>Returns zero on success.

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

<h3>2.3.3 net_listen</h3>

<h4>Prototype</h4>

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

<h4>Purpose</h4>

<p>Makes a conn start listening (waiting for connection attempts).  Only
works on an idle conn.

<h4>Parameters</h4>

<p><var>conn</var> is the conn that should start listening.

<h4>Return value</h4>

<p>Returns zero on success, nonzero otherwise.

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

<h3>2.3.4 net_poll_listen</h3>

<h4>Prototype</h4>

<pre>NET_CONN *net_poll_listen (NET_CONN *conn);
</pre>

<h4>Purpose</h4>

<p>Polls a listening channel for incoming connections.  If
there are any, this function accepts the first one queued
and creates a new conn to talk to the connecting computer.

<h4>Parameters</h4>

<p><var>conn</var> is the (listening) conn to poll.

<h4>Return value</h4>

<p>If a new conn is created, this function returns a new
NET_CONN * which the user can use to talk to the connecting
computer.  Otherwise NULL is returned.

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

<h3>2.3.5 net_connect</h3>

<h4>Prototype</h4>

<pre>int net_connect (NET_CONN *conn, char *addr);
</pre>

<h4>Purpose</h4>

<p>Initiates a connection attempt.  See also: <a href="#net_connect_wait_time">net_connect_wait_time</a>,
<a href="#net_connect_wait_cb">net_connect_wait_cb</a>, <a href="#net_connect_wait_cb_time">net_connect_wait_cb_time</a>.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to connect; <var>addr</var> is the target address.

<h4>Return value</h4>

<p>Returns zero if successful in initiating; nonzero otherwise.  If
the return value is zero, the app should keep calling
<code>net_poll_connect</code> until a connection is established or
refused, or until the app gets bored.

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

<h3>2.3.6 net_poll_connect</h3>

<h4>Prototype</h4>

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

<h4>Purpose</h4>

<p>Polls a connecting conn to monitor connection progress.

<h4>Parameters</h4>

<p><var>conn</var> is the (connecting) conn to poll.

<h4>Return value</h4>

<p>Returns zero if the connection is still in progress, nonzero
if the connection process has ended.  A nonzero return value
is either positive (connection established) or negative
(connection not established).

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

<h3>2.3.7 net_connect_wait_time</h3>

<h4>Prototype</h4>

<pre>int net_connect_wait_time (NET_CONN *conn, char *addr, int time);
</pre>

<h4>Purpose</h4>

<p>This function uses <code>net_connect</code> and <code>net_poll_connect</code>
to establish a connection.  It waits until the connection process
is completed or the time runs out.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to connect with.  <var>addr</var> is the target
address.  <var>time</var> is the time in seconds to wait before giving up.

<h4>Return value</h4>

<p>Returns zero if the connection is established, negative if
there is an error (e.g. connection refused) and positive if
the time ran out.

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

<h3>2.3.8 net_connect_wait_cb</h3>

<h4>Prototype</h4>

<pre>int net_connect_wait_cb (NET_CONN *conn, char *addr, int (*cb)());
</pre>

<h4>Purpose</h4>

<p>This function uses <code>net_connect</code> and <code>net_poll_connect</code>
to establish a connection.  It waits, calling the callback function
regularly (once per second), until the connection process is completed
or the callback function returns nonzero.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to connect with.  <var>addr</var> is the target
address.  <var>cb</var> is the address of the callback function.

<h4>Return value</h4>

<p>Returns zero if the connection is established, negative if
there is an error (e.g. connection refused) and positive if
the callback function returned nonzero.

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

<h3>2.3.9 net_connect_wait_cb_time</h3>

<h4>Prototype</h4>

<pre>int net_connect_wait_cb_time (NET_CONN *conn, char *addr, int (*cb)(), int time)
</pre>

<h4>Purpose</h4>

<p>This function uses <code>net_connect</code> and <code>net_poll_connect</code>
to establish a connection.  It waits, calling the callback function
regularly (once per second), until the connection process is
completed, the time runs out, or the callback function returns
nonzero.

<p>Note that if the callback function is time consuming, the time limit
will be inaccurate.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to connect with.  <var>addr</var> is the target
address.  <var>cb</var> is the callback function and <var>time</var> is the
time in seconds to wait before giving up.

<h4>Return value</h4>

<p>Returns zero if the connection is established, negative if
there is an error (e.g. connection refused) and positive if
either the time ran out or the callback function returned
nonzero.

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

<h3>2.3.10 net_send_rdm</h3>

<h4>Prototype</h4>

<pre>int net_send_rdm (NET_CONN *conn, void *buffer, int size);
</pre>

<h4>Purpose</h4>

<p>Sends data down a conn.  Analogous to <a href="#net_send">net_send</a>.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to send the packet down, <var>buffer</var> points
to the data to send and <var>size</var> is the number of bytes to send.

<h4>Return value</h4>

<p>Returning zero to indicate success or non-zero if an error occurs.

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

<h3>2.3.11 net_receive_rdm</h3>

<h4>Prototype</h4>

<pre>int net_receive_rdm (NET_CONN *conn, void *buffer, int maxsize);
</pre>

<h4>Purpose</h4>

<p>Receives data from a conn.  Analogous to <a href="#net_receive">net_receive</a>.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to receive from.  <var>buffer</var> points
somewhere to store the packet, and <var>maxsize</var> is the maximum
number of bytes to store.

<h4>Return value</h4>

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

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

<h3>2.3.12 net_query_rdm</h3>

<h4>Prototype</h4>

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

<h4>Purpose</h4>

<p>Tests whether data can be read from a conn.  Analogous to
<a href="#net_query">net_query</a>, but this function actually returns the size
of the next queued packet.

<h4>Parameters</h4>

<p><var>conn</var> is the conn to test.

<h4>Return value</h4>

<p>The size of the next queued incoming packet, or 0 if no packets
are queued.

<pre>if (net_query_rdm (conn)) process_data(conn);
</pre>

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