IoGetDeviceProperty function (wdm.h)
The IoGetDeviceProperty routine retrieves information about a device such as configuration information and the name of its PDO.
Syntax
NTSTATUS IoGetDeviceProperty(
[in] PDEVICE_OBJECT DeviceObject,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Parameters
[in] DeviceObject
Pointer to the physical device object (PDO) for the device being queried.
[in] DeviceProperty
A DEVICE_REGISTRY_PROPERTY-typed enumerator that identifies the device property to be retrieved.
[in] BufferLength
Specifies the size, in bytes, of the caller-supplied PropertyBuffer.
[out, optional] PropertyBuffer
Pointer to a caller-supplied buffer to receive the property information. The buffer can be allocated from pageable memory. The type of the buffer is determined by the DeviceProperty (see above).
[out] ResultLength
Pointer to a ULONG to receive the size of the property information returned at PropertyBuffer. If IoGetDeviceProperty returns STATUS_BUFFER_TOO_SMALL, it sets this parameter to the required buffer length.
Return value
IoGetDeviceProperty returns STATUS_SUCCESS if the call was successful. Possible error return values include the following.
| Return code | Description |
|---|---|
| STATUS_BUFFER_TOO_SMALL | The buffer at PropertyBuffer was too small. ResultLength points to the required buffer length. |
| STATUS_INVALID_PARAMETER_2 | The given DeviceProperty is not one of the properties handled by this routine. |
| STATUS_INVALID_DEVICE_REQUEST | Possibly indicates that the given DeviceObject was not a valid PDO pointer. |
Remarks
IoGetDeviceProperty retrieves device setup information from the registry. Use this routine, rather than accessing the registry directly, to insulate a driver from differences across platforms and from possible changes in the registry structure.
For many DeviceProperty requests, it can take two or more calls to IoGetDeviceProperty to determine the required BufferLength. The first call should use a best-guess value. If the return status is STATUS_BUFFER_TOO_SMALL, the driver should free its current buffer, allocate a buffer of the size returned in ResultLength, and call IoGetDeviceProperty again. Because some of the setup properties are dynamic, the data size can change between the time the required size is returned and driver calls this routine again. Therefore, drivers should call IoGetDeviceProperty inside a loop that runs until the return status is not STATUS_BUFFER_TOO_SMALL.
Function drivers that support devices on a legacy bus and a PnP bus can use the DevicePropertyBusNumber, DevicePropertyBusTypeGuid, and DevicePropertyLegacyBusType properties to distinguish between the buses.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 2000. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI compliance rules | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |