IoGetDeviceInterfacePropertyData function (wdm.h)

Article
02/22/2024

The IoGetDeviceInterfacePropertyData routine retrieves the current value of a device interface property.

Syntax

NTSTATUS IoGetDeviceInterfacePropertyData(
  [in]  PUNICODE_STRING  SymbolicLinkName,
  [in]  const DEVPROPKEY *PropertyKey,
  [in]  LCID             Lcid,
        ULONG            Flags,
  [in]  ULONG            Size,
  [out] PVOID            Data,
  [out] PULONG           RequiredSize,
  [out] PDEVPROPTYPE     Type
);

Parameters

[in] SymbolicLinkName

A pointer to a string that identifies the device interface instance. This string was obtained from a previous call to the IoGetDeviceInterfaces, IoGetDeviceInterfaceAlias, or IoRegisterDeviceInterface routine.

[in] PropertyKey

A pointer to a DEVPROPKEY structure that contains the device interface property key.

[in] Lcid

Specifies a locale identifier. Set this parameter either to a language-specific LCID value or to LOCALE_NEUTRAL. The LOCALE_NEUTRAL LCID specifies that the property is language-neutral (that is, not specific to any language). Do not set this parameter to LOCALE_SYSTEM_DEFAULT or LOCALE_USER_DEFAULT. For more information about language-specific LCID values, see LCID Structure.

Flags

Reserved for system use. Drivers should set this value to zero.

[in] Size

Specifies the size, in bytes, of the buffer that Data points to.

[out] Data

A pointer to a caller-allocated buffer into which the routine writes the device interface property data.

[out] RequiredSize

A pointer to a ULONG variable into which IoGetDeviceInterfacePropertyData writes the required size of the property data. If the routine succeeds, the required size value is the number of bytes that the routine writes to the output buffer that Data points to. If the routine returns STATUS_BUFFER_TOO_SMALL, the required size value is the size of the buffer that the caller should allocate for this property value.

[out] Type

A pointer to a DEVPROPTYPE variable. If IoGetDeviceInterfacePropertyData successfully retrieves the property data, the routine writes the property type value to this variable. This value indicates the type of property data that is in the Data buffer.

Return value

IoGetDeviceInterfacePropertyData returns STATUS_SUCCESS if it is successful. Possible error return values include the following status codes.

Return code	Description
STATUS_BUFFER_TOO_SMALL	The buffer that Data points to is too small to contain the property data. *RequiredSize contains the required buffer length.
STATUS_UNSUCCESSFUL	The specified LCID value is not valid.
STATUS_NOT_IMPLEMENTED	The specified property is not supported.

Remarks

Kernel-mode drivers use the IoGetDeviceInterfacePropertyData routine to retrieve device interface properties that are defined as part of the unified device property model. For more information about device interface properties, see Device Properties.

Drivers can use the IoSetDeviceInterfacePropertyData routine to modify a device interface property.

Callers of IoGetDeviceInterfacePropertyData must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 8 and later versions of Windows.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL