Struct ndisapi_rs::Ndisapi

pub struct Ndisapi { /* private fields */ }

The Ndisapi struct represents an instance of the NDIS filter driver that provides access to network adapters and packets.

This struct is used to communicate with the NDIS filter driver and access its functionalities. It contains a single field, driver_handle, which represents a handle to the driver. This handle is used to perform operations such as reading and writing packets, setting filters, and getting information about network adapters.

To use Ndisapi, you should first create an instance of the struct by calling the Ndisapi::new() function. This will return a Result that contains an instance of Ndisapi if the operation was successful, or an error if it failed. Once you have an instance of Ndisapi, you can call its methods to perform various network-related operations.

For example, you can use the Ndisapi::read_packets() method to read packets from the network adapter, or the Ndisapi::send_packets_to_adapter() method to write packets to the network adapter. You can also use the Ndisapi::set_packet_filter_table() method to set a filter that specifies which packets should be captured or dropped.

Implementations

impl Ndisapi

pub fn get_adapter_mode(&self, adapter_handle: HANDLE) -> Result<FilterFlags>

This method takes an adapter handle as an argument and returns a Result containing the FilterFlags enum for the selected network interface. If an error occurs, the GetLastError function is called to retrieve the error and is then converted into a Result::Err variant.

Arguments

• adapter_handle - A HANDLE representing the network interface for which the packet filter mode should be queried.

Returns

• Result<FilterFlags> - A Result containing the FilterFlags enum for the selected network interface if the query was successful, or an error if it failed.

pub fn get_hw_packet_filter(&self, adapter_handle: HANDLE) -> Result<u32>

This method takes an adapter handle as an argument and returns a Result containing a u32 value representing the hardware packet filter for the specified network interface. If an error occurs, it will be propagated as a Result::Err variant.

Arguments

• adapter_handle - A HANDLE representing the network interface for which the hardware packet filter should be queried.

Returns

• Result<u32> - A Result containing a u32 value representing the hardware packet filter for the specified network interface if the query was successful, or an error if it failed.

pub fn get_ras_links( &self, adapter_handle: HANDLE, ras_links: &mut RasLinks ) -> Result<()>

This method takes an adapter handle and a mutable reference to a RasLinks struct as arguments. It queries the active WAN connections from the NDIS filter driver and updates the ras_links argument with the received information. If an error occurs, it will be propagated as a Result::Err variant.

Arguments

• adapter_handle - A HANDLE representing the network interface for which the active WAN connections should be queried.
• ras_links - A mutable reference to a RasLinks struct that will be updated with the information about active WAN connections.

Returns

• Result<()> - A Result containing an empty tuple if the query was successful, or an error if it failed.

pub fn get_tcpip_bound_adapters_info(&self) -> Result<Vec<NetworkAdapterInfo>>

This method retrieves information about network interfaces that available to NDIS filter driver. It returns a Result containing a vector of NetworkAdapterInfo structs, which contain detailed information about each network interface.

Returns

• Result<Vec<NetworkAdapterInfo>> - A Result containing a vector of NetworkAdapterInfo structs representing the available network interfaces if the query was successful, or an error if it failed.

pub fn get_version(&self) -> Result<Version>

This method retrieves the version of the NDIS filter driver currently running on the system. It returns a Result containing a Version struct with the major, minor, and revision numbers of the driver version.

Returns

• Result<Version> - A Result containing a Version struct representing the NDIS filter driver version if the query was successful, or an error if it failed.

pub fn ndis_get_request<T>( &self, oid_request: &mut PacketOidData<T> ) -> Result<()>

This function is used to obtain various parameters of the network adapter, such as the dimension of the internal buffers, the link speed, or the counter of corrupted packets. The constants that define the operations are declared in the file ntddndis.h.

Type Parameters

• T: The type of data to be queried from the network adapter.

Arguments

• oid_request: A mutable reference to a PacketOidData<T> struct that specifies the adapter handle and the operation to perform.

Returns

• Result<()> - A Result indicating whether the query operation was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn ndis_set_request<T>(&self, oid_request: &PacketOidData<T>) -> Result<()>

This function is used to set various parameters of the network adapter, such as the dimension of the internal buffers, the link speed, or the counter of corrupted packets. The constants that define the operations are declared in the file ntddndis.h.

Type Parameters

• T: The type of data to be set for the network adapter.

Arguments

• oid_request: A reference to a PacketOidData<T> struct that specifies the adapter handle and the operation to perform.

Returns

• Result<()> - A Result indicating whether the set operation was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn set_adapter_list_change_event(&self, event_handle: HANDLE) -> Result<()>

The user application should create a Win32 event (with the CreateEvent API call) and pass the event handle to this function. The helper driver will signal this event when the NDIS filter adapter’s list changes, for example, when a network card is plugged/unplugged, a network connection is disabled/enabled, or other similar events.

Arguments

• event_handle: A HANDLE to a Win32 event created by the user application.

Returns

• Result<()> - A Result indicating whether setting the event was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn set_adapter_mode( &self, adapter_handle: HANDLE, flags: FilterFlags ) -> Result<()>

Sets the packet filter mode for the selected network interface.

Arguments

• adapter_handle: A HANDLE to the network interface (obtained via call to get_tcpip_bound_adapters_info).
• flags: A FilterFlags value representing the combination of packet filter mode flags.
• MSTCP_FLAG_SENT_TUNNEL – Queue all packets sent from MSTCP to the network interface. Original packet dropped.
• MSTCP_FLAG_RECV_TUNNEL – Queue all packets indicated by the network interface to MSTCP. Original packet dropped.
• MSTCP_FLAG_SENT_LISTEN – Queue all packets sent from MSTCP to the network interface. Original packet goes ahead.
• MSTCP_FLAG_RECV_LISTEN – Queue all packets indicated by the network interface to MSTCP. Original packet goes ahead.
• MSTCP_FLAG_FILTER_DIRECT – In promiscuous mode, the TCP/IP stack receives all packets in the Ethernet segment and replies with various ICMP packets. To prevent this, set this flag. All packets with destination MAC different from FF-FF-FF-FF-FF-FF and the network interface’s current MAC will never reach MSTCP.

Returns

• Result<()> - A Result indicating whether setting the adapter mode was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn set_hw_packet_filter( &self, adapter_handle: HANDLE, filter: u32 ) -> Result<()>

This method allows setting the hardware packet filter mode for the specified network interface by calling the ndis_set_request function.

Arguments

• adapter_handle: A HANDLE to the network interface.
• filter: A u32 value representing the packet filter mode.

Returns

• Result<()> - A Result indicating whether setting the hardware packet filter was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn set_hw_packet_filter_event(&self, event_handle: HANDLE) -> Result<()>

This method allows setting a Win32 event that will be signaled by the filter driver when the hardware packet filter for the network interface changes.

Arguments

• event_handle: A HANDLE to the Win32 event created by the user application.

Returns

• Result<()> - A Result indicating whether setting the hardware packet filter event was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn set_wan_event(&self, event_handle: HANDLE) -> Result<()>

This method allows setting a Win32 event that will be signaled by the filter driver when a WAN connection (such as dial-up, DSL, ADSL, etc.) is established or terminated.

Arguments

• event_handle: A HANDLE to the Win32 event created by the user application.

Returns

• Result<()> - A Result indicating whether setting the WAN event was successful or not. On success, returns Ok(()). On failure, returns an error.

pub fn get_intermediate_buffer_pool_size(&self) -> Result<u32>

Retrieves the effective size of the Windows Packet Filter internal intermediate buffer pool.

Returns

• Result<u32> - If the operation is successful, returns Ok(pool_size) where pool_size is the size of the intermediate buffer pool. Otherwise, returns an Err with the error code.

This function retrieves the size of the intermediate buffer pool used by the driver. It uses DeviceIoControl with the IOCTL_NDISRD_QUERY_IB_POOL_SIZE code to perform the operation.

impl Ndisapi

pub fn add_secondary_fast_io<const N: usize>( &self, fast_io_section: &mut FastIoSection<N> ) -> Result<()>

This function adds a secondary Fast I/O shared memory section to the NDIS filter driver, allowing faster communication between user-mode applications and the driver.

Type Parameters

• N: The size of the Fast I/O shared memory section.

Arguments

• fast_io_section: A mutable reference to a FastIoSection<N> object representing the shared memory section to be added.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn initialize_fast_io<const N: usize>( &self, fast_io_section: &mut FastIoSection<N> ) -> Result<()>

This function initializes the fast I/O mechanism for the NDIS filter driver and submits the initial shared memory section for faster communication between user-mode applications and the driver.

Type Parameters

• N: The size of the Fast I/O shared memory section.

Arguments

• fast_io_section: A mutable reference to a FastIoSection<N> object representing the shared memory section to be submitted.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn read_packets_unsorted<const N: usize>( &self, packets: &mut [IntermediateBuffer; N] ) -> Result<usize>

This function retrieves queued packets from the NDIS filter driver without considering the network interface. It reads packets in an unsorted manner and stores them in the provided buffer.

Type Parameters

• N: The number of packets to read.

Arguments

• packets: A mutable reference to an array of IntermediateBuffer objects, where the read packets will be stored.

Returns

• Result<usize>: If successful, returns Ok(usize) with the number of packets read. Otherwise, returns an error.

pub fn send_packets_to_adapters_unsorted<const N: usize>( &self, packets: &mut [IntermediateBuffer; N], packets_num: usize ) -> Result<usize>

This function forwards packets to the NDIS filter driver in an unsorted manner, which then sends them to the target network interface. The target adapter handle should be set in the IntermediateBuffer.header.adapter_handle field.

Type Parameters

• N: The number of packets to send.

Arguments

• packets: A mutable reference to an array of IntermediateBuffer objects, which contain the packets to be sent.
• packets_num: The number of packets to send from the array.

Returns

• Result<usize>: If successful, returns Ok(usize) with the number of packets sent. Otherwise, returns an error.

pub fn send_packets_to_mstcp_unsorted<const N: usize>( &self, packets: &mut [IntermediateBuffer; N], packets_num: usize ) -> Result<usize>

This function forwards packets to the NDIS filter driver in an unsorted manner, which then sends them to the target protocols layer (MSTCP). The target adapter handle (to be indicated from) should be set in the IntermediateBuffer.header.adapter_handle field.

Type Parameters

• N: The number of packets to send.

Arguments

• packets: A mutable reference to an array of IntermediateBuffer objects, which contain the packets to be sent.
• packets_num: The number of packets to send from the array.

Returns

• Result<usize>: If successful, returns Ok(usize) with the number of packets sent. Otherwise, returns an error.

impl Ndisapi

pub fn get_packet_filter_table<const N: usize>( &self, filter_table: &mut StaticFilterTable<N> ) -> Result<()>

This function retrieves the static filter table from the NDIS filter driver and stores it in the provided filter_table argument.

Type Parameters

• N: The size of the static filter table.

Arguments

• filter_table: A mutable reference to a StaticFilterTable<N> object, which will store the queried static filter table.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn get_packet_filter_table_reset_stats<const N: usize>( &self, filter_table: &mut StaticFilterTable<N> ) -> Result<()>

This function retrieves the static filter table from the NDIS filter driver, stores it in the provided filter_table argument, and resets the filter statistics.

Type Parameters

• N: The size of the static filter table.

Arguments

• filter_table: A mutable reference to a StaticFilterTable<N> object, which will store the queried static filter table.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn get_packet_filter_table_size(&self) -> Result<usize>

This function retrieves the size of the static filter table from the NDIS filter driver.

Returns

• Result<usize>: If successful, returns the size of the static filter table as Ok(usize). Otherwise, returns an error.

pub fn reset_packet_filter_table(&self) -> Result<()>

This function resets the static filter table in the NDIS filter driver, effectively removing all filters from the table.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn set_packet_filter_table<const N: usize>( &self, filter_table: &StaticFilterTable<N> ) -> Result<()>

This function takes a static filter table and sets it as the current filter table in the NDIS filter driver.

Type Parameters

• N: The number of filters in the static filter table.

Arguments

• filter_table: &StaticFilterTable<N>: A reference to the static filter table to be loaded.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

impl Ndisapi

pub fn flush_adapter_packet_queue(&self, adapter_handle: HANDLE) -> Result<()>

This function clears the packet queue associated with the specified network adapter handle in the NDIS filter driver.

Arguments

• adapter_handle: HANDLE: The handle of the network adapter whose packet queue should be flushed.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn get_adapter_packet_queue_size( &self, adapter_handle: HANDLE ) -> Result<u32>

This function retrieves the number of packets currently queued in the packet queue associated with the specified network adapter handle in the NDIS filter driver.

Arguments

• adapter_handle: HANDLE: The handle of the network adapter whose packet queue size should be queried.

Returns

• Result<u32>: If successful, returns Ok(queue_size) where queue_size is the number of packets in the adapter’s packet queue. Otherwise, returns an error.

pub fn read_packet(&self, packet: &mut EthRequest<'_>) -> Result<()>

This function retrieves a single network packet from the NDIS filter driver associated with the specified EthRequest.

Arguments

• packet: &mut EthRequest: A mutable reference to the EthRequest structure that will be filled with the retrieved packet data.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn read_packets<const N: usize>( &self, packets: &mut EthMRequest<'_, N> ) -> Result<usize>

This function retrieves a block of network packets from the NDIS filter driver associated with the specified EthMRequest<N>.

Arguments

• packets: &mut EthMRequest<N>: A mutable reference to the EthMRequest<N> structure that will be filled with the retrieved packet data.

Returns

• Result<usize>: If successful, returns Ok(packet_count) where packet_count is the number of packets read into EthMRequest<N>. Otherwise, returns an error.

pub fn send_packet_to_adapter(&self, packet: &EthRequest<'_>) -> Result<()>

This function sends a single network packet to the NDIS filter driver associated with the specified EthRequest, which will then be passed down the network stack.

Arguments

• packet: &EthRequest: A reference to the EthRequest structure containing the packet data to be sent.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn send_packet_to_mstcp(&self, packet: &EthRequest<'_>) -> Result<()>

This function sends a single network packet to the NDIS filter driver associated with the specified EthRequest, which will then be passed down the network stack to the Microsoft TCP/IP stack.

Arguments

• packet: &EthRequest: A reference to the EthRequest structure containing the packet data to be sent.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn send_packets_to_adapter<const N: usize>( &self, packets: &EthMRequest<'_, N> ) -> Result<()>

This function sends a block of network packets to the NDIS filter driver associated with the specified EthMRequest<N>, which will then be passed down the network stack.

Arguments

• packets: &EthMRequest<N>: A reference to the EthMRequest<N> structure containing the packet data to be sent.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn send_packets_to_mstcp<const N: usize>( &self, packets: &EthMRequest<'_, N> ) -> Result<()>

This function sends a block of network packets to the NDIS filter driver associated with the specified EthMRequest<N>, which will then be passed up the network stack to the Microsoft TCP/IP stack.

Arguments

• packets: &EthMRequest<N>: A reference to the EthMRequest<N> structure containing the packet data to be sent.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

pub fn set_packet_event( &self, adapter_handle: HANDLE, event_handle: HANDLE ) -> Result<()>

This function sets a Win32 event to be signaled by the NDIS filter when it has queued packets available for read on the specified network adapter.

Arguments

• adapter_handle: HANDLE: The handle of the network adapter to associate the event with.
• event_handle: HANDLE: The handle of the Win32 event to be signaled when queued packets are available.

Returns

• Result<()>: If successful, returns Ok(()). Otherwise, returns an error.

impl Ndisapi

pub fn is_ndiswan_ip(adapter_name: impl Into<String>) -> bool

Determines if a given network interface is an NDISWANIP interface.

This function checks if the specified network adapter is an NDISWANIP interface by calling is_ndiswan_interface with the component ID “ms_ndiswanip”.

Arguments

• adapter_name: impl Into<String>: The name of the network adapter to check.

Returns

• bool: Returns true if the interface is an NDISWANIP interface, false otherwise.

pub fn is_ndiswan_ipv6(adapter_name: impl Into<String>) -> bool

Determines if a given network interface is an NDISWANIPV6 interface.

This function checks if the specified network adapter is an NDISWANIPV6 interface by calling is_ndiswan_interface with the component ID “ms_ndiswanipv6”.

Arguments

• adapter_name: impl Into<String>: The name of the network adapter to check.

Returns

• bool: Returns true if the interface is an NDISWANIPV6 interface, false otherwise.

pub fn is_ndiswan_bh(adapter_name: impl Into<String>) -> bool

Determines if a given network interface is an NDISWANBH interface.

This function checks if the specified network adapter is an NDISWANBH interface by calling is_ndiswan_interface with the component ID “ms_ndiswanbh”.

Arguments

• adapter_name: impl Into<String>: The name of the network adapter to check.

Returns

• bool: Returns true if the interface is an NDISWANBH interface, false otherwise.

pub fn get_friendly_adapter_name( adapter_name: impl Into<String> ) -> Result<String>

This function checks if the specified network adapter is an NDISWAN IP, IPv6, or BH interface, and if not, attempts to find the friendly name from the registry.

Arguments

• adapter_name: impl Into<String>: The system-level name of the network adapter to obtain the user-friendly name for.

Returns

• Result<String>: Returns a Result containing the user-friendly name of the network adapter if found, or an error otherwise.

pub fn set_mtu_decrement(&self, mtu_decrement: u32) -> Result<()>

This function sets a parameter in the registry key that the filter driver reads during its initialization. The value set in the registry is subtracted from the actual MTU (Maximum Transmission Unit) when it is requested by the MSTCP (Microsoft TCP/IP) from the network. Because this parameter is read during the initialization of the filter driver, a system reboot is required for the changes to take effect. Requires Administrator permissions.

Arguments

• mtu_decrement: u32 - The value to subtract from the actual MTU.

Returns

• Result<()> - Returns a Result that is Ok(()) if the MTU decrement value is set successfully in the registry, or an error otherwise.

pub fn get_mtu_decrement(&self) -> Option<u32>

This function retrieves the value set by set_mtu_decrement from the registry. Note that if you have not rebooted after calling set_mtu_decrement, the return value is meaningless. If MTUDecrement value is not present in the registry or an error occurred, then None is returned.

Returns

• Option<u32> - Returns an Option containing the MTU decrement value if it is present in the registry and there are no errors, or None otherwise.

pub fn set_adapters_startup_mode(&self, startup_mode: u32) -> Result<()>

This routine sets the default mode to be applied to each adapter as soon as it appears in the system. It can be helpful in scenarios where you need to delay a network interface from operating until your application has started. However, it’s essential to note that this API call requires a system reboot to take effect. Requires Administrator permissions to succeed.

Arguments

• startup_mode: u32 - The default startup mode to be applied to each adapter.

Returns

• Result<()> - Returns a Result indicating whether the operation succeeded or an error occurred.

pub fn get_adapters_startup_mode(&self) -> Option<u32>

Returns the current default filter mode value applied to each adapter when it appears in the system. Note that if you have not rebooted after calling SetAdaptersStartupMode, the return value is meaningless.

Returns

• Option<u32> - Returns the current default startup mode as Some(u32) if the value is present in the registry, or None if the value is not present or an error occurred.

pub fn set_pool_size(&self, pool_size: u32) -> Result<()>

Sets the pool size multiplier for Windows Packet Filter driver in the Windows registry.

This function creates or modifies the PoolSize value in the registry based on the given value. The appropriate registry key is selected depending on the Windows platform (NT/2000/XP or 9x/ME). The resulting internal packet pool size will be equal to 2048 (512 for Windows version before Vista) * PoolSize packets. The maximum effective PoolSize is 10.

Arguments

• pool_size: u32 - The desired pool size multiplier to be set in the registry.

Returns

• Result<()> - If the pool size multiplier is successfully set, returns Ok(()). Otherwise, returns an Err with the error code.

pub fn get_pool_size(&self) -> Option<u32>

Retrieves the pool size multiplier for the Windows Packet Filter driver from the Windows registry.

This function queries the registry for the PoolSize value and returns it. The appropriate registry key is used depending on the Windows platform (NT/2000/XP or 9x/ME). The internal packet pool size is determined by 2048 * PoolSize packets. The maximum effective PoolSize is 10.

Returns

• Option<u32> - The pool size multiplier retrieved from the registry. If the value is not found or an error occurs, returns None.

impl Ndisapi

pub fn new(driver_name: &str) -> Result<Self>

Initializes new Ndisapi instance opening the NDIS filter driver

Arguments

• driver_name - The name of the file representing the NDIS filter driver.

Returns

• Result<Self> - A Result containing the Ndisapi instance if successful, or an error if not.

Examples

use ndisapi_rs::Ndisapi;
let ndisapi = Ndisapi::new("NDISRD").unwrap();

pub fn get_driver_registry_key(&self) -> PCWSTR

Trait Implementations

impl Clone for Ndisapi

fn clone(&self) -> Ndisapi

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ndisapi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Ndisapi

fn drop(&mut self)

Executes the destructor for this type.