libnet.txt

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

libnet documentation     seventh revision  by gfoot and dwi   28/03/98
______________________________________________________________________

							|o|   _  _ . 
							|||-.| |/_)|-
							'''-'' '`- `-

	libnet is (c) Copyright Chad Catlett and George Foot 1997-1998
______________________________________________________________________


This is the main documentation for libnet.  Most of it is relevant to 
end-users, but some of it is more relevant to driver authors.  You 
should read the instructions in readme.txt before this.



0. Contents
~~~~~~~~~~~
   0 - Contents
   1 - Basic aims
   2 - Functions
   3 - Drivers
   4 - Config files
   5 - Structs
	 + a) NET_CHANNEL
	 + b) NET_DRIVER
	 + c) NET_DRIVERNAME
   6 - Improvements
   7 - Contacting the authors



1. Basic aims
~~~~~~~~~~~~~
   Aims of this project:


   * Make a generic interface to a variety of network drivers

	 Such an interface will enable people to write programs with
	 networking capabilities without having to tie them down to
	 particular types of network. The same program code will be
	 able to use any supported network (e.g. Winsock, IPX, 
	 serial, ...) neither becoming cluttered nor requiring much
	 effort to adapt.


   * Offer basic functionality only

	 Restricting the functionality means that more classes of
	 network can be implemented and makes it easy for new users
	 to get used to.


   * Make addition of new drivers painless

	 Naturally, writing a new driver will require an amount of
	 research and testing; however, adding new drivers to the
	 library should not be a painful process.


   * Start with a core library, and a few sample drivers; invite
	 other people to contribute new drivers.

	 We can test whether the theory is workable, as well as
	 creating sample programs to show people how to use the
	 library. Hopefully they will then contribute missing
	 drivers.



2. Functions
~~~~~~~~~~~~
   The following functions can be used to communicate with the
   library:


   int net_init();

	  This function initialises the library, and should be
	  called before any others.


   int net_loadconfig (char *filename);

	  This loads a configuration file and invites the various
	  drivers to extract information from it.  If `filename' is
	  NULL it loads `libnet.cfg' from the program's home 
	  directory (as in argv[0]).  If `filename' is a directory
	  the file `libnet.cfg' is loaded from that directory.  If
	  `filename' is a file, that file is loaded.

	  See the separate chapter on config files for full 
	  information about them.


   NET_DRIVERNAME *net_getdrivernames (int which);

	  This function returns an array of NET_DRIVERNAME structs,
	  which contain the reference numbers and names of the
	  drivers specified by `which', plus the `nonet' driver and
	  a terminating entry with a NULL pointer for the driver 
	  name. The list is malloced, and should be freed by the 
	  caller.  If the above description is unclear, please see 
	  tests/getdrvnm.c for a short example.


   int net_detectdrivers (int which);

	  `which' is a combination of the NET_DRIVER_* flags,
	  indicating which drivers to attempt to detect.
	  NET_DRIVER_ALL can be given to detect all drivers.  The
	  function returns a similar bitset showing which of drivers
	  were actually detected.

	  This function can be called once to detect all drivers at
	  once, for example, or it can be called several times (e.g.
	  once per driver to detect).  The return value only shows
	  which of the drivers specified were detected; in the
	  latter case this is not the entire list of detected
	  drivers.


   int net_initdrivers (int which);

	  This function operates similarly to the net_detectdrivers
	  function, but it initialises the specified drivers rather
	  than detecting them.  Also, it returns the complete list of
	  initialised (i.e. ready-for-use) drivers.


   int net_shutdown();

	  Shuts everything down nicely, returning 0 on success.  This
	  will close any open channels and shut down all initialised
	  drivers.


   NET_CHANNEL *net_openchannel(int type);

	  Opens a communications channel for use over the specified
	  network type.  It returns a pointer to the CHANNEL struct
	  created, or NULL on error.


   NET_CHANNEL *net_openinputchannel (int type);

	  Opens a channel in such a way that other computers can
	  send data, without having any specific information about
	  the channel.  Only one should exist per driver.

	  In most respects this is just like a normal channel; it
	  can both send and receive data.  The difference as far as 
	  the Winsock driver is concerned is that the port is known 
	  -- it's either the default value or an override value 
	  from the config file.  This means users don't need to 
	  know the port address to send data.


   int net_closechannel(NET_CHANNEL *channel);

	  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.  Returns 0 on
	  success.


   int net_assigntarget(NET_CHANNEL *channel, char *target);

	  Sets the target of the given channel.  The format of the
	  target address depends upon the network type being used by
	  the channel.


   char *net_getlocaladdress(NET_CHANNEL *channel);

	  Returns the channel's recorded local address.  This might
	  be the address to which other computers should send data,
	  but for some drivers it might not be.  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.


   int net_send(CHANNEL *channel,void *buffer,int size);

	  Sends data down a channel, returning zero to indicate
	  success or non-zero if an error occurs.


   int net_receive(CHANNEL *channel,void *buffer,int maxsize,char *from);

	  Receives data from a channel, maximum `maxsize' bytes,
	  storing the data in `buffer' and, if `from' is not NULL,
	  putting the source's address in that buffer (which should
	  be at least NET_MAX_ADDRESS_LENGTH characters in length).
	  Returns the number of bytes received.  0 is valid; there
	  was no data to read.  -1 indicates that an error occured.


   int net_query(CHANNEL *channel);

	  Returns nonzero if data is ready for reading from the
	  given channel.


   NET_CONN *net_openconn (int type, int listen);

	  Opens a connection to another machine, using the given 
	  network type.  If `listen' is 1, the connection will 
	  be a listening connection.  Only one connection should 
	  listen at a time.  The connection will stop listening 
	  when it is closed.


   int net_connect (NET_CONN *conn, char *target);

	  Connects an open (non-listening) connection to the 
	  given target (which should be listening).  Returns 
	  zero if it connects successfully, nonzero otherwise. 


   int net_accept (NET_CONN *conn);

	  Causes a listening connection to check for connection 
	  attempts.  If there has been an attempt, the connection 
	  stops listening and this function returns zero.  Otherwise 
	  this function returns nonzero.


   int net_send_rdm (NET_CONN *conn, void *buffer, int size);
   int net_receive_rdm (NET_CONN *conn, void *buffer, int maxsize, char *from);
   int net_query_rdm (NET_CONN *conn);

	  These functions are the connection-based analogues of the
	  channel-based functions net_send, net_receive and net_query.
	  RDM stands for Reliably Delivered Message.


   int net_closeconn (NET_CONN *conn);

	  Closes a connection.



   The following functions are planned but not implemented:


   NET_STREAM *net_createstream();
	  Create new stream.

   int net_stream_addsource (NET_STREAM *stream, int networktype, ...);
	  Adds an input source to a stream.

   int net_stream_getpacket (NET_STREAM *stream, NET_PACKET *packet);
	  Gets a packet from a stream.

   int net_closestream();
	  Closes a stream.



3. Drivers
~~~~~~~~~~
   More information on the drivers can be found in their
   individual documentation.

   At present, the following drivers are implemented and fully
   functional:


   NET_DRIVER_NONET     -       No networking

	  This driver will return success codes for everything, but
	  won't actually do anything. It's a dummy driver, in case
	  no others are available. Target and return addresses are
	  meaningless; send an empty string to net_assigntarget.


   NET_DRIVER_WSOCK     -       Winsock driver

	  This driver uses the UDP protocol over the internet via
	  Windows 95's or Windows 3.11's Winsock.  The target address
	  should be given either in IP format as four unsigned chars 
	  separated by full stops or in hostname format, and either 
	  type of address can optionally be followed by a colon and
	  a port number.  If the port number is omitted, the default
	  port is used (24785 if not overridden in the config file).
	  For example, setting the target to "127.0.0.1:12345" would
	  cause data to be looped back to the host, coming in on port
	  12345, and setting it to "www.lycos.com" would refer to the
	  Lycos web search engine using the default port of 24785.

	  With this driver, the return address is awkward to complete.
	  The port number is correct but the IP may not be.  More
	  information is given in the docs/wsock.txt file; in general
	  though, clients should connect to a host using any IP 
	  address that refers to the host, and the port given in the