net::dial
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;
Errors
type error;
type invalid_address;
type unknown_service;
Functions
fn dial(str, str, str) (net::socket | error);
fn registerproto(str, *dialer) void;
fn registersvc(str, str, []str, u16) void;
fn resolve(str, str, str) (([]ip::addr, u16) | error);
fn strerror(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);
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 registerproto
fn registerproto(name: str, dial: *dialer) void;
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;
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);
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 strerror
fn strerror(err: error) const str;
Converts an error to a human-readable string.