Struct DeviceBuilder

Source

pub struct DeviceBuilder { /* private fields */ }

Expand description

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§

Source §

impl DeviceBuilder

Source

pub fn new() -> Self

Creates a new DeviceBuilder instance with default settings.

Source

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

Sets the device name.

Source

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

Sets the device MTU (Maximum Transmission Unit).

Source

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

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

Source

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);

Source

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);

Source

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),
]);

Source

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

Source

pub fn tx_queue_len(self, tx_queue_len: u32) -> Self

Sets the transmit queue length on Linux.

Source

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

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

Source

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

Enables multi-queue support on Linux.

Source

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.

Source

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

Enables or disables the device. Defaults to be enabled.

Source

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

Builds a synchronous device instance and applies all configuration parameters.

Source

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.

Source

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();