type dialer[link]

type dialer = fn(addr: str, service: str) (net::socket | error);

A dialer is a function which implements dial for a specific protocol.

type error[link]

type error = !(invalid_address | unknown_service | net::error | dns::error | hosts::error);

Errors which can occur from dial.

type invalid_address[link]

type invalid_address = !void;

Returned if the address parameter was invalid, for example if it specifies an invalid port number.

type unknown_service[link]

type unknown_service = !void;

Returned if the service parameter does not name a service known to the system.

fn dial[link]

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[link]

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[link]

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[link]

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[link]

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 splitaddr[link]

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[link]

fn strerror(err: error) const str;

Converts an error to a human-readable string. The result may be statically allocated.