IWDFFileHandleTargetFactory：：CreateFileHandleTarget 方法 (wudfddi.h)

  • 项目

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 Windows 驱动程序必须使用 UMDF 2。 有关详细信息，请参阅使用 UMDF 入门。]

CreateFileHandleTarget 方法创建基于文件句柄的 I/O 目标对象。

语法

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

参数

[in] hTarget

目标设备的句柄。 句柄之前必须已使用 FILE_FLAG_OVERLAPPED 标志打开。 例如，必须在 Microsoft Win32 CreateFile 函数的 dwFlagsAndAttributes 参数中指定FILE_FLAG_OVERLAPPED。

[out] ppTarget

指向位置的指针，该位置接收指向 I/O 目标对象的 IWDFIoTarget 接口的指针。

返回值

CreateFileHandleTarget 返回以下值之一：

返回代码 说明
S_OK

CreateFileHandleTarget 已成功创建基于文件句柄的 I/O 目标对象。
E_OUTOFMEMORY

CreateFileHandleTarget 遇到分配失败。
 

CreateFileHandleTarget 还可能返回 Winerror.h 中定义的其他 HRESULT 值。

注解

如果驱动程序使用基于文件句柄的 I/O 目标，则驱动程序 INF 文件的 DDInstall.WDF 部分必须将 UmdfDispatcher 指令设置为 FileHandle。 有关 UmdfDispatcher 的详细信息，请参阅 指定 WDF 指令。

在驱动程序创建基于文件句柄的 I/O 目标对象后，它可以格式化 I/O 请求并将其发送到 I/O 目标。 通常，如果驱动程序调用 IWDFIoTarget：：FormatRequestForRead、 IWDFIoTarget：：FormatRequestForWrite 或 IWDFIoTarget：：FormatRequestForIoctl，驱动程序会将 pFile 参数设置为 NULL。 NULL 会导致框架使用驱动程序指定为 CreateFileHandleTarget 的文件名。 如果驱动程序提供非 NULLpFile 参数，则指定的文件将替换驱动程序指定为 CreateFileHandleTarget 的文件。 (驱动程序还可以调用 IWDFIoRequest：：FormatUsingCurrentType 来格式化 I/O 请求。)

当驱动程序调用 IWDFIoRequest：：Send 将 I/O 请求发送到 I/O 目标时，驱动程序不得在 Flags 参数中设置WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET值。

驱动程序传递给 CreateFileHandleTarget 的 Win32 句柄必须在基于文件句柄的 I/O 目标对象的生存期内保持有效。 (框架不对此目标句柄进行引用，因此驱动程序必须确保 Win32 句柄保持有效。)

驱动程序使用 CreateFileHandleTarget 提供的 IWDFIoTarget 接口后，必须释放 IWDFIoTarget 接口。

有关 CreateFileHandleTarget 和 I/O 目标的详细信息，请参阅 在 UMDF 中初始化常规 I/O 目标。

示例

下面的代码示例演示如何为命名管道创建基于文件句柄的 I/O 目标。 在此示例中， m_FxDevice 是 IWDFDriver：：CreateDevice 提供的接口指针。

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);
}

要求

要求 值
结束支持 在 UMDF 2.0 及更高版本中不可用。
目标平台 桌面
最低 UMDF 版本 1.5
标头 wudfddi.h (包括 Wudfusb.h)
DLL WUDFx.dll

另请参阅

IWDFFileHandleTargetFactory

IWDFIoRequest：：Send

IWDFIoTarget