Struct DeviceBuilder

pub struct DeviceBuilder { /* private fields */ }

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 tx_queue_len(self, tx_queue_len: u32) -> Self

Sets the transmit queue length on Linux.

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

Enables TUN offloads on Linux. After enabling, use recv_multiple/send_multiple for data transmission.

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

Enables multi-queue support on Linux.

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

Enables or disables packet information for the network driver on macOS, Linux.

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.

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.