WdfIoTargetWdmGetTargetFileHandle method

[Applies to KMDF and UMDF]

The WdfIoTargetWdmGetTargetFileHandle method returns a handle to the file that is associated with a specified remote I/O target.

Syntax


HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Parameters

IoTarget [in]

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

Return value

If the driver specified an object name when it called WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle returns the file handle that is associated with the specified I/O target. Otherwise WdfIoTargetWdmGetTargetFileHandle returns NULL.

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

Remarks

For KMDF, the returned file handle is a kernel-mode handle that is valid in an arbitrary thread context. For information about how a driver can use this file handle, see Using a File Handle.

The file handle that the WdfIoTargetWdmGetTargetFileHandle method returns is valid until the driver calls WdfIoTargetClose or WdfIoTargetCloseForQueryRemove, or until the remote I/O target object is deleted. If the driver provides an EvtCleanupCallback function for the remote I/O target object, and if the object is deleted before the remote I/O target is closed, the pointer is valid until the EvtCleanupCallback function returns.

If the driver attempts to access the WDM device object after it has been removed, the driver can cause the system to crash. The toastmon sample demonstrates how the driver can provide an EvtIoTargetQueryRemove callback function so that it is notified if the I/O target is removed.

For UMDF, WdfIoTargetWdmGetTargetFileHandle returns a Win32 HANDLE valid only in the current process.

If the driver specifies NULL for FileName when it calls WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, WdfIoTargetWdmGetTargetFileHandle returns a non-NULL handle.

For more information about WdfIoTargetWdmGetTargetFileHandle, see Obtaining Information About a General I/O Target.

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

Examples

The following code example obtains a handle to the file that is associated with a specified remote I/O target.


HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

A legacy UMDF driver (version 1.x) calls IWDFDevice::RetrieveDeviceName to get the name of the underlying kernel-mode device and then open a handle to it with CreateFile. The driver then sends I/O directly to the device using DeviceIoControl.

Starting in UMDF 2.15, the driver opens the local I/O target by file and retrieves its handle. The framework opens and closes the file handle. The file handle remains valid within the contract of WdfIoTargetWdmGetTargetFileHandle.


NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.


Requirements

Target platform

Universal

Minimum KMDF version

1.0

Minimum UMDF version

2.15

Header

Wdfiotarget.h (include Wdf.h)

Library

Wdf01000.sys (see Framework Library Versioning.)

IRQL

<=DISPATCH_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

WdfIoTargetCreate
WdfIoTargetWdmGetTargetFileObject

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft