IoReportTargetDeviceChange function (wdm.h)

Article
04/18/2022

The IoReportTargetDeviceChange routine notifies the PnP manager that a custom event has occurred on a device.

Syntax

NTSTATUS IoReportTargetDeviceChange(
  [in] PDEVICE_OBJECT PhysicalDeviceObject,
  [in] PVOID          NotificationStructure
);

Parameters

[in] PhysicalDeviceObject

Pointer to the PDO of the device being reported.

[in] NotificationStructure

Pointer to a caller-supplied TARGET_DEVICE_CUSTOM_NOTIFICATION structure describing the custom event. The PnP manager sends this structure to drivers that registered for notification of the event.

NotificationStructure.FileObject must be NULL. NotificationStructure.Event must contain the custom GUID for the event. The other fields of the NotificationStructure must be filled in as appropriate for the custom event.

The PnP manager fills in the NotificationStructure.FileObject field when it sends notifications to registrants.

Return value

IoReportTargetDeviceChange returns STATUS_SUCCESS or an appropriate error status. Possible error status values include the following.

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	The caller specified a system PnP event, such as GUID_TARGET_DEVICE_QUERY_REMOVE. This routine is only for custom events.

Remarks

After IoReportTargetDeviceChange notifies the PnP manager that a custom event has occurred on a device, the PnP manager sends notification of the event to drivers that registered for notification on the device. Do not use this routine to report system PnP events, such as GUID_TARGET_DEVICE_REMOVE_COMPLETE.

A driver that defines a custom device event calls IoReportTargetDeviceChange to inform the PnP manager that the custom event has occurred. Custom notification can be used for events like a volume label change.

A driver should call the asynchronous form of this routine, IoReportTargetDeviceChangeAsynchronous, instead of this routine, to prevent deadlocks.

Certain kernel-mode components can call this synchronous routine. For example, a file system can call IoReportTargetDeviceChange to report a "get off the volume" custom event when a component tries to open the volume for exclusive access. Clients that register for notification on file system volumes are careful to not request an exclusive open in a PnP notification callback routine.

The custom notification structure contains a driver-defined event with its own GUID. Driver writers can generate GUIDs with Uuidgen.exe or Guidgen.exe (which are included in the Microsoft Windows SDK).

Callers of IoReportTargetDeviceChange must be running at IRQL = PASSIVE_LEVEL in the context of a system thread. To report a target device change from IRQL > PASSIVE_LEVEL, call IoReportTargetDeviceChangeAsynchronous.

IoReportTargetDeviceChange is not supported on Windows 98/Me; it returns STATUS_NOT_IMPLEMENTED.

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 (see Remarks section)
DDI compliance rules	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)