Crate net_types

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
  Ethernet protocol types.
• ip
  Internet Protocol (IP) types.

Macros

• for_any_ip_version
  Evaluates expression for any given ip_version.
• map_ip_twice
  Invokes I::map_ip, passing the same function body as both arguments.

Structs

• AddrAndPortFormatter
  Provides a Display implementation for printing an address and a port.
• AddrAndZone
  A witness type for an address and a scope zone.
• BroadcastAddr
  An address which is guaranteed to be broadcast.
• LinkLocalAddr
  An address which is guaranteed to be link-local.
• MulticastAddr
  An address which is guaranteed to be multicast.
• NonMappedAddr
  An address which is guaranteed to be non_mapped.
• NonMulticastAddr
  An address which is guaranteed to be non-multicast.
• SpecifiedAddr
  An address which is guaranteed to be specified.
• UnicastAddr
  An address which is guaranteed to be unicast.

Enums

• ZonedAddr
  An address that may have an associated scope zone.

Traits

• BroadcastAddress
  Addresses that can be broadcast.
• LinkLocalAddress
  Addresses that can be a link-local.
• LinkLocalBroadcastAddress
  An address that can be link-local and broadcast.
• LinkLocalMulticastAddress
  An address that can be link-local and multicast.
• LinkLocalUnicastAddress
  An address that can be link-local and unicast.
• MappedAddress
  An address that may represent an address from another addressing scheme.
• MulticastAddress
  Addresses that can be multicast.
• Scope
  A scope used by ScopeableAddress. See that trait’s documentation for more information.
• ScopeableAddress
  An address that can be tied to some scope identifier.
• SpecifiedAddress
  Addresses that can be specified.
• TransposableWitness
  Witness types that can be transposed with other witness wrapper types.
• UnicastAddress
  Addresses that can be unicast.
• Witness
  A type which is a witness to some property about an address.

Type Aliases

• LinkLocalBroadcastAddr
  A link-local broadcast address.
• LinkLocalMulticastAddr
  A link-local multicast address.
• LinkLocalUnicastAddr
  A link-local unicast address.