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

  • Статья

[Предупреждение: 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. Если драйвер предоставляет параметр pFile, отличный от NULL, указанный файл заменяет файл, указанный драйвером для CreateFileHandleTarget. (Драйверы также могут вызывать IWDFIoRequest::FormatUsingCurrentType для форматирования запроса ввода-вывода.)

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

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

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

Дополнительные сведения о createFileHandleTarget и целевых объектах ввода-вывода см. в разделе Инициализация общего целевого объекта ввода-вывода в 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 (включая Wudfusb.h)
DLL WUDFx.dll

См. также раздел

IWDFFileHandleTargetFactory

IWDFIoRequest::Send

IWDFIoTarget