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

Статья
07/16/2024

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

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

Синтаксис

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

[in, optional] OtherArg4

[in, optional] RequestOptions

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

[out, optional] BytesReturned

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

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

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

Возвращаемый код	Описание
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), который представляет параметр запроса , не предоставляет достаточно IO_STACK_LOCATION структур, чтобы разрешить драйверу пересылать запрос.

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

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

Замечания

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

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

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

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

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

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

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

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

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

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

Чтобы создать новый запрос ввода-вывода:

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

Доступны следующие методы указания пространства буфера:
- Укажите локальные буферы.
  Так как WdfIoTargetSendInternalIoctlOthersSynchronous обрабатывает запросы ввода-вывода синхронно, драйвер может создавать буферы запросов, которые являются локальными для вызывающей подпрограммы, как показано в следующем примере кода.
```
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);
```
- Предоставьте многомерные выражения.
  Драйверы могут получить многомерные ключи, связанные с полученным запросом ввода-вывода, вызвав WdfRequestRetrieveInputmMdl и WdfRequestRetrieveOutputMdl.

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

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

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

Примеры

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

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 (include 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)