Struct IphlpNetworkAdapterInfo

Source

pub struct IphlpNetworkAdapterInfo { /* private fields */ }

Expand description

Represents information about a network adapter.

This struct provides an easy-to-use and safe interface for working with network adapter information, such as IP addresses, DNS server addresses, gateway addresses, and more.

Implementations§

Source §

impl IphlpNetworkAdapterInfo

Source

pub fn add_unicast_address_ipv4( &self, address: Ipv4Addr, prefix_length: u8, ) -> Option<MIB_UNICASTIPADDRESS_ROW>

Adds an IPv4 unicast address to the network interface.

This function creates a new MIB_UNICASTIPADDRESS_ROW with the provided IPv4 address and prefix length, and then calls the CreateUnicastIpAddressEntry Windows API function to add the unicast address to the network interface. On success, it returns Some(MIB_UNICASTIPADDRESS_ROW); otherwise, it sets the last error and returns None.

§Arguments

address - The IPv4 address to assign to the network interface.
prefix_length - The subnet prefix length for the IPv4 address.

§Returns

Option<MIB_UNICASTIPADDRESS_ROW> - Returns Some(MIB_UNICASTIPADDRESS_ROW) if the unicast address is successfully added to the network interface, or None if the operation fails.

§Safety

This function uses unsafe Windows API calls (InitializeUnicastIpAddressEntry and CreateUnicastIpAddressEntry). The function takes care of initializing the MIB_UNICASTIPADDRESS_ROW struct and ensuring that the arguments and struct fields are properly set before making the API calls. However, any changes to this function or the underlying Windows APIs could introduce potential safety issues. Ensure that you understand the risks and consequences of using unsafe code before modifying this function or its dependencies.

Source

pub fn add_unicast_address_ipv6( &self, address: Ipv6Addr, prefix_length: u8, ) -> Option<MIB_UNICASTIPADDRESS_ROW>

Adds an IPv6 unicast address to the network interface.

This function creates a new MIB_UNICASTIPADDRESS_ROW with the provided IPv6 address and prefix length, and then calls the CreateUnicastIpAddressEntry Windows API function to add the unicast address to the network interface. On success, it returns Some(MIB_UNICASTIPADDRESS_ROW); otherwise, it sets the last error and returns None.

§Arguments

address - The IPv6 address to assign to the network interface.
prefix_length - The subnet prefix length for the IPv6 address.

§Returns

Option<MIB_UNICASTIPADDRESS_ROW> - Returns Some(MIB_UNICASTIPADDRESS_ROW) if the unicast address is successfully added to the network interface, or None if the operation fails.

§Safety

This function uses unsafe Windows API calls (InitializeUnicastIpAddressEntry and CreateUnicastIpAddressEntry). The function takes care of initializing the MIB_UNICASTIPADDRESS_ROW struct and ensuring that the arguments and struct fields are properly set before making the API calls. However, any changes to this function or the underlying Windows APIs could introduce potential safety issues. Ensure that you understand the risks and consequences of using unsafe code before modifying this function or its dependencies.

Source

pub fn delete_unicast_address(address: &MIB_UNICASTIPADDRESS_ROW) -> bool

Removes a unicast IP address from the network adapter using a reference to a MIB_UNICASTIPADDRESS_ROW.

This function calls the DeleteUnicastIpAddressEntry Windows API function to remove the unicast IP address from the network adapter. On success, it returns true; otherwise, it sets the last error and returns false.

§Arguments

address - A reference to a MIB_UNICASTIPADDRESS_ROW.

§Returns

bool - Returns true if the unicast IP address is successfully removed from the network adapter, or false if the operation fails.

§Safety

This function contains unsafe code as it calls the DeleteUnicastIpAddressEntry Windows API function, which is an unsafe operation due to the use of raw pointers. The caller must ensure that the provided address reference is valid and correctly initialized to avoid any undefined behavior.

Source

pub fn reset_unicast_addresses(&self) -> bool

Removes all unicast addresses associated with the network interface.

§Returns

bool: true if successful, false otherwise.

§Safety

This function uses unsafe Windows API calls to get and delete unicast IP addresses. The caller should ensure that the network interface is properly configured before calling this function.

Source

pub fn delete_unicast_address_ipv4(&self, address: Ipv4Addr) -> bool

Removes the specified IPv4 address from the network interface.

§Arguments

address: Ipv4Addr to remove

§Returns

bool: true if successful, false otherwise.

§Safety

This function uses unsafe Windows API calls to get and delete unicast IP address entries. The caller should ensure that the provided IPv4 address is valid and that the network interface is properly configured before calling this function.

Source

pub fn delete_unicast_address_ipv6(&self, address: Ipv6Addr) -> bool

Removes the specified IPv6 address from the network interface.

§Arguments

address: Ipv6Addr to remove

§Returns

bool: true if successful, false otherwise.

§Safety

This function uses unsafe Windows API calls to get and delete unicast IP address entries. The caller should ensure that the provided IPv6 address is valid and that the network interface is properly configured before calling this function.

Source §

impl IphlpNetworkAdapterInfo

Source

pub fn add_default_gateway_ipv4( &self, address: Ipv4Addr, ) -> Option<MIB_IPFORWARD_ROW2>

Adds a default IPv4 gateway to the network interface.

§Arguments

address: Default gateway IPv4 address

§Returns

Option<MIB_IPFORWARD_ROW2>: Some(MIB_IPFORWARD_ROW2) on success, None on failure

§Safety

This function calls unsafe Windows API functions (InitializeIpForwardEntry, SetLastError, and CreateIpForwardEntry2). Make sure to handle errors and exceptions properly when using this function.

Source

pub fn add_default_gateway_ipv6( &self, address: Ipv6Addr, ) -> Option<MIB_IPFORWARD_ROW2>

Adds a default IPv6 gateway to the network interface.

§Arguments

address: Default gateway IPv6 address

§Returns

Option<MIB_IPFORWARD_ROW2>: Some(MIB_IPFORWARD_ROW2) on success, None on failure

§Safety

This function uses FFI to interact with the Windows API, specifically the InitializeIpForwardEntry, CreateIpForwardEntry2, and SetLastError functions. It is the caller’s responsibility to ensure that the library containing these functions is properly loaded and the FFI definitions are correct.

Source

pub fn assign_default_gateway_ipv4( &self, metric: u32, ) -> Option<MIB_IPFORWARD_ROW2>

Configures the network interface as a default IPv4 gateway with the specified metric.

§Arguments

metric: Network metric (priority), defaults to 0

§Returns

Option<MIB_IPFORWARD_ROW2>: Some(MIB_IPFORWARD_ROW2) on success, None on failure

§Safety

This function uses unsafe Windows API calls to initialize and create IP forward entries. The caller should ensure that the provided metric is a valid network metric and that the network interface is properly configured before calling this function.

Source

pub fn assign_default_gateway_ipv6( &self, metric: u32, ) -> Option<MIB_IPFORWARD_ROW2>

Configures the network interface as a default IPv6 gateway with the specified metric.

§Arguments

metric: Network metric (priority), defaults to 0

§Returns

Option<MIB_IPFORWARD_ROW2>: Some(MIB_IPFORWARD_ROW2) on success, None on failure

§Safety

This function uses unsafe Windows API calls to initialize and create IP forward entries. The caller should ensure that the provided metric is a valid network metric and that the network interface is properly configured before calling this function.

Source §

impl IphlpNetworkAdapterInfo

Source

pub fn if_index(&self) -> u32

Returns the index of the IPv4 interface.

§Examples

let if_index = adapter_info.if_index();

Source

pub fn ipv6_if_index(&self) -> u32

Returns the interface index for the IPv6 IP address. This member is zero if IPv6 is not available on the interface.

§Examples

let ipv6_if_index = adapter_info.ipv6_if_index();

Source

pub fn adapter_name(&self) -> &String

Returns a reference to the name of the adapter. Unlike an adapter’s friendly name, the adapter name specified in adapter_name_ is permanent and cannot be modified by the user.

§Examples

let adapter_name = adapter_info.adapter_name();

Source

pub fn true_adapter_name(&self) -> &GuidWrapper

Returns a reference to the name of the underlying hardware adapter.

§Examples

let true_adapter_name = adapter_info.true_adapter_name();

Source

pub fn description(&self) -> &String

Returns a reference to the description for the adapter.

§Examples

let description = adapter_info.description();

Source

pub fn friendly_name(&self) -> &String

Returns a reference to the user-friendly name for the adapter.

§Examples

let friendly_name = adapter_info.friendly_name();

Source

pub fn unicast_address_list(&self) -> &Vec<IpAddr>

Returns a reference to the list of IP unicast addresses for the adapter.

§Examples

let unicast_address_list = adapter_info.unicast_address_list();

Source

pub fn dns_server_address_list(&self) -> &Vec<IpAddr>

Returns a reference to the list of DNS server addresses for the adapter.

§Examples

let dns_server_address_list = adapter_info.dns_server_address_list();

Source

pub fn gateway_address_list(&self) -> &Vec<IpGatewayInfo>

Returns a reference to the list of gateways for the adapter.

§Examples

let gateway_address_list = adapter_info.gateway_address_list();

Source

pub fn physical_address(&self) -> &MacAddress

Returns a reference to the Media Access Control (MAC) address for the adapter.

§Examples

let physical_address = adapter_info.physical_address();

Source

pub fn mtu(&self) -> u16

Returns the maximum transmission unit (MTU) size, in bytes.

§Examples

let mtu = adapter_info.mtu();

Source

pub fn if_type(&self) -> u32

Returns the interface type as defined by the Internet Assigned Names Authority (IANA). Possible values for the interface type are listed in the Ipifcons.h header file.

§Examples

let if_type = adapter_info.if_type();

Source

pub fn transmit_link_speed(&self) -> u64

Returns the current speed in bits per second of the transmit link for the adapter.

§Examples

let transmit_link_speed = adapter_info.transmit_link_speed();

Source

pub fn receive_link_speed(&self) -> u64

Returns the current speed in bits per second of the receive link for the adapter.

§Examples

let receive_link_speed = adapter_info.receive_link_speed();

Source

pub fn luid(&self) -> &IfLuid

Returns the interface LUID for the adapter address.

§Examples

let luid = adapter_info.luid();

Source

pub fn media_type(&self) -> &NDIS_MEDIUM

Returns the NDIS media type for the interface. This member can be one of the values from the NDIS_MEDIUM enumeration type defined in the Ntddndis.h header file.

§Examples

let media_type = adapter_info.media_type();

Source

pub fn physical_medium_type(&self) -> &NDIS_PHYSICAL_MEDIUM

Returns the NDIS physical medium type. This member can be one of the values from the NDIS_PHYSICAL_MEDIUM enumeration type defined in the Ntddndis.h header file.

§Examples

let physical_medium_type = adapter_info.physical_medium_type();

Source

pub fn true_medium_type(&self) -> &NDIS_PHYSICAL_MEDIUM

If physical_medium_type_ is NdisPhysicalMediumUnspecified (virtual network interface on top of the real one), this one may contain real physical media.

§Examples

let true_medium_type = adapter_info.true_medium_type();

Source

pub fn ndis_wan_ip_link(&self) -> &MacAddress

Returns the NDISWANIP associated MAC address.

§Examples

let ndis_wan_ip_link = adapter_info.ndis_wan_ip_link();

Source

pub fn ndis_wan_ipv6_link(&self) -> &MacAddress

Returns the NDISWANIPV6 associated MAC address.

§Examples

let ndis_wan_ipv6_link = adapter_info.ndis_wan_ipv6_link();

Source §

impl IphlpNetworkAdapterInfo

Source

pub fn add_ndp_entry_ipv4( &self, address: Ipv4Addr, hw_address: [u8; 6], ) -> Option<MIB_IPNET_ROW2>

Adds an IPv4 NDP entry for the network interface.

§Arguments

address: Ipv4Addr
hw_address: [u8; 6] hardware address

§Returns

Option<MIB_IPNET_ROW2>: Some with a MIB_IPNET_ROW2 if successful, None otherwise.

§Safety

This function uses unsafe Windows API calls to create an IP Net entry. The caller should ensure that the provided IPv4 address and hardware address are valid and that the network interface is properly configured before calling this function.

Source

pub fn add_ndp_entry_ipv6( &self, address: Ipv6Addr, hw_address: [u8; 6], ) -> Option<MIB_IPNET_ROW2>

Adds an IPv6 NDP entry for the network interface.

§Arguments

address: Ipv6Addr
hw_address: [u8; 6] hardware address

§Returns

Option<MIB_IPNET_ROW2>: Some with a MIB_IPNET_ROW2 if successful, None otherwise.

§Safety

This function uses unsafe Windows API calls to create an IP Net entry. The caller should ensure that the provided IPv6 address and hardware address are valid and that the network interface is properly configured before calling this function.

Source

pub fn delete_ndp_entry(address: &MIB_IPNET_ROW2) -> bool

Removes an NDP entry by a MIB_IPNET_ROW2 reference.

§Arguments

address: A reference to MIB_IPNET_ROW2

§Returns

bool: true if successful, false otherwise.

§Safety

This function uses unsafe Windows API calls to delete an IP Net entry. The caller should ensure that the provided MIB_IPNET_ROW2 reference is valid and points to an existing NDP entry before calling this function.

Source §

impl IphlpNetworkAdapterInfo

Source

pub fn add_routes_ipv4( &self, ips: Vec<IpNetwork>, ) -> VecDeque<MIB_IPFORWARD_ROW2>

Configures IPv4 network interface routes (Wireguard AllowedIps parameter).

§Arguments

ips: Vec of IpNetwork (Ipv4Network or Ipv6Network) subnets to configure

§Returns

VecDeque<MIB_IPFORWARD_ROW2>: VecDeque of MIB_IPFORWARD_ROW2 on success

§Safety

This function uses unsafe Windows API calls to initialize and create IP forward entries. The caller should ensure that the provided IPv4/IPv6 subnets are valid and that the network interface is properly configured before calling this function.

Source

pub fn add_routes_ipv6( &self, ips: Vec<IpNetwork>, ) -> VecDeque<MIB_IPFORWARD_ROW2>

Configures IPv6 network interface routes (Wireguard AllowedIps parameter).

§Arguments

ips: Vec of IpNetwork (Ipv4Network or Ipv6Network) subnets to configure

§Returns

VecDeque<MIB_IPFORWARD_ROW2>: VecDeque of MIB_IPFORWARD_ROW2 on success

§Safety

This function uses unsafe Windows API calls to initialize and create IP forward entries. The caller should ensure that the provided IPv4/IPv6 subnets are valid and that the network interface is properly configured before calling this function.

Source

pub fn delete_route(address: &MIB_IPFORWARD_ROW2) -> bool

Deletes routing table entry by MIB_IPFORWARD_ROW2 reference.

§Arguments

address: Reference to MIB_IPFORWARD_ROW2

§Returns

bool: true if successful, false otherwise

§Safety

This function uses an unsafe Windows API call to delete IP forward entries. The caller should ensure that the provided MIB_IPFORWARD_ROW2 reference is valid before calling this function.

Source

pub fn delete_routes(addresses: &mut [MIB_IPFORWARD_ROW2]) -> bool

Deletes routing table entries by MIB_IPFORWARD_ROW2 references.

§Arguments

addresses: Vec of MIB_IPFORWARD_ROW2 references

§Returns

bool: true if successful, false otherwise

§Safety

This function uses an unsafe Windows API call to delete IP forward entries. The caller should ensure that the provided MIB_IPFORWARD_ROW2 reference is valid before calling this function.

Source

pub fn reset_adapter_routes(&self) -> bool

Removes all routing table entries associated with the network interface.

§Returns

bool: true if successful, false otherwise

§Safety

This function uses unsafe Windows API calls to get the IP forward table, delete IP forward entries, and free the MIB table. The caller should ensure that the network interface is properly configured before calling this function.

Source §

impl IphlpNetworkAdapterInfo

Source

pub fn get_external_network_connections() -> Vec<IphlpNetworkAdapterInfo>

Returns a list of network interfaces which:

Have at least one unicast address assigned
Operational (IfOperStatusUp)
Not software loopback

§Returns

Vec<IphlpNetworkAdapterInfo>: A vector of IphlpNetworkAdapterInfo objects.

§Safety

This function uses unsafe Windows API calls to get the network interface information. The caller should ensure that the returned IphlpNetworkAdapterInfo objects are not used after the corresponding network interfaces have been removed or disabled.

Source

pub fn get_connection_by_luid(luid: IfLuid) -> Option<IphlpNetworkAdapterInfo>

Finds a network interface by the provided LUID.

§Arguments

luid - An IfLuid to look up.

§Returns

Option<IphlpNetworkAdapterInfo> - An optional IphlpNetworkAdapterInfo class instance.

§Safety

This function uses unsafe Windows API calls to get the network interface information. The caller should ensure that the returned IphlpNetworkAdapterInfo objects are not used after the corresponding network interfaces have been removed or disabled.

Source

pub fn get_connection_by_hw_address( address: &MacAddress, ) -> Option<IphlpNetworkAdapterInfo>

Finds network interface by provided hardware address.

§Arguments

address - A MacAddress to lookup.

§Returns

Option<IphlpNetworkAdapterInfo> - An optional IphlpNetworkAdapterInfo object.

§Safety

This function uses unsafe Windows API calls to get the network interface information. The caller should ensure that the returned IphlpNetworkAdapterInfo objects are not used after the corresponding network interfaces have been removed or disabled.

Source

pub fn get_connection_by_guid(guid: &str) -> Option<IphlpNetworkAdapterInfo>

Finds network interface by provided GUID.

§Arguments

guid - A &str containing the GUID to lookup.

§Returns

Option<IphlpNetworkAdapterInfo> - An optional IphlpNetworkAdapterInfo object.

§Safety

This function uses unsafe Windows API calls to get the network interface information. The caller should ensure that the returned IphlpNetworkAdapterInfo objects are not used after the corresponding network interfaces have been removed or disabled.

Source §

impl IphlpNetworkAdapterInfo

Source

pub unsafe fn new( address: const IP_ADAPTER_ADDRESSES_LH, if_row: const MIB_IF_ROW2, ) -> Self

Constructs a new IphlpNetworkAdapterInfo instance from raw pointers to IP_ADAPTER_ADDRESSES_LH and MIB_IF_ROW2 structures.

This method is marked as unsafe because it dereferences raw pointers, which can lead to undefined behavior if not used correctly.

§Safety

The caller must ensure that address and if_row are valid pointers to IP_ADAPTER_ADDRESSES_LH and MIB_IF_ROW2 structures, respectively, and that the structures remain valid for the duration of the method call.

§Arguments

address - A pointer to an IP_ADAPTER_ADDRESSES_LH structure containing information about the network adapter.
if_row - A pointer to a MIB_IF_ROW2 structure containing information about the network interface.

§Examples

use my_crate::IphlpNetworkAdapterInfo;
use my_crate::{IP_ADAPTER_ADDRESSES_LH, MIB_IF_ROW2};

unsafe {
    let address = /* ... */;
    let if_row = /* ... */;

    let network_adapter_info = IphlpNetworkAdapterInfo::new(address, if_row);
}

Source

pub fn set_friendly_name( &mut self, friendly_name: impl Into<String>, ) -> Result<()>

Sets the friendly name of the network adapter.

This function sets the friendly name of the network adapter by updating the Windows registry. The registry key for the adapter is located at: SYSTEM\CurrentControlSet\Control\Network\{4D36E972-E325-11CE-BFC1-08002BE10318}\{adapter_name}\Connection.