WdfIoTargetOpen function (wdfiotarget.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfIoTargetOpen method opens a remote I/O target so the driver can send I/O requests to it.

Syntax

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

Parameters

[in] IoTarget

A handle to an I/O target object that was obtained from a previous call to WdfIoTargetCreate.

[in] OpenParams

A pointer to a caller-allocated WDF_IO_TARGET_OPEN_PARAMS structure.

Return value

WdfIoTargetOpen returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_DEVICE_STATE	The specified I/O target is already open.
STATUS_INSUFFICIENT_RESOURCES	Available system resources were insufficient to complete the operation.
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_IO_TARGET_OPEN_PARAMS structure that OpenParams specified was incorrect.
STATUS_NO_SUCH_DEVICE	The TargetFileObject member of the caller's WDF_IO_TARGET_OPEN_PARAMS structure specified an invalid file object.
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_NOT_FOUND	The device name that is identified in the OpenParams parameter cannot be found.

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

Drivers can open remote I/O targets by supplying a Unicode string that represents an object name or by supplying a pointer to a Windows Driver Model (WDM) DEVICE_OBJECT structure. (Framework-based drivers typically do not have pointers to other drivers' DEVICE_OBJECT structures.)

To obtain a device interface name prior to calling WdfIoTargetOpen, a UMDF driver should call CM_Register_Notification to register for interface arrival and removal notification. Then it can open the remote target using the interface symbolic name that it receives in the interface notification callback routine. The driver should continue to listen for the removal notification while the handle is open. If the target driver fails, the UMDF driver must close the handle.

If the interface already exists, a UMDF driver should call CM_Get_Device_Interface_List, possibly calling CM_Get_Device_Interface_List_Size first to determine the required buffer size.

If you want your driver to use its local I/O target, the driver must call WdfDeviceGetIoTarget instead of WdfIoTargetOpen.

If a call to WdfIoTargetOpen fails, the driver should call WdfObjectDelete to delete the I/O target object.

For more information about WdfIoTargetOpen, see Initializing a General I/O Target.

For more information about I/O targets, see Using I/O Targets.

Examples

The following example creates an I/O target object, initializes a WDF_IO_TARGET_OPEN_PARAMS structure, and opens a remote I/O target by specifying a device's symbolic link name.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfiotarget.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via