libnet.txi

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

Conns are referred to through pointers to @code{NET_CONN} objects.

@menu
* net_openconn::                
* net_closeconn::               
* net_listen::                  
* net_poll_listen::             
* net_connect::                 
* net_poll_connect::            
* net_connect_wait_time::       
* net_connect_wait_cb::         
* net_connect_wait_cb_time::    
* net_send_rdm::                
* net_receive_rdm::             
* net_query_rdm::               
* net_ignore_rdm::              
* net_conn_stats::              
* net_getpeer::                 
@end menu

@c ----------------------------------------------------------------
@node net_openconn, net_closeconn, Connection Functions, Connection Functions
@subsection net_openconn
@findex net_openconn
@cindex conn, opening
@cindex opening a conn
@cindex creating a conn
@cindex allocating a conn

@subsubheading Prototype

@example
NET_CONN *net_openconn (int type, char *binding);
@end example

@subsubheading Purpose

Opens a conn over the specified network type.

@subsubheading Parameters

@var{type} is the type of the network to use.  @var{binding} can 
determine the local binding.  @xref{net_openchannel}, for more 
information about the binding.

@subsubheading Return value

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

@c ----------------------------------------------------------------
@node net_closeconn, net_listen, net_openconn, Connection Functions
@subsection net_closeconn
@findex net_closeconn
@cindex conn, closing
@cindex closing a conn
@cindex destroying a conn
@cindex freeing a conn

@subsubheading Prototype

@example
int net_closeconn (NET_CONN *conn);
@end example

@subsubheading Purpose

Closes a previously opened conn.

@subsubheading Parameters

@var{conn} is the connection to be closed.

@subsubheading Return value

Returns zero on success.

@c ----------------------------------------------------------------
@node net_listen, net_poll_listen, net_closeconn, Connection Functions
@subsection net_listen
@findex net_listen
@cindex conn, listening
@cindex conn, starting to listen
@cindex listening conn, initiating
@cindex starting to listen for connections on a conn


@subsubheading Prototype

@example
int net_listen (NET_CONN *conn);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

@var{conn} is the conn that should start listening.

@subsubheading Return value

Returns zero on success, nonzero otherwise.

@c ----------------------------------------------------------------
@node net_poll_listen, net_connect, net_listen, Connection Functions
@subsection net_poll_listen
@findex net_poll_listen
@cindex conn, polling (listening) for connection attempts
@cindex polling a listening conn for connection status
@cindex listening conn, polling for status
@cindex checking whether a listening conn has been contacted

@subsubheading Prototype

@example
NET_CONN *net_poll_listen (NET_CONN *conn);
@end example

@subsubheading Purpose

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.

@subsubheading Parameters

@var{conn} is the (listening) conn to poll.

@subsubheading Return value

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.

@c ----------------------------------------------------------------
@node net_connect, net_poll_connect, net_poll_listen, Connection Functions
@subsection net_connect
@findex net_connect
@cindex conn, connecting
@cindex connecting conn, initiating
@cindex initiating a connection
@cindex starting a connection attempt
@cindex setting the target of a conn
@cindex assigning the target of a conn

@subsubheading Prototype

@example
int net_connect (NET_CONN *conn, char *addr);
@end example

@subsubheading Purpose

Initiates a connection attempt.  See also: @ref{net_connect_wait_time}, 
@ref{net_connect_wait_cb}, @ref{net_connect_wait_cb_time}.

@subsubheading Parameters

@var{conn} is the conn to connect; @var{addr} is the target address.

@subsubheading Return value

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

@c ----------------------------------------------------------------
@node net_poll_connect, net_connect_wait_time, net_connect, Connection Functions
@subsection net_poll_connect
@findex net_poll_connect
@cindex conn, polling connection status
@cindex polling a conn for connection status
@cindex connecting conn, polling for status
@cindex checking whether a connecting conn has connected yet

@subsubheading Prototype

@example
int net_poll_connect (NET_CONN *conn);
@end example

@subsubheading Purpose

Polls a connecting conn to monitor connection progress.

@subsubheading Parameters

@var{conn} is the (connecting) conn to poll.

@subsubheading Return value

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

@c ----------------------------------------------------------------
@node net_connect_wait_time, net_connect_wait_cb, net_poll_connect, Connection Functions
@subsection net_connect_wait_time
@findex net_connect_wait_time
@cindex conn, connecting with time limit
@cindex connecting a conn with time limit

@subsubheading Prototype

@example
int net_connect_wait_time (NET_CONN *conn, char *addr, int time);
@end example

@subsubheading Purpose

This function uses @code{net_connect} and @code{net_poll_connect}
to establish a connection.  It waits until the connection process
is completed or the time runs out.

@subsubheading Parameters

@var{conn} is the conn to connect with.  @var{addr} is the target 
address.  @var{time} is the time in seconds to wait before giving up.

@subsubheading Return value

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

@c ----------------------------------------------------------------
@node net_connect_wait_cb, net_connect_wait_cb_time, net_connect_wait_time, Connection Functions
@subsection net_connect_wait_cb
@findex net_connect_wait_cb
@cindex conn, connecting with callback
@cindex connecting a conn with callback

@subsubheading Prototype

@example
int net_connect_wait_cb (NET_CONN *conn, char *addr, int (*cb)());
@end example

@subsubheading Purpose

This function uses @code{net_connect} and @code{net_poll_connect}
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.

@subsubheading Parameters

@var{conn} is the conn to connect with.  @var{addr} is the target 
address.  @var{cb} is the address of the callback function.

@subsubheading Return value

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.

@c ----------------------------------------------------------------
@node net_connect_wait_cb_time, net_send_rdm, net_connect_wait_cb, Connection Functions
@subsection net_connect_wait_cb_time
@findex net_connect_wait_cb_time
@cindex conn, connecting with callback and time limit
@cindex connecting a conn with callback and time limit

@subsubheading Prototype

@example
int net_connect_wait_cb_time (NET_CONN *conn, char *addr, int (*cb)(), int time)
@end example

@subsubheading Purpose

This function uses @code{net_connect} and @code{net_poll_connect}
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.

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

@subsubheading Parameters

@var{conn} is the conn to connect with.  @var{addr} is the target 
address.  @var{cb} is the callback function and @var{time} is the 
time in seconds to wait before giving up.

@subsubheading Return value

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.

@c ----------------------------------------------------------------
@node net_send_rdm, net_receive_rdm, net_connect_wait_cb_time, Connection Functions
@subsection net_send_rdm
@findex net_send_rdm
@cindex conn, sending packets
@cindex sending packets on a conn
@cindex packets, sending on a conn
@cindex data, sending on a conn
@cindex RDM, sending
@cindex sending RDMs

@subsubheading Prototype

@example
int net_send_rdm (NET_CONN *conn, void *buffer, int size);
@end example

@subsubheading Purpose

Sends data down a conn.  Analogous to @ref{net_send}.

@subsubheading Parameters

@var{conn} is the conn to send the packet down, @var{buffer} points 
to the data to send and @var{size} is the number of bytes to send.

@subsubheading Return value

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

@c ----------------------------------------------------------------
@node net_receive_rdm, net_query_rdm, net_send_rdm, Connection Functions
@subsection net_receive_rdm
@findex net_receive_rdm
@cindex conn, receiving packets
@cindex receiving packets on a conn
@cindex packets, receiving on a conn
@cindex data, receiving on a conn
@cindex RDM, receiving
@cindex reading from a conn
@cindex receiving RDMs

@subsubheading Prototype

@example
int net_receive_rdm (NET_CONN *conn, void *buffer, int maxsize);
@end example

@subsubheading Purpose

Receives data from a conn.  Analogous to @ref{net_receive}.

@subsubheading Parameters

@var{conn} is the conn to receive from.  @var{buffer} points 
somewhere to store the packet, and @var{maxsize} is the maximum 
number of bytes to store.

@subsubheading Return value

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

@c ----------------------------------------------------------------
@node net_query_rdm, net_ignore_rdm, net_receive_rdm, Connection Functions
@subsection net_query_rdm
@findex net_query_rdm
@cindex conn, querying for incoming packets
@cindex conn, checking for incoming packets
@cindex querying for incoming packets on a conn
@cindex checking for incoming packets on a conn
@cindex packets, querying for on a conn
@cindex packets, checking for on a conn
@cindex data, querying for on a conn
@cindex data, checking for on a conn
@cindex RDM, querying for
@cindex RDM, checking for

@subsubheading Prototype

@example
int net_query_rdm (NET_CONN *conn);
@end example

@subsubheading Purpose

Tests whether data can be read from a conn.  Analogous to 
@ref{net_query}, but this function actually returns the size
of the next queued packet.

@subsubheading Parameters

@var{conn} is the conn to test.

@subsubheading Return value

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

@example
if (net_query_rdm (conn)) process_data(conn);
@end example


@c ----------------------------------------------------------------
@node net_ignore_rdm, net_conn_stats, net_query_rdm, Connection Functions
@subsection net_ignore_rdm
@findex net_ignore_rdm
@cindex conn, ignoring packets
@cindex conn, dropping packets deliberately
@cindex ignoring a packet queued on a conn
@cindex large packets, ignoring
@cindex packets, dropping deliberately
@cindex dropping packets deliberately
@cindex RDM, ignoring

@subsubheading Prototype

@example
int net_ignore_rdm (NET_CONN *conn);
@end example

@subsubheading Purpose

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.

@subsubheading Parameters

@var{conn} is the conn to operate on.

@subsubheading Return value