Crate net_types

source ·
Expand description

Networking types and operations.

This crate defines types and operations useful for operating with various network protocols. Some general utilities are defined in the crate root, while protocol-specific operations are defined in their own modules.

Witness types

This crate makes heavy use of the “witness type” pattern. A witness type is one whose existence “bears witness” to a particular property. For example, the UnicastAddr type wraps an existing address and guarantees that it is unicast.

There are a few components to a witness type.

First, each property is encoded in a trait. For example, the UnicastAddress trait is implemented by any address type which can be unicast. The is_unicast method is used to determine whether a given instance is unicast.

Second, a witness type wraps an address. For example, UnicastAddr<A> can be used with any A: UnicastAddress. There are two ways to obtain an instance of a witness type. Some constants are constructed as witness types at compile time, and so provide a static guarantee of the witnessed property (e.g., Ipv6::LOOPBACK_IPV6_ADDRESS is a UnicastAddr). Otherwise, an instance can be constructed fallibly at runtime. For example, UnicastAddr::new accepts an A and returns an Option<UnicastAddr<A>>, returning Some if the address passes the is_unicast check, and None otherwise.

Finally, each witness type implements the Witness trait, which allows code to be written which is generic over which witness type is used.

Witness types enable a variety of operations which are only valid on certain types of addresses. For example, a multicast MAC address can be derived from a multicast IPv6 address, so the MulticastAddr<Mac> type implements From<MulticastAddr<Ipv6Addr>>. Similarly, given an Ipv6Addr, the to_solicited_node_address method can be used to construct the address’s solicited-node address, which is a MulticastAddr<Ipv6Addr>. Combining these, it’s possible to take an Ipv6Addr and compute the solicited node address’s multicast MAC address without performing any runtime validation:

fn to_solicited_node_multicast_mac(addr: &Ipv6Addr) -> MulticastAddr<Mac> {
    addr.to_solicited_node_address().into()
}

Naming Conventions

When both types and traits exist which represent the same concept, the traits will be given a full name - such as IpAddress or UnicastAddress - while the types will be given an abbreviated name - such as IpAddr, Ipv4Addr, Ipv6Addr, or UnicastAddr.

Modules

Ethernet protocol types.
Internet Protocol (IP) types.

Structs

A witness type for an address and a scope zone.
An address which is guaranteed to be broadcast.
An address which is guaranteed to be link-local.
An address which is guaranteed to be multicast.
An address which is guaranteed to be specified.
An address which is guaranteed to be unicast.

Enums

An address that may have an associated scope zone.

Traits

Addresses that can be broadcast.
Addresses that can be a link-local.
An address that can be link-local and broadcast.
An address that can be link-local and multicast.
An address that can be link-local and unicast.
Addresses that can be multicast.
A scope used by ScopeableAddress. See that trait’s documentation for more information.
An address that can be tied to some scope identifier.
Addresses that can be specified.
Addresses that can be unicast.
A type which is a witness to some property about an address.

Type Definitions

A link-local broadcast address.
A link-local multicast address.
A link-local unicast address.