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

[Применимо к KMDF и UMDF]

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

Синтаксис

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

Параметры

[in] UsbDevice

Дескриптор объекта USB-устройства, полученного из предыдущего вызова WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Request

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

[in, optional] RequestOptions

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

[in] SetupPacket

Указатель на структуру, выделенную вызывающим объектом WDF_USB_CONTROL_SETUP_PACKET , описывающую передачу элемента управления.

[in, optional] MemoryDescriptor

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

[out, optional] BytesTransferred

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

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

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

Код возврата Описание
STATUS_INVALID_PARAMETER
Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES
Недостаточно памяти.
STATUS_INVALID_DEVICE_REQUEST
Указан недопустимый дескриптор памяти или указанный запрос ввода-вывода уже помещен в очередь в целевой объект ввода-вывода.
STATUS_IO_TIMEOUT
Драйвер предоставил значение времени ожидания и запрос не завершился в течение выделенного времени.

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

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

Remarks

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The framework sets the USBD_SHORT_TRANSFER_OK flag in its internal URB. Если установить этот флаг, последний пакет передачи данных будет меньше максимального размера пакета.

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

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

Примеры

В следующем примере кода инициализируется структура WDF_USB_CONTROL_SETUP_PACKET , а затем вызывается WdfUsbTargetDeviceSendControlTransferSynchronous для отправки передачи элемента управления, зависящем от поставщика.

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

Требования

   
Целевая платформа Универсальное
Минимальная версия KMDF 1.0
Минимальная версия UMDF 2.0
Верхняя часть wdfusb.h (include Wdfusb.h)
Библиотека Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
Правила соответствия DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

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

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR

WdfRequestCancelSentRequest

WdfUsbTargetDeviceFormatRequestForControlTransfer

WdfUsbTargetDeviceSendUrbSynchronously