Export (0) Print
Expand All

IWDFFileHandleTargetFactory::CreateFileHandleTarget method

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

Syntax


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

Parameters

hTarget [in]

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.

ppTarget [out]

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 codeDescription
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

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.5

Header

Wudfddi.h (include Wudfusb.h)

DLL

WUDFx.dll

See also

IWDFFileHandleTargetFactory
IWDFIoRequest::Send
IWDFIoTarget

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft