Метод IWDFFileHandleTargetFactory::CreateFileHandleTarget (wudfddi.h)

Статья
07/16/2024

[ предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе Начало работы с UMDF.]

Метод CreateFileHandleTarget создает целевой объект ввода-вывода на основе файлов.

Синтаксис

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

Параметры

[in] hTarget

Дескриптор целевого устройства. Ранее дескриптор был открыт с помощью флага FILE_FLAG_OVERLAPPED. Например, FILE_FLAG_OVERLAPPED должны быть указаны в параметре dwFlagsAndAttributes функции Microsoft Win32 CreateFile.

[out] ppTarget

Указатель на расположение, которое получает указатель на интерфейс IWDFIoTarget целевого объекта ввода-вывода.

Возвращаемое значение

CreateFileHandleTarget возвращает одно из следующих значений:

Возвращаемый код	Описание
S_OK	CreateFileHandleTarget успешно создал целевой объект ввода-вывода на основе файлов.
E_OUTOFMEMORY	CreateFileHandleTarget возникла ошибка выделения.

CreateFileHandleTarget также может возвращать другие значения HRESULT, определенные в Winerror.h.

Замечания

Если драйвер использует целевой объект ввода-вывода на основе файлов, раздел DDInstall.WDF INF-файла драйвера должен задать директиву UmdfDispatcher значение FileHandle. Дополнительные сведения о UmdfDispatcherсм. в разделе Указание директив WDF.

После создания целевого объекта ввода-вывода на основе файлов драйвер может отформатировать запросы ввода-вывода и отправить их в целевой объект ввода-вывода. Как правило, если драйвер вызывает IWDFIoTarget::FormatRequestForRead, IWDFIoTarget::FormatRequestForWriteили IWDFIoTarget::FormatRequestForIoctl, драйвер задает параметр pFile значение NULL. NULL приводит к использованию платформы имени файла, указанного драйвером CreateFileHandleTarget. Если драйверпредоставляет параметр pFilenull, указанный файл заменяет файл, указанный драйвером CreateFileHandleTarget. (Драйверы также могут вызывать IWDFIoRequest::FormatUsingCurrentType для форматирования запроса ввода-вывода.)

Когда драйвер вызывает IWDFIoRequest::Send для отправки запроса ввода-вывода в целевой объект ввода-вывода, драйвер не должен задать значение WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET в параметре Flags.

Дескриптор Win32, который драйвер передает в CreateFileHandleTarget, должен оставаться действительным в течение времени существования целевого объекта ввода-вывода на основе файлов. (Платформа не принимает ссылку на этот целевой дескриптор, поэтому драйвер должен убедиться, что дескриптор Win32 остается допустимым.)

Когда драйвер завершит работу с интерфейсом IWDFIoTarget , который предоставляет CreateFileHandleTarget, он должен освободить интерфейс IWDFIoTarget.

Дополнительные сведения о целевых объектах CreateFileHandleTar get и i/O см. в инициализации общего целевого объекта ввода-вывода вUMDF.

Примеры

В следующем примере кода показано, как создать целевой объект ввода-вывода на основе файлов для именованного канала. В этом примере 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 (include Wudfusb.h)
DLL	WUDFx.dll

См. также

IWDFFileHandleTargetFactory

IWDFIoRequest::Send

IWDFIoTarget

Поделиться через