IWDFFileHandleTargetFactory::CreateFileHandleTarget method (wudfddi.h)

Article
10/21/2021

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The CreateFileHandleTarget method creates a file-handle-based I/O target object.

Syntax

HRESULT CreateFileHandleTarget(
  [in]  HANDLE       hTarget,
  [out] IWDFIoTarget **ppTarget
);

Parameters

[in] hTarget

A handle to the target device. The handle must have been previously opened with the FILE_FLAG_OVERLAPPED flag. For example, FILE_FLAG_OVERLAPPED must have been specified in the dwFlagsAndAttributes parameter of the Microsoft Win32 CreateFile function.

[out] ppTarget

A pointer to a location that receives a pointer to the IWDFIoTarget interface of the I/O target object.

Return value

CreateFileHandleTarget returns one of the following values:

Return code	Description
S_OK	CreateFileHandleTarget successfully created a file-handle-based I/O target object.
E_OUTOFMEMORY	CreateFileHandleTarget encountered an allocation failure.

CreateFileHandleTarget might also return other HRESULT values that are defined in Winerror.h.

Remarks

If your driver uses a file-handle-based I/O target, the DDInstall.WDF section of the driver's INF file must set the UmdfDispatcher directive to FileHandle. For more information about UmdfDispatcher, see Specifying WDF Directives.

After the driver creates a file-handle-based I/O target object, it can format I/O requests and send them to the I/O target. Typically, if the driver calls IWDFIoTarget::FormatRequestForRead, IWDFIoTarget::FormatRequestForWrite, or IWDFIoTarget::FormatRequestForIoctl, the driver sets the pFile parameter to NULL. The NULL causes the framework to use the filename that the driver specified to CreateFileHandleTarget. If the driver provides a non-NULL pFile parameter, the specified file replaces the file that the driver specified to CreateFileHandleTarget. (Drivers can also call IWDFIoRequest::FormatUsingCurrentType to format an I/O request.)

When the driver calls IWDFIoRequest::Send to send the I/O request to the I/O target, the driver must not set the WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET value in the Flags parameter.

The Win32 handle that the driver passes to CreateFileHandleTarget must remain valid for the lifetime of the file-handle-based I/O target object. (The framework does not take a reference on this target handle, so your driver must ensure that the Win32 handle remains valid.)

When the driver has finished using the IWDFIoTarget interface that CreateFileHandleTarget provides, it must release the IWDFIoTarget interface.

For more information about CreateFileHandleTarget and I/O targets, see Initializing a General I/O Target in UMDF.

Examples

The following code example shows how to create a file-handle-based I/O target for a named pipe. In this example, m_FxDevice is the interface pointer that IWDFDriver::CreateDevice provides.

HRESULT hr = S_OK;
CComPtr<IWDFFileHandleTargetFactory> pFileHandleTargetFactory;
//
// Create a pipe and get the handle.
//
m_WriteHandle = CreateNamedPipe(NP_NAME, 
                                PIPE_ACCESS_DUPLEX|FILE_FLAG_OVERLAPPED, 
                                PIPE_TYPE_MESSAGE|PIPE_READMODE_MESSAGE|PIPE_WAIT,
                                2,
                                MAX_TRANSFER_SIZE,
                                MAX_TRANSFER_SIZE,
                                1000,
                                NULL);
if (m_WriteHandle == INVALID_HANDLE_VALUE) {
    DWORD err = GetLastError();
    hr = HRESULT_FROM_WIN32(err);
}
//
// Obtain the IWDFFileHandleTargetFactory interface
// by calling IWDFDevice::QueryInterface. 
//
if (SUCCEEDED(hr)) {
    hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pFileHandleTargetFactory));
}
//
// Create a file handle target.
//
if (SUCCEEDED(hr)) {
    hr = pFileHandleTargetFactory->CreateFileHandleTarget(m_WriteHandle,
                                                          &m_WriteTarget);
}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.5
Header	wudfddi.h (include Wudfusb.h)
DLL	WUDFx.dll