     [file version.texi not included]

     START-INFO-DIR-ENTRY
     * adasockets: (adasockets).		AdaSockets reference manual
     END-INFO-DIR-ENTRY

Copyright © 2002-2004 Samuel Tardieu

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

What is AdaSockets?
*******************

AdaSockets is a set of free software Ada packages allowing Ada programmers to use the so-called BSD sockets from their favourite programming language. AdaSockets has been designed and tested with the GNAT free software Ada compiler, but should be portable to other compilers quite easily.

Starting from release 3.14, the GNAT compiler started to integrate a GNAT.Sockets package. However, this package is GNAT specific and contains at this time less features than AdaSockets. At some point, AdaSockets may use GNAT.Sockets as its underlying sockets structure.

AdaSockets philosophy is to help the Ada programmer by providing easy-to-use objects. Special care has been taken to ensure that performances do however remain good.

Installing AdaSockets
*********************

Installing AdaSockets on a Unix or OpenVMS machine is as simple as typing a few commands. Once you got the latest version of AdaSockets (see Resources on the Internet), uncompress and untar it and go to the top-level directory of the distribution.

You must configure the AdaSockets distribution by using the configure command, such as in:

     ./configure --prefix=/users/sam/adasockets

If you want to install AdaSockets under the /usr/local hierarchy, you do not need to specify the --prefix option. Make sure you have write permission on the target directories.

Once AdaSockets is configured, you can compile and install it by using the make command:

     make install

The GNU make program is recommended but not mandatory. On your system, it may be installed under the gmake name.

Using AdaSockets
****************

Compiling an Ada application
============================

AdaSockets comes with an adasockets-config application that can be used to retrieve installation parameters while using gnatmake to compile your Ada application. The --cflags parameters tells adasockets-config to output the path to the Ada packages sources, while --libs asks for the path to the Ada library.

     gnatmake `adasockets-config --cflags` mainprog
       -largs `adasockets-config --libs`

Setting up unicast sockets
==========================

Unicast sockets are used everywhere on the Internet, for surfing the web, sending electronic mails or accessing remote files. They come in two flavours:

TCP
     TCP is a connected mode, in which packets are sent in a reliable and ordered way. Everything sent at one end will eventually arrive in the same order at the other end, the underlying operating system takes care of retransmitting missing packets and reordering out-of-order ones.

UDP
     UDP is a non-connected mode. A packet sent on a UDP socket may or may not arrive at the other end. This is a much lighter protocol when reliability is not needed as the operating system does not have to use large buffers to reorder packets. Also, this generates less traffic as no acknowledgments need to be sent by the kernels.

The package Sockets defines a Socket_FD tagged type. An instance of this type (or of any of its descendants) represents an incoming or outgoing socket. Two different kinds of sockets can be created: unicast (one-to-one) and multicast (many-to-many).

Setting up multicast sockets
============================

Multicast sockets are used for group communication over the Internet. To use multicast sockets, you must be connected to a multicast network and use a multicast-enabled operating system (such as most Unices, Linux or even recent Windows versions). Unless you are connected to the mbone (multicast backbone) or have setup a private multicast network, you will only be able to use multicast on your local network.

A multicast socket is somewhat similar to a UDP socket; in particular, packets may be lost or misordered.

You can create a multicast socket using the function Create_Multicast_Socket in the package Sockets.Multicast. This function returns a Multicast_Socket_FD object, which derives from Socket_FD.

Create_Multicast_Socket takes care of the whole setup of your multicast socket. You do not need to call any additionnal subprogram before using it. In particular, Create_Multicast_Socket will take care of registering the multicast socket to the operating system, so that the latter can tell the connected routers to propagate the subscription to the mbone as needed.

Sending and receiving data
==========================

In AdaSockets, data can be sent and received in three different ways: raw, string-oriented and stream-oriented.

Raw data manipulation
---------------------

Raw data is manipulated using the predefined Ada.Streams.Stream_Element_Array Ada type. This corresponds to an array of bytes, or an unsigned char * in the C programming language.

String-oriented exchanges
-------------------------

String-oriented exchanges provides the programmer with Ada.Text_IO like subprograms. Most Internet protocols are line-oriented and those subprograms are perfectly suited to implement those.

When sending data, the classical CR + LF sequence will be sent at the end of each line. When receiving data, CR characters are discarded and LF is used as the end-of-line marker.

The Get function is tied to the size of the operating system buffer. It is better to use Get_Line to get a full line. The line can be as long as the length of the Ada buffer. The Ada buffer can be adjusted by using the Set_Buffer and Unset_Buffer procedures.

When using string-oriented exchanges with datagram protocols such as UDP, setting a buffer using Set_Buffer for the receiving socket is mandatory. If you don't, the receiving socket will loose data and will be unable to reconstitute the string.

Sockets package
***************

     [file sockets.texi not included]

Sockets.Multicast package
*************************

     [file sockets-multicast.texi not included]

Sockets.Naming package
**********************

     [file sockets-naming.texi not included]

Contributors
************

AdaSockets has been originally developped by Samuel Tardieu who still maintains it. However, the following people have made crucial contributions to AdaSockets, be they new code, bug fixes or porting to new operating systems:

  * Dmitriy Anisimkov (anisimkov@yahoo.com)

  * Alan Barnes (barnesa@aston.ac.uk)

  * Juanma Barranquero (lektu@terra.es)

  * Bobby D. Bryant (bdbryant@mail.utexas.edu)

  * Sander Cox (sander.cox@philips.com)

  * Sune Falk (sune.falck@telia.com)

  * Guillaume Foliard (guifo@wanadoo.fr)

  * Laurent Guerby (guerby@club-internet.fr)

  * David J. Kristola (David95037@aol.com)

  * Dominik Madon (dominik@acm.org)

  * Pascal Obry (p.obry@wanadoo.fr)

  * Nicolas Ollinger (Nicolas.Ollinger@ens-lyon.fr)

  * Stéphane Patureau (spaturea@meletu.univ-valenciennes.fr)

  * Thomas Quinot (thomas@cuivre.fr.eu.org)

  * Preben Randhol (randhol@pvv.org)

  * Maxim Reznik (max1@mbank.com.ua)

  * Samuel Tardieu (sam@rfc1149.net)

If you feel that you have been forgotten, please send me a mail so that I can fix it in the next version.

See Resources on the Internet, for how to contribute.

Resources on the Internet
*************************

The latest version of AdaSockets can always be found at:

http://www.rfc1149.net/devel/adasockets

There is a mailing-list that you can use to discuss problem or suggestions at:

http://www.rfc1149.net/lists/info/adasockets

Please use the mailing-list for questions and discussions. However, you can send me patches by private mail (sam@rfc1149.net).