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

Статья
08/08/2023

[Применяется только к KMDF]

Метод WdfIoTargetSendInternalIoctlOthersSynchronously создает нестандартный внутренний запрос на управление устройством и синхронно отправляет его в целевой объект ввода-вывода.

Синтаксис

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

Параметры

[in] IoTarget

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

[in, optional] Request

Дескриптор объекта запроса платформы. Этот параметр является необязательным и может иметь значение NULL. Дополнительные сведения см. в разделе "Примечания".

[in] IoctlCode

Код элемента управления вводом-выводом (IOCTL), поддерживаемый целевым объектом ввода-вывода.

[in, optional] OtherArg1

Указатель на структуру WDF_MEMORY_DESCRIPTOR , описывающую буфер памяти, содержащий сведения о контексте. Этот параметр является необязательным и может иметь значение NULL.

[in, optional] OtherArg2

Указатель на структуру WDF_MEMORY_DESCRIPTOR, описывающую буфер памяти, содержащий сведения о контексте. Этот параметр является необязательным и может иметь значение NULL.

[in, optional] OtherArg4

Указатель на структуру WDF_MEMORY_DESCRIPTOR, описывающую буфер памяти, содержащий сведения о контексте. Этот параметр является необязательным и может иметь значение NULL.

[in, optional] RequestOptions

Указатель на структуру WDF_REQUEST_SEND_OPTIONS , выделенную вызывающим объектом, которая задает параметры для запроса. Этот указатель является необязательным и может иметь значение NULL. Дополнительные сведения см. в разделе "Примечания".

[out, optional] BytesReturned

Указатель на расположение, которое получает сведения (например, количество переданных байтов), которые другой драйвер предоставляет при выполнении запроса путем вызова WdfRequestCompleteWithInformation. Этот указатель является необязательным и может иметь значение NULL.

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_REQUEST_SEND_OPTIONS , на которую указывает параметр RequestOptions .
STATUS_INVALID_DEVICE_REQUEST	Запрос уже поставлен в очередь в целевой объект ввода-вывода.
STATUS_INSUFFICIENT_RESOURCES	Платформе не удалось выделить системные ресурсы (обычно это память).
STATUS_IO_TIMEOUT	Драйвер предоставил значение времени ожидания, и запрос не был выполнен в отведенное время.
STATUS_REQUEST_NOT_ACCEPTED	Пакет запроса ввода-вывода (IRP), который представляет параметр Request , не предоставляет достаточно IO_STACK_LOCATION структур, позволяющих драйверу пересылать запрос.

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

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

Нестандартный внутренний запрос на управление устройством использует код IOCTL для идентификации выполняемой операции, но запрос не использует стандартные входные и выходные буферы, которые используются другими внутренними запросами управления устройствами. При создании набора взаимодействующих драйверов можно определить, как этот набор драйверов использует аргументы запроса: OtherArg1, OtherArg2 и OtherArg4.

Параметр OtherArg3 отсутствует, так как платформа связывает эти параметры с элементами Argument1, Argument2 и Argument4 объединения Other.Parameters в структуре IO_STACK_LOCATION драйвера. Член Argument3 в этом объединении получает значение из параметра IoctlCode , поэтому оно недоступно для других значений, предоставленных драйвером.

Используйте метод WdfIoTargetSendInternalIoctlOthersSynchronously для синхронной отправки нестандартных внутренних запросов на управление устройствами. Чтобы асинхронно отправлять внутренние запросы на управление устройствами, используйте WdfIoTargetFormatRequestForInternalIoctlOthers, а затем WdfRequestSend.

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

Метод WdfIoTargetSendInternalIoctlOthersSynchronously не возвращается до завершения запроса, если драйвер не предоставляет значение времени ожидания в структуре WDF_REQUEST_SEND_OPTIONS параметра RequestOptions или если не обнаружена ошибка.

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

Чтобы переслать нестандартный внутренний запрос на управление устройством, полученный драйвером в очереди ввода-вывода, выполните приведенные далее действия.

Укажите дескриптор полученного запроса для параметра Request метода WdfIoTargetSendInternalIoctlOthersSynchronously.
Используйте сведения контекста полученного запроса для параметров OtherArg1, OtherArg2 иOtherArg4 метода WdfIoTargetSendInternalIoctlOthersSynchronously.
Чтобы получить эти значения параметров, драйвер должен вызвать WdfRequestGetParameters и использовать элемент DeviceIoControl возвращаемой структуры WDF_REQUEST_PARAMETERS .

Дополнительные сведения о переадресации запроса ввода-вывода см. в разделе Переадресация запросов ввода-вывода.

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

Чтобы создать новый запрос ввода-вывода, выполните приведенные далее действия.

Укажите дескриптор запроса NULL для параметра Request метода WdfIoTargetSendInternalIoctlOthersSynchronously или создайте новый объект запроса и укажите его дескриптор:
- Если вы предоставляете дескриптор запроса NULL , платформа использует внутренний объект запроса. Этот метод прост в использовании, но драйвер не может отменить запрос.
- При вызове WdfRequestCreate для создания одного или нескольких объектов запроса можно повторно использовать эти объекты запроса, вызвав WdfRequestReuse. Этот метод позволяет функции обратного вызова EvtDriverDeviceAdd драйвера предварительно выделить объекты запросов для устройства. Кроме того, другой поток драйвера может вызвать WdfRequestCancelSentRequest , чтобы при необходимости отменить запрос.
Драйвер может указать параметр RequestOptions, отличный от NULL, независимо от того, предоставляет ли драйвер параметр запроса, отличный от NULL или null. Например, можно использовать параметр RequestOptions , чтобы указать значение времени ожидания.
Предоставьте контекстное пространство для параметров OtherArg1, OtherArg2 и OtherArg4 метода WdfIoTargetSendInternalIoctlOthersSynchronously, если они требуются для запроса.
Драйвер может указать это контекстное пространство в виде локально выделенных буферов, дескрипторов WDFMEMORY или списков дескрипторов памяти (MDL). Вы можете использовать любой наиболее удобный метод.

Доступны следующие методы указания буферного пространства:
- Укажите локальные буферы.
  Так как WdfIoTargetSendInternalIoctlOthersSynchronously обрабатывает запросы ввода-вывода синхронно, драйвер может создавать буферы запросов, которые являются локальными для вызывающей подпрограммы, как показано в следующем примере кода.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
```
- Предоставление дескрипторов WDFMEMORY.
  Вызовите WdfMemoryCreate или WdfMemoryCreatePreallocated , чтобы получить дескриптор памяти, управляемой платформой, как показано в следующем примере кода.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);
```
- Предоставьте многомерные списки.
  Драйверы могут получать mdls, связанные с полученным запросом ввода-вывода, путем вызова WdfRequestRetrieveInputWdmMdl и WdfRequestRetrieveOutputWdmMdl.

Сведения о получении сведений о состоянии после завершения запроса ввода-вывода см. в разделе Получение сведений о завершении.

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

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

Примеры

В следующем примере кода инициализируется структура IRB IEEE 1394, используется адрес структуры для инициализации структуры WDF_MEMORY_DESCRIPTOR , а затем вызывается WdfIoTargetSendInternalIoctlOthersSynchronously.

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           NULL,
                                                           NULL
                                                           );

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfiotarget.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки платформы).
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf)