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

Статья
07/16/2024

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

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

Синтаксис

NTSTATUS WdfIoTargetSendInternalIoctlSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [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] InputBuffer

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

[in, optional] OutputBuffer

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

[in, optional] RequestOptions

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

[out, optional] BytesReturned

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

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

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

Возвращаемый код	Описание
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.

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

Замечания

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

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

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

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

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

Укажите дескриптор полученного запроса для параметра WdfIoTargetSendInternalIoctlSynchronous метода request.
Используйте входной буфер полученного запроса для параметра WdfIoTargetSendInternalIoctlSynchronous метода InputBuffer.
Драйвер должен вызвать WdfRequestRetrieveInputMemory, чтобы получить дескриптор входного буфера запроса. Затем драйвер должен поместить этот дескриптор в структуру WDF_MEMORY_DESCRIPTOR, которую драйвер предоставляет для параметра InputBuffer.
Используйте выходной буфер полученного запроса для параметра WdfIoTargetSendInternalIoctlSynchronous метода OutputBuffer.
Драйвер должен вызвать WdfRequestRetrieveOutputMemory, чтобы получить дескриптор выходного буфера запроса, и затем он должен поместить этот дескриптор в структуру WDF_MEMORY_DESCRIPTOR, которую драйвер предоставляет для параметра OutputBuffer.

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

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

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

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

При необходимости платформа преобразует описания буфера, чтобы они были правильными для типа передачи IOCTL. Дополнительные сведения о типах передачи IOCTL см. в определении кодов управления ввода-вывода.

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

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

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

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

Примеры

Следующий пример кода определяет локальный буфер, инициализирует структуру WDF_MEMORY_DESCRIPTOR и вызывает WdfIoTargetSendInternalIoctlSynchronous. В этом примере указывается null для дескриптора объекта запроса, поэтому платформа создаст новый объект запроса для целевого объекта ввода-вывода.

WDF_MEMORY_DESCRIPTOR  outputDescriptor;
NTSTATUS  status;
MY_DRIVER_INFORMATION  driverInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &driverInformation,
                                  sizeof(MY_DRIVER_INFORMATION)
                                  );

status = WdfIoTargetSendInternalIoctlSynchronously(
                                                   hidTarget,
                                                   NULL,
                                                   IOCTL_INTERNAL_GET_MY_DRIVER_INFORMATION,
                                                   NULL,
                                                   &outputDescriptor,
                                                   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)