NdisMSetAttributesEx function (ndis.h)

  • Article

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisMSetAttributesEx informs the NDIS library about significant features of the caller's NIC or virtual NIC during initialization.

Syntax

void NdisMSetAttributesEx(
  [in]           NDIS_HANDLE         MiniportAdapterHandle,
  [in]           NDIS_HANDLE         MiniportAdapterContext,
  [in, optional] UINT                CheckForHangTimeInSeconds,
  [in]           ULONG               AttributeFlags,
  [in, optional] NDIS_INTERFACE_TYPE AdapterType
);

Parameters

[in] MiniportAdapterHandle

Specifies the handle input to MiniportInitialize.

[in] MiniportAdapterContext

Specifies a handle for a resident context area allocated by MiniportInitialize.

[in, optional] CheckForHangTimeInSeconds

Specifies the interval, in seconds, at which NDIS should call the MiniportCheckForHang function. If a driver has not responded to an OID request or sent request within two successive calls to MiniportCheckForHang, NDIS can call the driver's MiniportReset function.

The actual interval that NDIS uses when calling MiniportCheckForHang is always a multiple of 2 seconds. For example, if you specify 5 seconds, the actual interval will be approximately 4 seconds.

Specifying zero for this parameter indicates that NDIS should call MiniportCheckForHang at the NDIS default 2-second interval.

If the caller sets NDIS_ATTRIBUTE_DESERIALIZE in AttributeFlags, NDIS does not queue pending sends for the miniport driver. Instead, such a deserialized driver must manage its own queuing of subsequent send requests internally whenever it has insufficient resources to transmit an incoming send immediately.

[in] AttributeFlags

Specifies a bitmask that can be set with one or more (ORed) of the following flags:

  • NDIS_ATTRIBUTE_BUS_MASTER
    Set if the caller's NIC is a bus-master DMA device.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Set if the caller is a deserialized miniport driver.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Set if NDIS should not attempt to time-out pending send packets that it holds queued to the caller. Intermediate drivers should set this flag, but NIC drivers should not.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Set if NDIS should not attempt to time-out pending query and set requests that it holds queued to the caller. Intermediate drivers should set this flag, but NIC drivers should not.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Set if the caller is an intermediate driver.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Set if NDIS should not call a Token Ring NIC driver's MiniportReset function if Token Ring errors are indicated.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Set if NDIS should not call a driver's MiniportHalt function before the system transitions to a low-power (sleeping) state. Drivers that rely on hardware-maintained state should not set this flag.

    Note   Setting this flag disables the Allow the computer to turn off this device to save power check box in the Power Management Tab of the Properties dialog box for the network interface card (NIC). Power management is disabled even if the NIC is capable of power management.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Set if the driver can handle removal of its NIC without user notification. Such a driver exports a MiniportPnPEventNotify function. System support for NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK is available in Windows XP and later operating systems.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Set by a driver that can support both connection-oriented and connectionless devices to indicate that the device is a connectionless device. System support for NDIS_ATTRIBUTE_NOT_CO_NDIS is available in Windows XP and later operating systems.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Set by a driver that uses NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe, and NdisQueryBufferSafe exclusively to access system virtual addresses for send packet buffers. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS is also set by a driver that exclusively uses physical addresses to access such buffers. Setting NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS can improve performance since the operating system will not have to map send packet buffers to system virtual addresses. System support for NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS is available in Windows XP and later versions.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Set by a CoNDIS miniport driver that does not provide TAPI services. Setting NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO prevents NDIS from binding the miniport driver to the NDIS TAPI proxy driver (NDPROXY). By default, NDIS binds NDPROXY to all CoNDIS miniport drivers.

[in, optional] AdapterType

Specifies the I/O bus interface type of the caller's NIC, which usually is the type of I/O bus on which the NIC is connected, as one of the following:

  • NdisInterfaceInternal
    Specifies a host-specific internal interface.

  • NdisInterfaceIsa
    Specifies the ISA interface.

  • NdisInterfaceEisa
    Specifies the extended ISA (EISA) interface.

  • NdisInterfaceMca
    This refers to the MCA bus, which is no longer supported.

  • NdisInterfaceTurboChannel
    Specifies the Turbo Channel interface.

  • NdisInterfacePci
    Specifies the Peripheral Component Interconnect (PCI) interface.

  • NdisInterfacePcMcia
    Specifies the Personal Computer Memory Card International Association (PC Card) interface.

This parameter is irrelevant for intermediate drivers, which should pass zero for this argument to NdisMSetAttributesEx.

Return value

None

Remarks

A MiniportInitialize function must call NdisMSetAttributesEx(or NdisMSetAttributes) before calling any other NdisMRegisterXxx or NdisXxx function that depends on the information supplied to NdisMSetAttributesEx. For example, a NIC driver's call to NdisMAllocateMapRegisters will fail if MiniportInitialize has not yet called NdisMSetAttributesEx with the AttributeFlags set with NDIS_ATTRIBUTE_BUS_MASTER.

Intermediate drivers must call NdisMSetAttributesEx, rather than NdisMSetAttributes, and they must set NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER in the AttributeFlags. Setting this flag causes NDIS to treat an intermediate driver as a full-duplex miniport driver, which prevents rare but intermittent deadlocks from occurring in the intermediate driver. Consequently, every intermediate driver must be capable of handling concurrent sends and indications.

Deserialized drivers also must call NdisMSetAttributesEx, and they must set NDIS_ATTRIBUTE_DESERIALIZE in the AttributeFlags. NDIS does not maintain a send-packet queue for a deserialized driver, nor does NDIS serialize calls to a such a driver's MiniportXxx functions. A deserialized driver makes itself responsible for the following:

  • Accepting all incoming send requests
  • Queuing incoming send packets internally if necessary, as, for example, if a deserialized NIC driver currently has insufficient resources available to transmit an incoming send packet immediately
  • Synchronizing access to its internal queue(s) as necessary among the driver's routines
  • Completing all requested sends asynchronously by subsequently calling NdisMSendComplete with each protocol-supplied packet descriptor passed in to its Miniport(Co)Send(Packets) function

NDIS assumes that all connection-oriented miniports are deserialized drivers, regardless of the AttributeFlags that they pass to NdisMSetAttributesEx. That is, any driver that calls NdisMRegisterMiniport with 0x05 as the MajorNdisVersion must be a deserialized miniport driver.

Serialized NIC drivers can call either of these functions from MiniportInitialize, but NdisMSetAttributes does not allow its caller to adjust the interval at which a NIC driver's MiniportCheckForHang and/or MiniportReset function(s) are called.

The value of CheckForHangTimeInSeconds determines the NDIS library's time-out interval on sends, if any, and requests that it holds queued to the caller. By default, NDIS times out queued sends (only for serialized drivers) and requests at twice the check-for-hang interval, after which it calls the MiniportReset function, unless the driver sets AttributeFlags with NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT when it calls NdisMSetAttributesEx. Intermediate drivers should set these flags when calling NdisMSetAttributesEx because such a driver cannot determine or control when the underlying NIC driver will process sends and requests.

NIC drivers should not set the NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT flags, although NDIS will honor such a specification by a serialized NIC driver. However, NIC drivers can adjust the time-out interval at which their MiniportReset functions are called by specifying an explicit CheckForHangTimeInSeconds. For example, a NIC driver that emulates Ethernet over a modem might not complete every packet within the default time-out interval of the NDIS library. Whenever a packet appeared to time out on such a NIC, NDIS would assume that the NIC was no longer operating correctly and call the driver's MiniportReset function. For the driver of such a NIC, calling NdisMSetAttributesEx with a CheckForHangTimeInSeconds set to something greater than two both prevents unnecessary resets and extends the interval at which its MiniportCheckForHang function, if any, is called to test the operational state of the NIC.

An intermediate driver must set the NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND flag. Setting this flag prevents NDIS from halting the driver before the system transitions to a low-power (sleeping) state.

A legacy miniport driver that manages a non-PnP-aware NIC can set the NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND flag to prevent NDIS from halting the driver before the system transitions to a low-power state. If the miniport driver sets this flag, NDIS queries the miniport driver with OID_PNP_CAPABILITIES even though the bus driver for the miniport driver's NIC may have indicated that the NIC is not PM-aware. The miniport driver must succeed the OID_PNP_CAPABILITIES request with NDIS_STATUS_SUCCESS. In the NDIS_PM_WAKE_UP_CAPABILITIES structure returned by this OID, the miniport driver must also specify a device power state of NdisDeviceStateUnspecified for each wake-up capability. When the system transitions to a low-power state, NDIS will not call such a miniport driver's MiniportHalt function. Before the system transitions to a lower-power state, the miniport driver must save any hardware context that it maintains. On receiving an OID_PNP_SET_POWER request to the D3 state, the miniport driver must set its NIC to the appropriate state for the low-power state. On receiving an OID_PNP_SET_POWER request to the D0 state, the miniport driver must set its NIC to the appropriate state for the working state.

A miniport driver that supports surprise removal of its device (removal without notification through the user interface) must set NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK. Doing so causes NDIS to call the driver's MiniportPnPEventNotify function with PnPEvent set to NdisDevicePnPEventSurpriseRemoved when the miniport's device is removed without notification. In addition, setting NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK suppresses the display of a warning dialog box that asks the user to stop the device before removing it.

A miniport driver that can support both connectionless and connection-oriented devices must set NDIS_ATTRIBUTE_NOT_CO_NDIS if its device is a connectionless device. Otherwise, NDIS will mistakenly assume that its device is connection-oriented since the driver registers connection-oriented miniport driver functions with NdisMRegisterMiniport.

In general, a NIC driver must call NdisMSetAttributesEx before it calls any NdisXxx function that claims hardware resources in the registry for its NIC, because NDIS must have the AttributeFlags value before such a call is made and because the driver usually needs the memory at MiniportAdapterContext to store information for these calls. This restriction implies that a NIC driver's MiniportInitialize function cannot call the following NdisXxx before it calls NdisMSetAttributesEx:

However, before calling NdisMSetAttributesEx, any driver's MiniportInitialize function can call the Ndis..Configuration functions to retrieve configuration information installed in the registry. MiniportInitialize also can call the bus-type-specific NdisReadXxx functions, such as NdisReadPciSlotInformation, as long as the installed registry entry for the driver's interface type matches the bus-type-specific NdisReadXxxMiniportInitialize calls.

The MiniportAdapterContext handle supplied to NdisMSetAttributesEx becomes an input parameter to all MiniportXxx functions that were registered, along with MiniportInitialize, in the call to NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport. Usually, this handle is a pointer to resident memory, allocated by MiniportInitialize, in which the driver maintains NIC-specific run-time state.

  • Target platform: Universal
  • Version: Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMSetMiniportAttributesinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Requirements

Requirement Value
Header ndis.h (include Ndis.h)
Library Ndis.lib
IRQL PASSIVE_LEVEL

See also