共用方式為

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 旗標開啟。 例如，FILE_FLAG_OVERLAPPED必須在 dwFlagsAndAttributes 參數中指定 Microsoft Win32 CreateFile 函式。

[out] ppTarget

接收 I/O 目標物件之 IWDFIoTarget 介面之 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