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.

Macros§

  • Invokes I::map_ip, passing the same function body as both arguments.

Structs§

Enums§

  • An address that may have an associated scope zone.

Traits§

Type Aliases§