# Networking reference

This appendix is a reference of the standard networking module.

## Standard networking module

Symbol | Description
--- | ---
afnix-net | module
afnix:net | nameset

Address

The `Address` class is the Internet address manipulation class. The class can be used to perform the conversion between a host name and an IP address. The opposite is also possible. Finally, the class supports both IP version 4 and IP version 6 address formats.

address-p
Object
Address
String

The `Address` constructor create an IP address object by name. The name argument is a string of a host name or a valid IP address representation.

Address
String Boolean

The `Address` constructor create an IP address object by name and force the reverse lookup resolution depending on the boolean flag value. The first argument is a string of a host name or a valid IP address representation. The second argument is a boolean flag that indicates whether or not reverse lookup must occur during the construction.

==
Boolean
Address

The `==` operator returns true if the calling object is equal to the address argument.

!=
Boolean
Address

The `!=` operator returns true if the calling object is not equal to the address argument.

<
Boolean
Address

The `<` operator returns true if the calling address is less than the address object.

<=
Boolean
Address

The `<=` operator returns true if the calling address is less equal than the address object.

>
Boolean
Address

The `>` operator returns true if the calling address is greater than the address object.

>=
Boolean
Address

The `<=` operator returns true if the calling address is greater equal than the address object.

++
Address
Address

The `++` operator increments the calling address by one position.

resolve
String Boolean
none

The `resolve` method resolves an host name and eventually performs a reverse lookup. The first argument is a string of a host name or a valid IP address representation. The second argument is a boolean flag that indicates whether or not reverse lookup must occur during the resolution.

get-name
String
none

The `get-name` method returns the original name used during the object construction.

get-address
String
none

The `get-address` method returns a string representation of the IP address. The string representation follows the IP version 4 or IP version 6 preferred formats, depending on the internal representation.

get-vector
Vector
none

The `get-vector` method returns a vector representation of the IP address. The vector result follows the IP version 4 or IP version 6 preferred format, depending on the internal representation.

get-canonical-name
String
none

The `get-canonical-name` method returns a fully qualified name of the address. The resulting name is obtained by performing a reverse lookup. Note that the name can be different from the original name.

get-alias-size
Integer
none

The `get-alias-size` method returns the number of aliases for the address. The number of aliases includes as well the primary resolved name which is located at index 0.

get-alias-name
String
Integer

The `get-alias-name` method returns a fully qualified name of the address alias by index. The first argument is the alias index number which must be in the alias index range. The resulting name is obtained by performing a reverse lookup. Note that the name can be different from the original name. Using index 0 is equivalent to call `get-canonical-name`.

get-alias-address
String
Integer

The `get-alias-address` method returns a string representation of the IP address alias by index. The first argument is the alias index number which must be in the alias index range. The string representation follows the IP version 4 or IP version 6 preferred formats, depending on the internal representation. Using index 0 is equivalent to call `get-address`.

get-alias-vector
Vector
Integer

The `get-alias-vector` method returns a vector representation of the IP address alias by index. The first argument is the alias index number which must be in the alias index range. The vector result follows the IP version 4 or IP version 6 preferred format, depending on the internal representation. Using index 0 is equivalent to call `get-vector`.

Socket

The `Socket` class is a base class for the network services. The class is automatically constructed by a derived class and provide some common methods for all socket objects.

socket-p
Input
Output
REUSE-ADDRESS

The `REUSE-ADDRESS` constant is used by the `set-option` method to enable socket address reuse. This option changes the rules that validates the address used by bind. It is not recommended to use that option as it decreases TCP reliability.

BROADCAST

The `BROADCAST` constant is used by the `set-option` method to enable broadcast of packets. This options only works with IP version 4 address. The argument is a boolean flag only.

DONT-ROUTE

The `DONT-ROUTE` constant is used by the `set-option` method to control if a packet is to be sent via the routing table. This option is rarely used with . The argument is a boolean flag only.

KEEP-ALIVE

The `KEEP-ALIVE` constant is used by the `set-option` method to check periodically if the connection is still alive. This option is rarely used with . The argument is a boolean flag only.

LINGER

The `LINGER` constant is used by the `set-option` method to turn on or off the lingering on close. If the first argument is true, the second argument is the linger time.

RCV-SIZE

The `RCV-SIZE` constant is used by the `set-option` method to set the receive buffer size.

SND-SIZE

The `SND-SIZE` constant is used by the `set-option` method to set the send buffer size.

HOP-LIMIT

The `HOP-LIMIT` constant is used by the `set-option` method to set packet hop limit.

MULTICAST-LOOPBACK

The `MULTICAST-LOOPBACK` constant is used by the `set-option` method to control whether or not multicast packets are copied to the loopback. The argument is a boolean flag only.

MULTICAST-HOP-LIMIT

The `MULTICAST-HOP-LIMIT` constant is used by the `set-option` method to set the hop limit for multicast packets.

MAX-SEGMENT-SIZE

The `MAX-SEGMENT-SIZE` constant is used by the `set-option` method to set the TCP maximum segment size.

NO-DELAY

The `NO-DELAY` constant is used by the `set-option` method to enable or disable the Naggle algorithm.

bind
none
Integer

The `bind` method binds this socket to the port specified as the argument.

bind
none
Integer Address

The `bind` method binds this socket to the port specified as the first argument and the address specified as the second argument.

connect
none
Integer Address [Boolean]

The `connect` method connects this socket to the port specified as the first argument and the address specified as the second argument. A connected socket is useful with udp client that talks only with one fixed server. The optional third argument is a boolean flag that permits to select whether or not the alias addressing scheme should be used. If the flag is false, the default address is used. If the flag is true, an attempt is made to connect to the first successful address that is part of the alias list.

open-p
Boolean
none

The `open-p` predicate returns true if the socket is open. The method checks that a descriptor is attached to the object. This does not mean that the descriptor is valid in the sense that one can read or write on it. This method is useful to check if a socket has not been closed.

shutdown
Boolean
none|Boolean

The `shutdown` method shutdowns or close the connection. Without argument, the connection is closed without consideration for those symbols attached to the object. With one argument, the connection is closed in one direction only. If the mode argument is false, further receive is disallowed. If the mode argument is true, further send is disallowed. The method returns true on success, false otherwise.

ipv6-p
Boolean
none

The `ipv6-p` predicate returns true if the socket address is an IP version 6 address, false otherwise.

read
Character
none

The `read` method returns the next character available from the socket. If the socket has been closed, the `eof` character is returned.

read
Buffer
Integer

The `read` method with an integer argument returns a buffer of characters by reading the socket. The number of read characters might be less than requested. Use the `length` method to check for the returned buffer size.

readln
String
none

The `readln` method returns the next line available from the socket. If the socket has been closed, the `eof` character is returned.

write
none
Literal+

The `write` method write one or more literal arguments on the socket. This method returns nil.

writeln
none
Literal

The `writeln` method write one or more literal argument to the socket and finish with a newline. This method return nil.

newline
none
none

The `newline` method writes a new line character to the socket. The method returns nil.

close
Boolean
none

The `close` method close the socket and returns true on success, false otherwise. In case of success, multiple calls return true.

valid-p
Boolean
none|Integer

The `valid-p` method returns true if the socket is in a valid state. By valid state, we mean that the socket can read a character. With one argument, the method timeout after the specified time.

eof-p
Boolean
none

The `eof-p` method returns true if no more characters can be read from this socket or the socket has been closed.

pushback
none
Character|String

The `pushback` method pushback a character or a string in the input stream. Subsequent calls to read will return the last pushed characters. Pushing a string is equivalent to push each characters of the string.

get-socket-address
Address
none

The `get-socket-address` method returns an address object of the socket. The returned object can be later used to query the canonical name and the ip address.

get-socket-port
Integer
none

The `get-socket-address` method returns the port number of the socket.

get-peer-address
Address
none

The `get-peer-address` method returns an address object of the socket's peer. The returned object can be later used to query the canonical name and the ip address.

get-peer-port
Integer
none

The `get-socket-address` method returns the port number of the socket's peer.

set-option
Boolean
constant [Boolean|Integer] [Integer]

The `set-option` method set a socket option. The first argument is the option to set. The second argument is a boolean value which turn on or off the option. The optional third argument is an integer needed for some options.

TcpSocket

The `TcpSocket` class is a base class for all tcp socket objects. The class is derived from the `Socket` class and provides some specific tcp methods. If a `TcpSocket` is created, the user is responsible to connect it to the proper address and port.

tcp-socket-p
Socket
TcpSocket
none

The `TcpSocket` constructor creates a new tcp socket.

accept
TcpSocket
none

The `accept` method waits for incoming connection and returns a `TcpSocket` object initialized with the connected peer. The result socket can be used to perform i/o operations. This method is used by tcp server.

listen
Boolean
none|Integer

The `listen` method initialize a socket to accept incoming connection. Without argument, the default number of incoming connection is 5. The integer argument can be used to specify the number of incoming connection that socket is willing to queue. This method is used by tcp server.

TcpClient

The `TcpClient` class creates a tcp client by host and port. The host argument can be either a name or an address object. The port argument is the server port to contact. The `TcpClient` class is derived from the `TcpSocket` class. This class has no specific methods.

tcp-client-p
TcpSocket
TcpClient
String Integer

The `TcpClient` constructor creates a new tcp client socket by host name and port number.

TcpServer

The `TcpServer` class creates a tcp server by port. An optional host argument can be either a name or an address object. The port argument is the server port to bind. The `TcpServer` class is derived from the `TcpSocket` class. This class has no specific methods. With one argument, the server bind the port argument on the local host. The backlog can be specified as the last argument. The host name can also be specified as the first argument, the port as second argument and eventually the backlog. Note that the host can be either a string or an address object.

tcp-server-p
TcpSocket
TcpServer
none

The `TcpServer` constructor creates a default tcp server.

TcpServer
Integer

The `TcpServer` constructor creates a default tcp server which is bound on the specified port argument.

TcpServer
Integer Integer

The `TcpServer` constructor creates a default tcp server which is bound on the specified port argument. The second argument is the backlog value.

TcpServer
String Integer

The `TcpServer` constructor creates a tcp server by host name and port number. The first argument is the host name. The second argument is the port number.

TcpServer
String Integer Integer

The `TcpServer` constructor creates a tcp server by host name and port number. The first argument is the host name. The second argument is the port number. The third argument is the backlog.

Datagram

The `Datagram` class is a socket class used by udp socket. A datagram is constructed by the `UdpSocket` `accept` method. The purpose of a datagram is to store the peer information so one can reply to the sender. The datagram also stores in a buffer the data sent by the peer. This class does not have any constructor nor any specific method.

datagram-p
Socket
UdpSocket

The `UdpSocket` class is a base class for all udp socket objects. The class is derived from the `Socket` class and provides some specific udp methods.

udp-socket-p
Socket
UdpSocket
none

The `UdpSocket` constructor creates a new udp socket.

accept
Datagram
none

The `accept` method waits for an incoming datagram and returns a `Datagram` object. The datagram is initialized with the peer address and port as well as the incoming data.

UdpClient

The `UdpClient` class creates a udp client by host and port. The host argument can be either a name or an address object. The port argument is the server port to contact. The `UdpClient` class is derived from the `UdpSocket` class. This class has no specific methods.

udp-client-p
UdpSocket
UdpClient
String Integer

The `UdpClient` constructor creates a new udp client by host and port. The first argument is the host name. The second argument is the port number.

UdpServer

The `UdpServer` class creates a udp server by port. An optional host argument can be either a name or an address object. The port argument is the server port to bind. The `UdpServer` class is derived from the `UdpSocket` class. This class has no specific methods. With one argument, the server bind the port argument on the local host. The host name can also be specified as the first argument, the port as second argument. Note that the host can be either a string or an address object.

udp-server-p
UdpSocket
UdpServer
none

The `UdpServer` constructor creates a default udp server object.

UdpServer
String|Address

The `UdpServer` constructor creates a udp server object by host. The first argument is the host name or host address.

UdpServer
String|Address Integer

The `UdpServer` constructor creates a udp server object by host and port. The first argument is the host name or host address. The second argument is the port number.

Multicast

The `Multicast` class creates a udp multicast socket by port. An optional host argument can be either a name or an address object. The port argument is the server port to bind. The `Multicast` class is derived from the `UdpSocket` class. This class has no specific methods. With one argument, the server bind the port argument on the local host. The host name can also be specified as the first argument, the port as second argument. Note that the host can be either a string or an address object. This class is similar to the `UdpServer` class, except that the socket join the multicast group at construction and leave it at destruction.

multicast-p
UdpSocket
Multicast
String|Address

The `Multicast` constructor creates a multicast socket object by host. The first argument is the host name or host address.

Multicast
String|Address Integer

The `Multicast` constructor creates a multicast socket object by host and port. The first argument is the host name or host address. The second argument is the port number.

get-loopback
String
none

The `get-loopback` function returns the name of the machine loopback. On a UNIX system, that name is localhost.

get-tcp-service
String
Integer

The `get-tcp-service` function returns the name of the tcp service given its port number. For example, the tcp service at port 13 is the daytime server.

get-udp-service
String
Integer

The `get-udp-service` function returns the name of the udp service given its port number. For example, the udp service at port 19 is the chargen server.