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标志打开。 例如，必须在 dwFlagsAndAttributes Microsoft Win32 CreateFile 函数的参数中指定FILE_FLAG_OVERLAPPED。

[out] ppTarget

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

返回值

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 目标时，驱动程序不得在 标志 参数中设置 WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET 值。

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

驱动程序使用 IWDFIoTarget 接口 CreateFileHandleTarget 提供后，它必须释放 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);
}

要求

另请参阅

IWDFFileHandleTargetFactory

IWDFIoRequest：：Send

IWDFIoTarget