The Sockets package contains all the definitions and subprograms needed to build a simple unicast client or server.

 -- Sockets.Socket_FD: type Socket_FD is tagged private;
     The Socket_FD tagged type is the root type of all sockets. It gets initialized by calling Socket (procedure).

Accept_Socket (procedure)
-------------------------

Purpose
     Accept an incoming connection

Prototype
      -- Sockets.Accept_Socket: procedure Accept_Socket (SOCKET : Socket_FD; NEW_SOCKET : out Socket_FD);

Parameters

     SOCKET   in   Initialized
     NEW_SOCKET   out   Incoming socket object

Description
     This procedure creates a new socket corresponding to an incoming connection on TCP socket SOCKET. All the communications with the peer will take place on NEW_SOCKET, while the program can accept another connection on SOCKET.

     NEW_SOCKET must not be initialized before calling this procedure, or must have been cleaned up by calling Shutdown, in order to avoid a file descriptors leak.

     Accept_Socket will block until an incoming connection is ready to be accepted.

Example

          declare
             Sock     : Socket_FD;
             Incoming : Socket_FD;
          begin
             -- Create a TCP socket listening on local port 4161
             Socket (Sock, PF_INET, SOCK_STREAM);
             Bind (Sock, 4161);
             Listen (Sock, 3);
             -- One-connection-at-a-time server (3 may be pending)
             loop
                -- Wait for a new connection and accept it
                Accept_Socket (Sock, Incoming);
                -- Do some dialog with the remote host
                Do_Some_Dialog (Incoming);
                -- Close incoming socket and wait for next connection
                Shutdown (Incoming);
             end loop;
          end;

See also
     Bind (procedure),
     Listen (procedure),
     Shutdown (procedure),
     Socket (procedure).

Bind (procedure)
----------------

Purpose
     Associate a local port to a socket

Prototype
      -- Sockets.Bind: procedure Bind (SOCKET : Socket_FD; PORT : Natural; HOST : String := "");

Parameters

     SOCKET   in   Initialized socket object
     PORT   in   Local port to bind to
     HOST   in   Local interface to bind to

Description
     This procedure requests a local port from the operating system. If 0 is given in PORT, the system will assign a free port whose number can later be retrieved using Get_Sock_Port (function). Also, most operating systems require special privileges if you want to bind to ports below 1024.

     If HOST is not the empty string, it must contain the IP address of a local interface to bind to, or a name which resolves into such an address. If an empty string is given (the default), the socket will be bound to all the available interfaces.

Exceptions

     Socket_Error   Requested port or interface not available Socket_Error

See also
     Listen (procedure),
     Socket (procedure).

Connect (procedure)
-------------------

Purpose
     Connect a socket on a given host/port

Prototype
      -- Sockets.Connect: procedure Connect (SOCKET : Socket_FD; HOST : String; PORT : Positive);

Parameters

     SOCKET   in   Initialized socket object
     HOST   in   Host to connect to
     PORT   in   Port to connect to

Description
     This procedure connects an initialized socket to a given host on a given port. In the case of a TCP socket, a real connection is attempted. In the case of a UDP socket, no connection takes place but the endpoint coordinates are recorded.

Exceptions

     Connection_Refused   The connection has been refused by the server Connection_Refused
     Socket_Error   Another error occurred during the connection Socket_Error

Example

          declare
             Sock : Socket_FD;
          begin
             -- Create a TCP socket
             Socket (Sock, PF_INET, SOCK_STREAM);
             -- Connect it to rfc1149.net's mail server
             Connect (Sock, "mail.rfc1149.net", 25);
             -- Do a mail transaction then close the socket
             [...]
          end;

See also
     Socket (procedure).

Get (function)
--------------

Purpose
     Get a string from a remote host

Prototype
      -- Sockets.Get: function Get (SOCKET : Socket_FD'Class)
     return String;

Parameters

     SOCKET   in   Initialized and connected socket object

Return value
     Some characters that have been received

Description
     This function receives some characters from a remote host. As soon that at least one character is available, the current reception buffer is returned.

     There is usually little gain in using this function whose behaviour is comparable to the one of Receive (function). Other functions such as Get_Char (function), or Get_Line (function), allow more structured programming.

     However, this function may be used to avoid loosing characters when calling Unset_Buffer (procedure), if, for some reason, the remote host may have sent some.

Exceptions

     Connection_Closed   Peer has closed the connection before sending any data Connection_Closed

Get_Char (function)
-------------------

Purpose
     Get a character from a remote host

Prototype
      -- Sockets.Get_Char: function Get_Char (SOCKET : Socket_FD'Class)
     return Character;

Parameters

     SOCKET   in   Initialized and connected socket object

Return value
     One character sent by the remote host

Description
     This function receives exactly one character from the remote host.

Exceptions

     Connection_Closed   Peer has closed the connection before sending the character Connection_Closed

See also
     Get (function),
     Get_Line (function),
     Get_Line (procedure),
     Receive (procedure),
     Set_Buffer (procedure).

Get_Line (procedure)
--------------------

Purpose
     Get a whole line from a remote host

Prototype
      -- Sockets.Get_Line: procedure Get_Line (SOCKET : Socket_FD'Class; STR : in out String; LAST : out Natural);

Parameters

     SOCKET   in   Initialized and connected socket object
     STR   in out   String to fill
     LAST   out   Last index used in the string

Description
     This procedure receives one line from the remote host. A line consists into zero or more characters followed by an optional CR and by a LF. Those terminators are stripped before the line is returned.

     This procedure blocks until one full line has been received.

Exceptions

     Connection_Closed   Peer has closed the connection before sending a whole line Connection_Closed

See also
     Get (function),
     Get_Char (function),
     Get_Line (function),
     Receive (procedure),
     Set_Buffer (procedure).

Get_Line (function)
-------------------

Purpose
     Get a whole line from a remote host

Prototype
      -- Sockets.Get_Line: function Get_Line (SOCKET : Socket_FD'Class; MAX_LENGTH : Positive := 2048)
     return String;

Parameters

     SOCKET   in   Initialized and connected socket object
     MAX_LENGTH   in   Maximum returned line length

Return value
     A line without the CR and LF separators

Description
     This function receives one line from the remote host. A line consists into zero or more characters followed by an optional CR and by a LF. Those terminators are stripped before the line is returned.

     This function blocks until one full line has been received. The line length is limited with the value of the Max_Length argument, to avoid exhaustion of the secondary stack.

Exceptions

     Connection_Closed   Peer has closed the connection before sending a whole line Connection_Closed

See also
     Get (function),
     Get_Char (function),
     Get_Line (procedure),
     Receive (procedure),
     Set_Buffer (procedure).

Getsockopt (procedure)
----------------------

Purpose
     Retrieve a socket option

Prototype
      -- Sockets.Getsockopt: procedure Getsockopt (SOCKET : Socket_FD; LEVEL : Socket_Level := SOL_SOCKET; OPTNAME : Socket_Option; OPTVAL : out Integer);

Parameters

     SOCKET   in   Initialized and bound socket object
     LEVEL   in   Protocol level
     OPTNAME   in   Option name
     OPTVAL   out   Option value

Description
     This procedure retrieves options applicable to a socket. Please see your operating system manual for usable levels and options.

     Two levels are defined: SOL_SOCKET (the default) and IPPROTO_IP. The options are SO_REUSEADDR, SO_REUSEPORT, IP_MULTICAST_TTL, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, IP_MULTICAST_LOOP, SO_SNDBUF and IP_RCVBUF.

     Note that unlike their C language counterpart, Getsockopt and Setsockopt do not require an extra parameter representing the length in bytes of the option value. AdaSockets nows the right size for every option.

See also
     Setsockopt (procedure).

Listen (procedure)
------------------

Purpose
     Establish a listen queue

Prototype
      -- Sockets.Listen: procedure Listen (SOCKET : Socket_FD; QUEUE_SIZE : Positive := 5);

Parameters

     SOCKET   in   Initialized and bound socket object
     QUEUE_SIZE   in   Requested slots in the listen queue

Description
     This procedure establishes a listen queue after a TCP socket as been initialized and bound. Each slot in the queue can hold one incoming connection that has not been accepted yet. Note that most operating systems ignore queue sizes larger than five.

See also
     Accept_Socket (procedure),
     Bind (procedure),
     Socket (procedure).

New_Line (procedure)
--------------------

Purpose
     Send a CR/LF to a remote host

Prototype
      -- Sockets.New_Line: procedure New_Line (SOCKET : Socket_FD'Class; COUNT : Natural := 1);

Parameters

     SOCKET   in   Initialized and connected socket object
     COUNT   in   Number of CR/LF sequences to send

Description
     This procedure sends one or more CR/LF combinations to the peer.

Exceptions

     Connection_Closed   Peer has prematurely closed the connection Connection_Closed

See also
     Put (procedure),
     Put_Line (procedure).

Put (procedure)
---------------

Purpose
     Send a string to a remote host

Prototype
      -- Sockets.Put: procedure Put (SOCKET : Socket_FD'Class; STR : String);

Parameters

     SOCKET   in   Initialized and connected socket object
     STR   in   String to send

Description
     This procedure sends the content of STR over an outgoing or incoming socket.

Exceptions

     Connection_Closed   Peer has prematurely closed the connection Connection_Closed

See also
     New_Line (procedure),
     Put_Line (procedure),
     Send (procedure).

Put_Line (procedure)
--------------------

Purpose
     Send a CR/LF terminated string to a remote host

Prototype
      -- Sockets.Put_Line: procedure Put_Line (SOCKET : Socket_FD'Class; STR : String);

Parameters

     SOCKET   in   Initialized and connected socket object
     STR   in   String to send

Description
     This procedure sends the content of STR plus a CR/LF combination over an outgoing or incoming socket.

Exceptions

     Connection_Closed   Peer has prematurely closed the connection Connection_Closed

See also
     New_Line (procedure),
     Put (procedure),
     Send (procedure).

Receive (procedure)
-------------------

Purpose
     Receive raw data over a socket

Prototype
      -- Sockets.Receive: procedure Receive (SOCKET : Socket_FD'Class; DATA : out Ada.Streams.Stream_Element_Array);

Parameters

     SOCKET   in   Initialized and bound or connected socket object
     DATA   out   Incoming data buffer

Description
     This procedure receives data from a bound UDP socket or a connected TCP socket. It will block until the DATA reception buffer has been totally filled.

Exceptions

     Connection_Closed   Peer has closed the connection before Data'Length bytes

     were received Connection_Closed

See also
     Get_Line (function),
     Get_Line (procedure),
     Receive (function),
     Receive_Some (procedure).

Receive (function)
------------------

Purpose
     Receive raw data over a socket

Prototype
      -- Sockets.Receive: function Receive (SOCKET : Socket_FD; MAX : Ada.Streams.Stream_Element_Count := 4096)
     return Ada.Streams.Stream_Element_Array;

Parameters

     SOCKET   in   Initialized and bound or connected socket object
     MAX   in   Maximum data length

Return value
     Received raw data

Description
     This procedure receives data from a bound UDP socket or a connected TCP socket. Only one system call will be performed; this function will return whatever data has arrived. Note that in GNAT the secondary stack may be used to store  the data and may result in stack storage exhaustion.

Exceptions

     Connection_Closed   Peer has closed the connection before sending any data Connection_Closed

See also
     Receive (procedure),
     Receive_Some (procedure),
     Get_Line (function),
     Get_Line (procedure).

Receive_Some (procedure)
------------------------

Purpose
     Receive raw data over a socket

Prototype
      -- Sockets.Receive_Some: procedure Receive_Some (SOCKET : Socket_FD'Class; DATA : out Ada.Streams.Stream_Element_Array; LAST : out Ada.Streams.Stream_Element_Offset);

Parameters

     SOCKET   in   Initialized and bound or connected socket object
     DATA   out   Incoming data buffer
     LAST   out   Index of last element placed into DATA

Description
     This procedure receives data from a bound UDP socket or a connected TCP socket. As soon as at least one byte has been read, it returns with LAST set to the index of the latest written element of DATA.

Exceptions

     Connection_Closed   Peer has closed the connection before sending any data Connection_Closed

See also
     Get_Line (function),
     Get_Line (procedure),
     Receive (function),
     Receive (procedure).

Send (procedure)
----------------

Purpose
     Send raw data over a socket

Prototype
      -- Sockets.Send: procedure Send (SOCKET : Socket_FD; DATA : out Ada.Streams.Stream_Element_Array);

Parameters

     SOCKET   in   Initialized and connected socket object
     DATA   out   Data to be sent

Description
     This procedure sends data over a connected outgoing socket or over an incoming socket.

Exceptions

     Connection_Closed   Peer has prematurely closed the connection Connection_Closed

See also
     Put (procedure),
     Put_Line (procedure).

Set_Buffer (procedure)
----------------------

Purpose
     Install a line-oriented buffer of the socket object

Prototype
      -- Sockets.Set_Buffer: procedure Set_Buffer (SOCKET : Socket_FD'Class; LENGTH : Positive := 1500);

Parameters

     SOCKET   in   Initialized and connected socket object
     LENGTH   in   Size in bytes of the newly installed buffer

Description
     This procedure puts the socket object in buffered mode. If the socket was already buffered, the content of the previous buffer will be lost. The buffered mode only affects character- and line-oriented read operation such as Get (function), Get_Char (function), and Get_Line (function). Other reception subprograms will not function properly if buffered mode is used at the same time.

     The size of the buffer has to be greater than the biggest possible packet sent by the remote host, otherwise data loss may occur.

See also
     Unset_Buffer (procedure).

Setsockopt (procedure)
----------------------

Purpose
     Set a socket option

Prototype
      -- Sockets.Setsockopt: procedure Setsockopt (SOCKET : Socket_FD; LEVEL : Socket_Level := SOL_SOCKET; OPTNAME : Socket_Option; OPTVAL : Integer);

Parameters

     SOCKET   in   Initialized and bound socket object
     LEVEL   in   Protocol level
     OPTNAME   in   Option name
     OPTVAL   in   Option value

Description
     This procedure sets options applicable to a socket. Please see your operating system manual for usable levels and options.

     Two levels are defined: SOL_SOCKET (the default) and IPPROTO_IP. The options are SO_REUSEADDR, SO_REUSEPORT, IP_MULTICAST_TTL, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, IP_MULTICAST_LOOP, SO_SNDBUF and IP_RCVBUF.

     Note that unlike their C language counterpart, Getsockopt and Setsockopt do not require an extra parameter representing the length in bytes of the option value. AdaSockets nows the right size for every option.

See also
     Getsockopt (procedure).

Shutdown (procedure)
--------------------

Purpose
     Shutdown a socket

Prototype
      -- Sockets.Shutdown: procedure Shutdown (SOCKET : in out Socket_FD; HOW : Shutdown_Type := Both);

Parameters

     SOCKET   in out   Socket object to shutdown
     HOW   in   Direction to shutdown

Description
     This procedure shutdowns either direction of the socket. HOW can take the value Send, Receive or Both.

See also
     Socket (procedure).

Socket (procedure)
------------------

Purpose
     Create a socket of the given mode

Prototype
      -- Sockets.Socket: procedure Socket (SOCKET : out Socket_FD; DOMAIN : Socket_Domain := PF_INET; TYP : Socket_Type := SOCK_STREAM);

Parameters

     SOCKET   out   Socket object to initialize
     DOMAIN   in   Protocol family
     TYP   in   Kind of sockets

Description
     This procedure initializes a new socket object by reserving a file descriptor to the operating system. For backward compatibility with older versions of this library, AF_INET is still accepted as a value but should be replaced as soon as possible with the proper PF_INET. Using SOCK_STREAM for the TYP argument will create a TCP socket while a SOCK_DGRAM will create a UDP one.

Example

          declare
             Sock : Socket_FD;
          begin
             -- Create a TCP socket
             Socket (Sock, PF_INET, SOCK_STREAM);
             -- Perform some operations on socket
             [...]
             -- Shutdown the socket in both directions
             Shutdown (Sock, Both);
          end;

See also
     Shutdown (procedure).

Unset_Buffer (procedure)
------------------------

Purpose
     Deinstall the line-oriented buffer of the socket object

Prototype
      -- Sockets.Unset_Buffer: procedure Unset_Buffer (SOCKET : Socket_FD'Class);

Parameters

     SOCKET   in   Initialized and connected socket object

Description
     This procedure deinstalls the buffer previously installed by Set_Buffer (procedure). If any data is still present in the buffer, it will be lost. To avoid this situation, the buffer can be flushed by calling Get (function).