C++ CNdisApi

SetAdaptersStartupMode

static BOOL CNdisApi::SetAdaptersStartupMode ( DWORD dwAdaptersStartupMode );

Return Value:
TRUE if call was successful, FALSE otherwise

Parameters:
dwAdaptersStartupMode
must be a combination of the XXX_LISTEN or XXX_TUNNEL flags:

  • MSTCP_FLAG_SENT_TUNNEL – queue all packets sent from MSTCP to network interface. Original packet dropped.
  • MSTCP_FLAG_RECV_TUNNEL – queue all packets indicated by network interface to MSTCP. Original packet dropped.
  • MSTCP_FLAG_SENT_LISTEN – queue all packets sent from MSTCP to network interface. Original packet goes ahead.
  • MSTCP_FLAG_RECV_LISTEN – queue all packets indicated by network interface to MSTCP. Original packet goes ahead.
  • MSTCP_FLAG_FILTER_DIRECT – In promiscuous mode 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 network interface current MAC will never reach MSTCP.

By default, loopback packets are passed to original MSTCP handlers without processing, to change this behavior use these additional flags below:

  • MSTCP_FLAG_LOOPBACK_FILTER – Pass loopback packet for processing by helper driver routines (redirected to user-mode if requested).
  • MSTCP_FLAG_LOOPBACK_BLOCK – Silently drop loopback packets, this flag is recommended for usage with promiscuous mode to avoid multiply processing of one packet.

Remarks:
This routine sets the default mode to be applied on each adapter when it appears in the system. It can be useful when you need to prevent a network interface to start operating before your application has started. The 3.6.2 SDK’s deployment guidance says to reboot for this startup setting to take effect.

Stored configuration: These APIs write or read the StartupMode REG_DWORD in the standard driver’s HKLM\SYSTEM\CurrentControlSet\Services\ndisrd\Parameters key; they do not issue an IOCTL. The getter reports stored startup configuration, not the active mode of an adapter. A stored zero, a missing value and a failed registry operation all return 0. The setter requires registry write permission, and the getter also opens/creates the key through RegCreateKey.

The reboot guidance is stated in the SDK comment; the public user-mode implementation does not show the driver’s adoption timing. For immediate per-adapter mode changes, use SetAdapterMode. See the pinned startup-mode implementation and guidance.