NdisOpenConfigurationEx function (ndis.h)

Article
04/18/2022

NDIS drivers call the NdisOpenConfigurationEx 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

[in] ConfigObject

A pointer to a caller-supplied and initialized NDIS_CONFIGURATION_OBJECT structure.

[out] 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:

Return code	Description
NDIS_STATUS_SUCCESS	NdisOpenConfigurationEx successfully opened the registry key where the driver's configuration parameters are stored.
NDIS_STATUS_RESOURCES	NdisOpenConfigurationEx failed due to insufficient resources.
NDIS_STATUS_FAILURE	NdisOpenConfigurationEx returns NDIS_STATUS_FAILURE if none of the preceding 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

NdisWriteConfiguration

NdisOpenConfigurationKeyByName NdisOpenConfigurationKeyByIndex

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 done accessing the configuration information, the driver must call the NdisCloseConfiguration function to release the configuration handle and related resources.

Note To be 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

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI compliance rules	Irql_Miscellaneous_Function(ndis), NdisOpenConfigurationEx(ndis)