NdisReadConfiguration (NDIS 5.1) function

Article
06/19/2017

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.

NdisReadConfiguration returns the value of a named entry of the specified type from the registry, given the handle to an open registry key.

Syntax

VOID NdisReadConfiguration(
  _Out_ PNDIS_STATUS                  Status,
  _Out_ PNDIS_CONFIGURATION_PARAMETER *ParameterValue,
  _In_  NDIS_HANDLE                   ConfigurationHandle,
  _In_  PNDIS_STRING                  Keyword,
  _In_  NDIS_PARAMETER_TYPE           ParameterType
);

Parameters

Status [out]
Pointer to a caller-supplied variable in which this function returns the status of the call as one of the following:
- NDIS_STATUS_SUCCESS
  The buffer at ParameterValue contains the returned configuration information.
- NDIS_STATUS_RESOURCES
  NDIS could not allocate resources, usually enough memory, to return the requested information.
- NDIS_STATUS_FAILURE
  The requested information could not be found under the opened registry key designated by the ConfigurationHandle.
ParameterValue [out]
Pointer to a memory location where NDIS supplies a pointer to an NDIS_CONFIGURATION_PARAMETER structure if the call to NdisReadConfiguration is successful. NDIS allocates memory for the NDIS_CONFIGURATION_PARAMETER structure, which is defined as follows:
```
typedef struct _NDIS_CONFIGURATION_PARAMETER {
    NDIS_PARAMETER_TYPE ParameterType;
    union {
        ULONG IntegerData;
        NDIS_STRING StringData;
    } ParameterData;
} NDIS_CONFIGURATION_PARAMETER, *PNDIS_CONFIGURATION_PARAMETER;
```
The members of this structure contain the following data:
- ParameterType
  Matches the value at ParameterType if the call is successful.
- ParameterData
  Specifies the value of the given named entry. If ParameterType is a string type, this member is an NDIS_STRING type describing a counted string in the system-default character set. For Windows 2000 and later drivers, such a string contains Unicode characters. That is, for Windows 2000 and later, NDIS defines the NDIS_STRING type as a UNICODE_STRING type.
ConfigurationHandle [in]
Specifies the handle to a registry key returned by NdisOpenConfiguration to a NIC driver, by NdisOpenProtocolConfiguration to a protocol driver, or by NdisOpenConfigurationKeyByIndex or NdisOpenConfigurationKeyByName to either type of NDIS driver.

Keyword [in]
Pointer to a caller-supplied NDIS_STRING type describing a counted string, in the system-default character set, specifying the name of the entry under the open registry key for which to return the value.

Alternatively, pointer to a caller-supplied NDIS_STRING_CONSTANT specifying one of the following predefined entry names along with predefined return values:

Predefined Entry Name	Predefined Return Values
Environment	NdisEnvironmentWindowsNt NdisEnvironmentWindows
ProcessorType	NdisProcessorX86 // // Following possible only if // current machine's Environment == // NdisEnvironmentWindowsNt // NdisProcessorAlpha // Following possible only if legacy driver NdisProcessorMips NdisProcessorPpc
NdisVersion	0xMMMMmmmm // where MMMM is the major version and // mmmm the minor version number. // For example, 0x00050000 indicates that // the highest NDIS version supported by // the system is major version 5, minor // version 0.

ParameterType [in]
Specifies the type of the value entry as one of the following:
- NdisParameterBinary
  Specifies a binary value.
- NdisParameterInteger
  Specifies an integer in decimal notation.
- NdisParameterHexInteger
  Specifies an integer in hexadecimal notation.
- NdisParameterString
  Specifies a string of type NDIS_STRING. For Windows 2000 and later drivers, this is a counted Unicode string.
- NdisParameterMultiString
  Specifies a multistring parameter of the REG_MULTI_SZ type, which is defined in Windows 2000 and later versions.

Return value

None

Remarks

In the configuration registry of Windows 2000 and later versions, an NDIS Keyword is a synonym for a value entry name. Such a name is a counted sequence of Unicode characters, terminated with a NULL.

Every NDIS driver can set up configuration information in the registry for itself under the driver's Parameters key using an installation file. For example, a protocol driver might store its own name as an entry with a preformatted string value that can be passed in calls to NdisRegisterProtocol.

Each NIC driver also has associated value entries under the driver's Parameters registry key. The value entries for any particular NIC driver can be device-dependent in nature. For example, an Ethernet NIC driver might have keywords such as InterruptNumber, SharedMemoryAddress, and MulticastListSize. The value associated with such an NDIS keyword can be either an integer (ULONG-type) or a string (NDIS_STRING-type). For example, the set of possible values for the already mentioned InterruptNumber entry might be NdisParameterInteger values 2, 3, 4, or 5, or the equivalents in hexadecimal as NdisParameterHexInteger values.

NdisReadConfiguration buffers and copies the caller-supplied string at Keyword and releases the storage it allocates for this copy before it returns control to the caller. The memory it allocates for the NDIS_CONFIGURATION_PARAMETER structure is freed when the driver releases the ConfigurationHandle with NdisCloseConfiguration. The caller of NdisReadConfiguration is responsible for releasing the buffered string at Keyword.

Note that NDIS does not validate values that a driver reads from the registry. The caller of NdisReadConfiguration must therefore not make any assumptions about such values and must validate each value read from the registry. If the caller determines that a value is out of bounds, it should use a default value instead.

For more information about setup and installation files, see Device Installation Overview.

Requirements

Target platform	Universal
Version	See NdisReadConfiguration.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL

Partager via