Функция WdfUsbTargetPipeReadSynchronously (wdfusb.h)

  • Статья

[Относится к KMDF и UMDF]

Метод WdfUsbTargetPipeReadSynchronously создает запрос на чтение и синхронно отправляет его в указанный входной USB-канал.

Синтаксис

NTSTATUS WdfUsbTargetPipeReadSynchronously(
  [in]            WDFUSBPIPE                Pipe,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    MemoryDescriptor,
  [out, optional] PULONG                    BytesRead
);

Параметры

[in] Pipe

Дескриптор объекта канала платформы, полученный путем вызова WdfUsbInterfaceGetConfiguredPipe.

[in, optional] Request

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

[in, optional] RequestOptions

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

[in, optional] MemoryDescriptor

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

[out, optional] BytesRead

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

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

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

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

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

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

Комментарии

Используйте метод WdfUsbTargetPipeReadSynchronously для синхронной отправки запросов на чтение. Для асинхронной отправки запросов на чтение используйте WdfUsbTargetPipeFormatRequestForRead, а затем WdfRequestSend.

Канал, который указывает параметр Pipe , должен быть входным каналом, а тип канала — WdfUsbPipeTypeBulk или WdfUsbPipeTypeInterrupt.

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

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

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

  1. Укажите дескриптор полученного запроса для параметра Request .
  2. Используйте выходной буфер полученного запроса для параметра MemoryDescriptor метода WdfUsbTargetPipeReadSynchronously.

    Драйвер должен вызвать WdfRequestRetrieveOutputMemory , чтобы получить дескриптор для объекта памяти платформы, представляющего выходной буфер запроса, а затем поместить этот дескриптор в структуру WDF_MEMORY_DESCRIPTOR , на которую указывает MemoryDescriptor .

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

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

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

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

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

  2. Укажите буферное пространство для параметра MemoryDescriptor метода WdfUsbTargetPipeReadSynchronously.

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

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

    Доступны следующие методы:

    • Предоставление локального буфера

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

      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);

      Кроме того, драйвер может вызвать WdfRequestRetrieveOutputMemory , чтобы получить дескриптор объекта памяти платформы, который представляет выходной буфер полученного запроса ввода-вывода, если требуется, чтобы драйвер передавал содержимое этого буфера целевому объекту ввода-вывода. Драйвер не должен выполнять полученный запрос ввода-вывода, пока новый запрос, который WdfUsbTargetPipeReadSynchronously отправляет целевому объекту ввода-вывода, не будет удален, повторно использован или переформатирован. (WdfUsbTargetPipeReadSynchronous увеличивает количество ссылок объекта памяти. Удаление, повторное использование или переформатирование объекта запроса уменьшает количество ссылок объекта памяти.)

    • Предоставление MDL

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

Платформа устанавливает флаг USBD_SHORT_TRANSFER_OK во внутренней urb. Установка этого флага позволяет, чтобы последний пакет передачи данных был меньше максимального размера пакета.

Драйвер не может вызывать WdfUsbTargetPipeReadSynchronously , если он настроил непрерывное средство чтения для канала.

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

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

Примеры

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

WDFMEMORY  wdfMemory;
WDF_MEMORY_DESCRIPTOR  readBufDesc;
ULONG  BytesRead;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         readSize,
                         &wdfMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return ;
}

buffer = WdfMemoryGetBuffer(
                            wdfMemory,
                            NULL
                            );

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &readBufDesc,
                                  buffer,
                                  readSize
                                  );

status = WdfUsbTargetPipeReadSynchronously(
                                           Pipe,
                                           NULL,
                                           NULL,
                                           &readBufDesc,
                                           &BytesRead
                                           );

Требования

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

См. также раздел

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WdfMemoryCreate

WdfUsbTargetPipeGetInformation