@head @module socket @title socket: Network connections

This module supports creating TCP clients that create stream-based network connections to other computers or processes. In this context, the term socket refers to IPv4 stream sockets only. @see Use the @ref{serversocket} module to create TCP servers. @end

Class Socket

@inherits Stream @supertypes @class Socket(destination as Str, port as Int[, buffering as Constant]) @desc Construct a TCP/IP connection stream to the specified port of the destination host. The destination may be either a host name such as "www.host.com" or a numeric IP address such as "100.50.200.5" (in decimal).

The buffering parameter specifies the buffering mode. If omitted, the connection is unbuffered. Valid values for the parameter are @ref{io::Buffered}, @ref{io::LineBuffered} and @ref{io::Unbuffered}.

Socket is derived from @ref{io::Stream}. Like @ref{File} objects, Socket objects are narrow streams. Socket objects support both writing (sending) and reading (receiving) data. @end

Socket instances are also implicitly created by the @ref{serversocket::ServerSocket} class.

Socket methods

Socket inherits most of the @ref{Stream} operations unchanged, including:

It also supports the following operations: @fun close() @desc Close the connection. Free any resources allocated to the connection. @end @fun localAddress() as Str @desc Return the local IP address as a string in dotted decimal format (e.g. "100.50.200.5"). @end @fun localPort() as Int @desc Return the local port number. @end @fun remoteAddress() as Str @desc Return the remote IP address as a string in dotted decimal format (e.g. "100.50.200.5"). @end @fun remotePort() as Int @desc Return the remote port number. @end @end-class

Functions

@fun GetHostByName(name as Str) as Str @desc Return the IP address of a host. The name argument may be a host name or a numeric IP address in dotted decimal format. If the host has multiple interfaces, only the address of the first interface is returned. @end @fun GetHostByAddress(address as Str) as Str @desc Return the primary host name of the machine with the given IP address. The IP address must be a string in dotted decimal format. @end @fun GetHostName() as Str @desc Return a string containing the hostname of the machine where the program is running. @end

Exceptions

@class NameError([message as Str]) @desc This exception is raised for DNS name lookup related errors. In particular, @ref{GetHostByName} and @ref{GetHostByAddress} may raise this exception. Inherits from @ref{std::Exception}. @end