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

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

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

1. Укажите дескриптор запроса NULL WdfIoTargetSendIoctlSynchronous метода request или создайте новый объект запроса и предоставьте его дескриптор:
   • Если вы предоставляете дескриптор запроса NULL, платформа использует внутренний объект запроса. Этот метод прост в использовании, но драйвер не может отменить запрос.
   • При вызове WdfRequestCreate для создания одного или нескольких объектов запроса можно повторно использовать эти объекты запроса, вызвав WdfRequestReuse. Этот метод позволяет драйвера EvtDriverDeviceAdd функцию обратного вызова для предварительного размещения объектов запросов для устройства. Кроме того, другой поток драйвера может вызывать WdfRequestCancelSentRequest, чтобы отменить запрос при необходимости.

   Драйвер может указать параметр, отличный отNULLRequestOptions, предоставляет ли драйвер параметрNULL или параметр NULLRequest. Например, можно использовать параметр RequestOptions для указания значения времени ожидания.

2. Предоставьте буферное пространство для WdfIoTargetSendIoctlSynchronous метода InputBuffer и OutputBuffer параметры, если запрос требует их.

   Драйвер может указать это буферное пространство как локальные выделенные буферы, как дескриптор WDFMEMORY или как списки дескрипторов памяти (MDLs). Вы можете использовать любой метод, наиболее удобный.

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

   Доступны следующие методы указания пространства буфера:

   • Укажите локальные буферы.

     Так как WdfIoTargetSendIoctlSynchronous обрабатывает запросы ввода-вывода синхронно, драйвер может создавать буферы запросов, которые являются локальными для вызывающей подпрограммы, как показано в следующем примере кода.

     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 для получения дескриптора в объект памяти платформы, представляющий буфер полученного запроса ввода-вывода, если требуется, чтобы драйвер передал содержимое этого буфера целевому объекту ввода-вывода. Драйвер не должен завершить полученный запрос ввода-вывода, пока новый запрос, который WdfIoTargetSendIoctlSynchronous отправляется в целевой объект ввода-вывода, был удален, повторно использован или переформатирован. (WdfIoTargetSendIoctlSynchronous увеличивает количество ссылок объекта памяти. Удаление, повторное использование или переформатирование объекта запроса уменьшает количество ссылок объекта памяти.)

   • Предоставьте многомерные выражения.

     Драйверы могут получить многомерные ключи, связанные с полученным запросом ввода-вывода, вызвав WdfRequestRetrieveInputmMdl и WdfRequestRetrieveOutputMdl.

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

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

Примеры

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

WDF_MEMORY_DESCRIPTOR  outputDescriptor;
NTSTATUS  status;
HID_COLLECTION_INFORMATION  collectionInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &collectionInformation,
                                  sizeof(HID_COLLECTION_INFORMATION)
                                  );

status = WdfIoTargetSendIoctlSynchronously(
                                           hidTarget,
                                           NULL,
                                           IOCTL_HID_GET_COLLECTION_INFORMATION,
                                           NULL,
                                           &outputDescriptor,
                                           NULL,
                                           NULL
                                           );

Требования

См. также

EvtDriverDeviceAdd

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForIoctl

WdfIoTargetSendInternalIoctlSynchronous

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse