libnet.txi

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

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

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


@c ----------------------------------------------------------------
@node net_conn_stats, net_getpeer, net_ignore_rdm, Connection Functions
@subsection net_conn_stats
@findex net_conn_stats
@cindex conn, status of packet queues
@cindex conn, packet queue status
@cindex packet queue status of a conn
@cindex queue status of a conn
@cindex getting the status of a conn
@cindex incoming packet count of a conn
@cindex outgoing packet count of a conn
@cindex conn, optimising network usage
@cindex optimising network usage

@subsubheading Prototype

@example
int net_conn_stats (NET_CONN *conn, int *in_q, int *out_q);
@end example

@subsubheading Purpose

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

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

@subsubheading Parameters

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

@subsubheading Return value

Zero on success.

@example
int in_queue, out_queue;
net_conn_stats (conn, &in_queue, &out_queue);
@end example


@c ----------------------------------------------------------------
@node net_getpeer,  , net_conn_stats, Connection Functions
@subsection net_getpeer
@findex net_getpeer
@cindex getting the address of a conn's peer
@cindex peer, getting address of
@cindex peer, definition
@cindex conn, peer's address

@subsubheading Prototype

@example
char *net_getpeer (NET_CONN *conn);
@end example

@subsubheading Purpose

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} or 
passed to a successful @code{net_poll_connect}).

@subsubheading Parameters

@var{conn} is the conn whose address will be returned.

@subsubheading Return value

A pointer to a static array is returned.  Do not write through 
the pointer.  @code{NULL} is returned on error.

@example
printf ("Connection received from %s\n", net_getpeer (conn));
@end example


@c ----------------------------------------------------------------
@node Driver List Functions, Alphabetic List of Functions, Connection Functions, Functions
@section Driver List Functions
@cindex driver list functions
@cindex functions, driver list manipulation
@cindex manipulating driver lists

These functions are provided to manipulate driver lists.

@menu
* net_driverlist_create::       
* net_driverlist_destroy::      
* net_driverlist_clear::        
* net_driverlist_add::          
* net_driverlist_remove::       
* net_driverlist_add_list::     
* net_driverlist_remove_list::  
* net_driverlist_test::         
* net_driverlist_foreach::      
* net_driverlist_count::        
@end menu


@c ----------------------------------------------------------------
@node net_driverlist_create, net_driverlist_destroy, Driver List Functions, Driver List Functions
@subsection net_driverlist_create
@findex net_driverlist_create

@subsubheading Prototype

@example
NET_DRIVERLIST net_driverlist_create (void);
@end example

@subsubheading Purpose

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

@subsubheading Return value

This function returns a pointer to the @code{NET_DRIVERLIST} struct it
creates, or @code{NULL} on error (extremely unlikely).


@c ----------------------------------------------------------------
@node net_driverlist_destroy, net_driverlist_clear, net_driverlist_create, Driver List Functions
@subsection net_driverlist_destroy
@findex net_driverlist_destroy

@subsubheading Prototype

@example
void net_driverlist_destroy (NET_DRIVERLIST list);
@end example

@subsubheading Purpose

Frees the memory occupied by a driver list.

@subsubheading Parameters

@var{list} is the driver list to free.


@c ----------------------------------------------------------------
@node net_driverlist_clear, net_driverlist_add, net_driverlist_destroy, Driver List Functions
@subsection net_driverlist_clear
@findex net_driverlist_clear

@subsubheading Prototype

@example
int net_driverlist_clear (NET_DRIVERLIST list);
@end example

@subsubheading Purpose

This function clears a driver list.

@subsubheading Parameters

@var{list} is the driver list to clear.

@subsubheading Return value

This function always returns 1.


@c ----------------------------------------------------------------
@node net_driverlist_add, net_driverlist_remove, net_driverlist_clear, Driver List Functions
@subsection net_driverlist_add
@findex net_driverlist_add

@subsubheading Prototype

@example
int net_driverlist_add (NET_DRIVERLIST list, int driver);
@end example

@subsubheading Purpose

This function adds a driver to a driver list.

@subsubheading Parameters

@var{driver} is one of the @code{NET_DRIVER_*} constants, and will be
added to the driver list @var{list}.

@subsubheading Return value

This function always returns 1.


@c ----------------------------------------------------------------
@node net_driverlist_remove, net_driverlist_add_list, net_driverlist_add, Driver List Functions
@subsection net_driverlist_remove
@findex net_driverlist_remove

@subsubheading Prototype

@example
int net_driverlist_remove (NET_DRIVERLIST list, int driver);
@end example

@subsubheading Purpose

This function removes a driver from a driver list.

@subsubheading Parameters

@var{list} is the driver list from which the driver @var{driver} will be
removed.

@subsubheading Return value

This function always returns 1.


@c ----------------------------------------------------------------
@node net_driverlist_add_list, net_driverlist_remove_list, net_driverlist_remove, Driver List Functions
@subsection net_driverlist_add_list
@findex net_driverlist_add_list

@subsubheading Prototype

@example
int net_driverlist_add_list (NET_DRIVERLIST list1, NET_DRIVERLIST list2);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

The contents of driver list @var{list2} will be added into the contents
of driver list @var{list1}.  @var{list1} will be modified in place.

@subsubheading Return value

This function always returns 1.


@c ----------------------------------------------------------------
@node net_driverlist_remove_list, net_driverlist_test, net_driverlist_add_list, Driver List Functions
@subsection net_driverlist_remove_list
@findex net_driverlist_remove_list

@subsubheading Prototype

@example
int net_driverlist_remove_list (NET_DRIVERLIST list1, NET_DRIVERLIST list2);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

The contents of driver list @var{list2} will be removed from driver list
@var{list1}.  @var{list1} will be modified in place.

@subsubheading Return value

This function always returns 1.


@c ----------------------------------------------------------------
@node net_driverlist_test, net_driverlist_foreach, net_driverlist_remove_list, Driver List Functions
@subsection net_driverlist_test
@findex net_driverlist_test

@subsubheading Prototype

@example
int net_driverlist_test (NET_DRIVERLIST list, int driver);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

@var{list} is the driver list in which to look for the driver
@var{driver}.

@subsubheading Return value

Returns non-zero if @var{list} contains @var{driver}, otherwise returns
zero.


@c ----------------------------------------------------------------
@node net_driverlist_foreach, net_driverlist_count, net_driverlist_test, Driver List Functions
@subsection net_driverlist_foreach
@findex net_driverlist_foreach

@subsubheading Prototype

@example
int net_driverlist_foreach (NET_DRIVERLIST list,
	int (*func)(int driver, void *dat), void *dat);
@end example

@subsubheading Purpose

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

@subsubheading Parameters

@var{list} is the driver list to iterate through.

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

@var{dat} is a parameter which you can use to pass any data you want to
the callback function.

@subsubheading Return value

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

@subsubheading Notes

Note that Libnet driver lists do not preserve the order in which you add
or remove drivers.  Currently, @code{net_driverlist_foreach} 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.


@c ----------------------------------------------------------------
@node net_driverlist_count,  , net_driverlist_foreach, Driver List Functions
@subsection net_driverlist_count
@findex net_driverlist_count

@subsubheading Prototype

@example
int net_driverlist_count (NET_DRIVERLIST list);
@end example

@subsubheading Purpose

Counts the number of drivers in a driver list.

@subsubheading Parameters

@var{list} is the driver list to count.

@subsubheading Return value

The number of drivers in @var{list}.


@c ----------------------------------------------------------------
@node Alphabetic List of Functions,  , Driver List Functions, Functions
@section Alphabetic List of Functions
@cindex functions, alphabetical list
@cindex list of functions
@cindex alphabetic list of functions

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

@printindex fn




@c ----------------------------------------------------------------
@node Drivers, Configuration, Functions, Top
@chapter Notes on Drivers in Libnet
@cindex drivers in Libnet
@cindex list of drivers

The drivers fall into the following categories:

@menu
* nonet::                       No networking
* template::                    Template for custom drivers

Internet drivers:  These communicate over the Internet using
UDP.

* socks::                       Berkeley sockets (Unix)
* wsockwin::                    Winsock (Windows)
* wsockdos::                    Winsock (DOS)

IPX drivers:       These communicate over an IPX network.

* ipxdos::                      DOS-based IPX

Serial drivers:    These communicate through a serial link.

* serialdos::                   DOS-based Serial

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

* localhost::                   Local host

Future drivers:    These haven't been written yet.

* Other drivers::               PPP, serial, etc

@end menu


@c ----------------------------------------------------------------
@node nonet, template, Drivers, Drivers
@section No networking