Struct DeviceBuilder 

pub struct DeviceBuilder { /* private fields */ }

This is a unified constructor of a device for various platforms. The specification of every API can be found by looking at the documentation of the concrete platform.

Implementations

impl DeviceBuilder

pub fn new() -> Self

Creates a new DeviceBuilder instance with default settings.

pub fn name<S: Into<String>>(self, dev_name: S) -> Self

Sets the device name.

pub fn mtu(self, mtu: u16) -> Self

Sets the device MTU (Maximum Transmission Unit).

pub fn mac_addr(self, mac_addr: [u8; 6]) -> Self

Sets the MAC address for the device (effective only in L2 mode).

pub fn ipv4<IPv4: ToIpv4Address, Netmask: ToIpv4Netmask>( self, address: IPv4, mask: Netmask, destination: Option<IPv4>, ) -> Self

Configures the IPv4 address for the device.

• address: The IPv4 address of the device.
• mask: The subnet mask or prefix length.
• destination: Optional destination address for point-to-point links.

Example

use std::net::Ipv4Addr;
use tun_rs::DeviceBuilder;
DeviceBuilder::new().ipv4(Ipv4Addr::new(10, 0, 0, 12), 24, None);

pub fn ipv6<IPv6: ToIpv6Address, Netmask: ToIpv6Netmask>( self, address: IPv6, mask: Netmask, ) -> Self

Configures a single IPv6 address for the device.

• address: The IPv6 address.
• mask: The subnet mask or prefix length.

Example

use tun_rs::DeviceBuilder;
DeviceBuilder::new().ipv6("CDCD:910A:2222:5498:8475:1111:3900:2021", 64);

pub fn ipv6_tuple<IPv6: ToIpv6Address, Netmask: ToIpv6Netmask>( self, addrs: &[(IPv6, Netmask)], ) -> Self

Configures multiple IPv6 addresses in batch.

Accepts a slice of (IPv6 address, netmask) tuples.

Example

use tun_rs::DeviceBuilder;
DeviceBuilder::new().ipv6_tuple(&[
    ("CDCD:910A:2222:5498:8475:1111:3900:2022", 64),
    ("CDCD:910A:2222:5498:8475:1111:3900:2023", 64),
]);

pub fn layer(self, layer: Layer) -> Self

Sets the operating layer (L2 or L3) for the device.

• L2 corresponds to TAP
• L3 corresponds to TUN

pub fn packet_information(self, packet_information: bool) -> Self

Enables or disables packet information for the network driver(TUN) on macOS, Linux, freebsd, openbsd, netbsd.

This option is disabled by default (false).

Note

There is no native way to enable/disable packet information on macOS. The elimination of the packet information on macOS according to this setting is processed by this library. The set value v can be retrieved by ignore_packet_info, the returned value is !v.

pub fn associate_route(self, associate_route: bool) -> Self

If true (default), the program will automatically add or remove routes on macOS or FreeBSD to provide consistent routing behavior across all platforms. If false, the program will not modify or manage routes in any way, allowing the system to handle all routing natively. Set this to be false to obtain the platform’s default routing behavior.

pub fn reuse_dev(self, reuse: bool) -> Self

Only works in TAP mode. If true (default), the existing device with the given name will be used if possible. If false, an error will be returned if a device with the specified name already exists.

pub fn enable(self, enable: bool) -> Self

Enables or disables the device. Defaults to be enabled.

pub fn build_sync(self) -> Result<SyncDevice>

Builds a synchronous device instance and applies all configuration parameters.

pub fn build_async(self) -> Result<AsyncDevice>

Builds an asynchronous device instance.

This method is available only when either async_io or async_tokio feature is enabled.

Note

Choose one of the two async runtimes; otherwise, a compile error will be incurred if both are enabled.

pub fn with<F: FnMut(&mut DeviceBuilderGuard<'_>)>(self, f: F) -> Self

To conveniently set the platform-specific parameters without breaking the calling chain.

Ergonomic

For example:

use tun_rs::DeviceBuilder;
let builder = DeviceBuilder::new().name("tun1");
#[cfg(target_os = "macos")]
let builder = builder.associate_route(false);
#[cfg(windows)]
let builder = builder.wintun_log(false);
let dev = builder.build_sync().unwrap();

This is tedious and breaks the calling chain.

With with, we can just set platform-specific parameters as follows without breaking the calling chain:

use tun_rs::DeviceBuilder;
let dev = DeviceBuilder::new().name("tun1").with(|opt|{
   #[cfg(windows)]
   opt.wintun_log(false);
   #[cfg(target_os = "macos")]
   opt.associate_route(false).packet_information(false);
}).build_sync().unwrap();

Trait Implementations

impl Default for DeviceBuilder

fn default() -> DeviceBuilder

Returns the “default value” for a type.