Функция WdfIoTargetOpen (wdfiotarget.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfIoTargetOpen открывает удаленный целевой объект ввода-вывода, чтобы драйвер смог отправлять ему запросы ввода-вывода.

Синтаксис

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

Параметры

[in] IoTarget

Дескриптор целевого объекта ввода-вывода, полученный из предыдущего вызова WdfIoTargetCreate.

[in] OpenParams

Указатель на структуру, выделенную вызывающим объектом WDF_IO_TARGET_OPEN_PARAMS .

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

WdfIoTargetOpen возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_DEVICE_STATE	Указанный целевой объект ввода-вывода уже открыт.
STATUS_INSUFFICIENT_RESOURCES	Доступных системных ресурсов недостаточно для завершения операции.
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_IO_TARGET_OPEN_PARAMS , указанной в OpenParams .
STATUS_NO_SUCH_DEVICE	Элемент TargetFileObject структуры WDF_IO_TARGET_OPEN_PARAMS вызывающего объекта указывает недопустимый объект файла.
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_NOT_FOUND	Не удается найти имя устройства, указанное в параметре OpenParams .

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Драйверы могут открывать удаленные целевые объекты ввода-вывода, предоставляя строку Юникода, представляющую имя объекта , или указатель на структуру windows Driver Model (WDM) DEVICE_OBJECT . (Драйверы на основе платформы обычно не имеют указателей на структуры DEVICE_OBJECT других драйверов.)

Чтобы получить имя интерфейса устройства перед вызовом WdfIoTargetOpen, драйвер UMDF должен вызвать CM_Register_Notification , чтобы зарегистрироваться для получения уведомления о прибытии и удалении интерфейса. Затем он может открыть удаленный целевой объект, используя символьное имя интерфейса, которое он получает в подпрограмме обратного вызова уведомления интерфейса. Драйвер должен продолжать прослушивать уведомление об удалении, пока дескриптор открыт. В случае сбоя целевого драйвера драйвер UMDF должен закрыть дескриптор.

Если интерфейс уже существует, драйвер UMDF должен вызвать CM_Get_Device_Interface_List, возможно, сначала вызвав CM_Get_Device_Interface_List_Size , чтобы определить требуемый размер буфера.

Если вы хотите, чтобы драйвер использовал локальный целевой объект ввода-вывода, драйвер должен вызвать WdfDeviceGetIoTarget вместо WdfIoTargetOpen.

Если вызов WdfIoTargetOpen завершается сбоем, драйвер должен вызвать WdfObjectDelete , чтобы удалить целевой объект ввода-вывода.

Дополнительные сведения о WdfIoTargetOpen см. в разделе Инициализация общего целевого объекта ввода-вывода.

Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.

Примеры

В следующем примере создается целевой объект ввода-вывода, инициализируется структура WDF_IO_TARGET_OPEN_PARAMS и открывается удаленный целевой объект ввода-вывода, указав имя символьной ссылки устройства.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfiotarget.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)