Share via


NdisOpenConfigurationEx (Compact 2013)

3/26/2014

NDIS drivers call this function to get a configuration handle that allows access to configuration parameters in the registry.

Syntax

NDIS_STATUS
  NdisOpenConfigurationEx(
    IN PNDIS_CONFIGURATION_OBJECT  ConfigObject,
    OUT PNDIS_HANDLE  ConfigurationHandle
    );

Parameters

  • ConfigurationHandle
    A pointer to a caller-supplied variable in which NdisOpenConfigurationEx returns a handle to a registry key. The registry key identifies the configuration parameters.

Return Value

NdisOpenConfigurationEx returns one of the following status values:

Value

Description

NDIS_STATUS_SUCCESS

NdisOpenConfigurationEx successfully opened the registry key where the driver's configuration parameters are stored.

NDIS_STATUS_RESOURCES

NdisOpenConfigurationEx failed because of insufficient resources.

NDIS_STATUS_FAILURE

NdisOpenConfigurationEx returns NDIS_STATUS_FAILURE if none of the previous values applies.

Remarks

NdisOpenConfigurationEx returns a configuration handle at the ConfigurationHandle parameter. The configuration handle is associated with a registry key that identifies the location of the configuration parameters. The caller can pass the configuration handle to other NDIS configuration functions to read or write information in the registry.

To access the configuration information, use the configuration handle with the following functions:

  • NdisReadConfiguration
    This function returns the value of a named entry of the specified type from the registry, given the handle to an open registry key.
  • NdisWriteConfiguration
    This function writes a caller-supplied value for a specified entry into the registry.

The type of registry data that is associated with the configuration handle depends on the type of handle that the caller passes to NdisOpenConfigurationEx in the NdisHandle member of the NDIS_CONFIGURATION_OBJECT structure that is referenced by the ConfigObject parameter. The handle can identify parameters that are associated with the driver or with an instance of the driver.

If the driver obtained the handle in NdisHandle by calling the NdisMRegisterMiniportDriver function, NdisOpenConfigurationEx provides a handle to the registry location where the miniport driver's configuration parameters are stored. The miniport driver can use the configuration handle until it calls the NdisMDeregisterMiniportDriver function.

If the driver obtained the handle in NdisHandle from the MiniportAdapterHandle parameter of the MiniportInitializeEx function, NdisOpenConfigurationEx provides a handle to the registry location where a miniport adapter's configuration parameters are stored. A miniport driver can pass the configuration handle to the NdisReadNetworkAddress function to retrieve network address information that can be configured by software and administered locally. Miniport drivers can use the configuration handle until NDIS halts the miniport adapter and the MiniportHaltEx function returns.

If the driver obtained the handle in NdisHandle by calling the NdisRegisterProtocolDriver function, NdisOpenConfigurationEx provides a handle to the registry location where the protocol driver's configuration parameters are stored. The protocol driver can use the configuration handle until it calls the NdisDeregisterProtocolDriver function.

If the handle in NdisHandle is a pointer to an NDIS_BIND_PARAMETERS structure that NDIS passed at the BindParameters parameter of the ProtocolBindAdapterEx function, NdisOpenConfigurationEx provides a handle to the registry location where configuration parameters for a protocol binding are stored. Protocol drivers can use the configuration handle until the bind operation is complete.

If the driver obtained the handle in NdisHandle by calling the NdisOpenAdapterEx function, NdisOpenConfigurationEx provides a handle to the registry location where the configuration parameters for a protocol binding are stored. The protocol driver can use the configuration handle until it calls the NdisCloseAdapterEx function.

If a filter driver obtained the handle in NdisHandle by calling the NdisFRegisterFilterDriver function, NdisOpenConfigurationEx provides a handle to the registry location where the filter driver's configuration parameters are stored. Filter drivers can use the configuration handle until they call the NdisFDeregisterFilterDriver function.

If a filter driver obtained the handle in NdisHandle from the NdisFilterHandle parameter of the FilterAttach function, NdisOpenConfigurationEx provides a handle to the registry location where a filter modules configuration parameters are stored. The filter driver can use the configuration handle until NDIS detaches the filter module and the FilterDetach function returns. If a monitoring filter driver specifies the NDIS_CONFIG_FLAG_FILTER_INSTANCE_CONFIGURATION flag in the Flags member of the NDIS_CONFIGURATION_OBJECT structure, the driver can access the filter module configuration for a specific filter module when there are multiple filter modules configured over the same miniport adapter. Modifying filter drivers must not use this flag.

After a driver is finished accessing the configuration information, the driver must call the NdisCloseConfiguration function to release the configuration handle and related resources.

Note   To make sure that this function runs at IRQL = PASSIVE_LEVEL, a driver can schedule an NDIS work item and call this and other configuration functions in the context of the work item callback.

Requirements

Header

ndis.h

See Also

Reference

NDIS Configuration Interface
FilterAttach
FilterDetach
MiniportHaltEx
MiniportInitializeEx
NDIS_BIND_PARAMETERS
NDIS_CONFIGURATION_OBJECT
NdisCloseAdapterEx
NdisCloseConfiguration
NdisDeregisterProtocolDriver
NdisFDeregisterFilterDriver
NdisFRegisterFilterDriver
NdisMDeregisterMiniportDriver
NdisMRegisterMiniportDriver
NdisOpenAdapterEx
NdisOpenConfigurationKeyByIndex
NdisOpenConfigurationKeyByName
NdisReadConfiguration
NdisReadNetworkAddress
NdisRegisterProtocolDriver
NdisWriteConfiguration
ProtocolBindAdapterEx