NdisReadConfiguration

NdisReadConfiguration

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

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

Parameters

Status

Points 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 specified 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

Points to a caller-supplied variable in which a successful call to NdisReadConfiguration returns a pointer to an NDIS_CONFIGURATION_PARAMETER structure, 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 a pointer to a buffered, counted string in the system-default character set. For Windows NT drivers, such a string contains Unicode characters.

ConfigurationHandle

Specifies the handle returned by NdisOpenConfiguration to a NIC driver’s ..\DriverName\Parameters registry key or by NdisOpenProtocolConfiguration to a protocol’s ..\NICDriverInstance\Parameters\ProtocolName key in the protocol section of the registry.

Keyword

Points to a caller-supplied 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.

This parameter also can point to one of the following predefined global keywords for all NDIS drivers:

Predefined Keyword	Predefined Return Values
Environment	NdisEnvironmentWindowsNt NdisEnvironmentWindows
ProcessorType	NdisProcessorX86 // // Following possible if and only if // current machine’s Environment == // NdisEnvironmentWindowsNt // NdisProcessorMips NdisProcessorAlpha NdisProcessorPpc

ParameterType

Specifies the type of the value entry as one of the following:

NdisParameterInteger

Specifies an integer in decimal notation.

NdisParameterHexInteger

Specifies an integer in hexadecimal notation.

NdisParameterString

Specifies a string of type NDIS_STRING. For Windows NT drivers, this is a counted Unicode string.

NdisParameterMultiString

Specifies a multistring parameter of the Windows NT-defined REG_MULTI_SZ type.

Comments

In the Windows NT configuration registry, an NDIS keyword is a synonym for a value entry name. Such a name is a counted sequence of Unicode characters, terminated with a zero.

Every NDIS driver can set up configuration information in the registry for itself under the driver’s Parameters key using an installation script. 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.

For more information about setup and installation scripts, see the Programmer’s Guide.

Callers of NdisReadConfiguration run at IRQL PASSIVE_LEVEL.