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 返回以下值之一:
返回代码 | 说明 |
---|---|
|
CreateFileHandleTarget 已成功创建基于文件句柄的 I/O 目标对象。 |
|
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 |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈