net::dial
dial: high-level support for establishing network connections
net::dial provides a single function to facilitate the establishment of outgoing network connections. It handles port selection, address parsing, protocol and service lookup, DNS lookup (via /etc/hosts, /etc/resolv.conf, etc), SRV record resolution, and so on. See dial for details.
Modules implementing their own network protocols are also able to add themselves to the protocol and service registry. The protocol registry is used for transport-level protocols (such as TCP) and is managed via registerproto; the service registry is used for application-level protocols (such as SSH) and is managed via registersvc.
Some useful functions for IP-related protocols to interpret the "addr" parameter of the dial function are also provided, namely resolve.
Index
Types
type dialer = fn(addr: str, service: str) (net::socket | error);
Errors
type error = !(invalid_address | unknown_service | net::error | dns::error | hosts::error | nomem);
type invalid_address = !void;
type unknown_service = !void;
Functions
fn dial(proto: str, address: str, service: str) (net::socket | error);
fn dial_uri(proto: str, uri: *uri::uri) (net::socket | error);
fn registerproto(name: str, dial: *dialer) (void | nomem);
fn registersvc(proto: str, name: str, alias: []str, port: u16) (void | nomem);
fn resolve(proto: str, addr: str, service: str) (([]ip::addr, u16) | error | nomem);
fn splitaddr(addr: str, service: str) ((str, u16) | invalid_address);
fn strerror(err: error) const str;
Types
type dialer
type dialer = fn(addr: str, service: str) (net::socket | error);
A dialer is a function which implements dial for a specific protocol.
Errors
type error
type error = !(invalid_address | unknown_service | net::error | dns::error | hosts::error | nomem);
Errors which can occur from dial.
type invalid_address
type invalid_address = !void;
Returned if the address parameter was invalid, for example if it specifies an invalid port number.
type unknown_service
type unknown_service = !void;
Returned if the service parameter does not name a service known to the system.
Functions
fn dial
fn dial(proto: str, address: str, service: str) (net::socket | error);
Dials a remote address, establishing a connection and returning the resulting net::socket. The proto parameter should be the transport protocol (e.g. "tcp"), the address parameter should be the remote address, and the service should be the name of the service, or the default port to use.
The interpretation of the address and service parameters is dependent on the protocol in use. For IP-based protocols (such as TCP or UDP), the address parameter may be either an IPv4 or IPv6 address, or a name, and may include a port separated by a colon (':'). If an IPv6 address and a port are both desired, use brackets ('[' and ']') to separate the address from the port (e.g. "[::1]:80"). If the port is not specified, it is inferred from the service parameter. If a name is used instead of an IP address, a DNS lookup is performed, consulting the local /etc/hosts file or equivalent, if possible.
The service parameter can be a service name (e.g. "submission") or a default port to use, if one is not specified by address. If a service name is used, an internal list of services is consulted (see registersvc), and if not known to Hare, the system service list (e.g. /etc/services) will be consulted. If the connection port cannot be established, errors::invalid is returned. The special service name "unknown" will always consult the address parameter for a desired port, and will return errors::invalid if one is not provided there.
If the address parameter includes a name, but not a port, an SRV lookup will be performed alongside the A or AAAA record lookup for that name. If the name server provides an SRV record for the given service, it will be utilized in lieu of the service database.
fn dial_uri
fn dial_uri(proto: str, uri: *uri::uri) (net::socket | error);
Performs a dial operation for a given URI, taking the service name from the URI scheme and forming an address from the URI host and port.
fn registerproto
fn registerproto(name: str, dial: *dialer) (void | nomem);
Registers a new transport-level protocol (e.g. TCP) with the dialer. The name should be statically allocated.
fn registersvc
fn registersvc(proto: str, name: str, alias: []str, port: u16) (void | nomem);
Registers a new application-level service (e.g. SSH) with the dialer. Note that the purpose of services is simply to establish the default outgoing port for TCP and UDP connections. The name and alias list should be statically allocated.
fn resolve
fn resolve(proto: str, addr: str, service: str) (([]ip::addr, u16) | error | nomem);
Performs DNS resolution on a given address string for a given service, including /etc/hosts lookup and SRV resolution, and returns a list of candidate IP addresses and the appropriate port, or an error.
The caller must free the net::ip::addr slice.
fn splitaddr
fn splitaddr(addr: str, service: str) ((str, u16) | invalid_address);
Splits an address:port/service string into separate address and port components. The return value is borrowed from the input.
fn strerror
fn strerror(err: error) const str;
Converts an error to a human-readable string. The result may be statically allocated.