Функция 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 возвращает значение состояния завершения целевого объекта ввода-вывода, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:
Код возврата | Описание |
---|---|
|
Обнаружен недопустимый параметр. |
|
Недостаточно памяти. |
|
Указан недопустимый дескриптор памяти или указанный запрос ввода-вывода уже поставлен в очередь в целевой объект ввода-вывода. |
|
Драйвер предоставил значение времени ожидания, и запрос не был выполнен в отведенное время. |
Этот метод также может возвращать другие значения NTSTATUS.
Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.
Комментарии
Используйте метод WdfUsbTargetDeviceSendControlTransferSynchronously для синхронной отправки запроса на передачу элемента управления USB. Чтобы отправить такие запросы асинхронно, используйте WdfUsbTargetDeviceFormatRequestForControlTransfer, а затем WdfRequestSend.
Метод WdfUsbTargetDeviceSendControlTransferSynchronously не возвращается до завершения запроса, если драйвер не предоставляет значение времени ожидания в структуре WDF_REQUEST_SEND_OPTIONS , на которую указывает параметр RequestOptions , или если не обнаружена ошибка.
Вы можете переслать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, или создать и отправить новый запрос. В любом случае для платформы требуется объект запроса и, в зависимости от типа передачи элемента управления, возможно, некоторое буферное пространство.
Чтобы переслать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, выполните приведенные далее действия.
- Укажите дескриптор полученного запроса для параметра Request .
-
Используйте входной или выходной буфер полученного запроса для параметра MemoryDescriptor .
Драйвер может вызвать WdfRequestRetrieveInputMemory или WdfRequestRetrieveOutputMemory , чтобы получить дескриптор объекта памяти платформы, который представляет входной или выходной буфер запроса, а затем поместить этот дескриптор в структуру WDF_MEMORY_DESCRIPTOR , которую драйвер предоставляет для параметра MemoryDescriptor .
-
Укажите дескриптор запроса NULL в параметре Request или создайте новый объект запроса и укажите его дескриптор:
- Если вы предоставляете дескриптор запроса NULL , платформа использует внутренний объект запроса. Этот метод прост в использовании, но драйвер не может отменить запрос.
- При вызове WdfRequestCreate для создания одного или нескольких объектов запроса можно повторно использовать эти объекты запроса, вызвав WdfRequestReuse. Этот метод позволяет функции обратного вызова EvtDriverDeviceAdd драйвера предварительно выделить объекты запросов для устройства. Кроме того, другой поток драйвера может вызвать WdfRequestCancelSentRequest , чтобы при необходимости отменить запрос.
Драйвер может указать параметр RequestOptions, отличный от NULL, независимо от того, предоставляет ли драйвер параметр запроса, отличный от NULL или null. Например, можно использовать параметр RequestOptions , чтобы указать значение времени ожидания.
-
Укажите буферное пространство для параметра MemoryDescriptor метода WdfUsbTargetDeviceSendControlTransferSynchronously.
Драйвер может указать это буферное пространство как локально выделенный буфер, как дескриптор WDFMEMORY или как MDL. Вы можете использовать любой наиболее удобный метод.
При необходимости платформа преобразует описание буфера в то, которое является правильным для метода целевого объекта ввода-вывода для доступа к буферам данных.
Доступны следующие методы:
-
Предоставление локального буфера
Так как WdfUsbTargetDeviceSendControlTransferSynchronously обрабатывает запросы ввода-вывода синхронно, драйвер может создавать буферы запросов, которые являются локальными для вызывающей подпрограммы, как показано в следующем примере кода.
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.
-
Предоставление локального буфера
Сведения о получении сведений о состоянии после завершения запроса ввода-вывода см. в разделе Получение сведений о завершении.
Дополнительные сведения о методе WdfUsbTargetDeviceSendControlTransferSynchronously и целевых объектах ввода-вывода USB см. в разделе Целевые объекты ввода-вывода USB.
Примеры
В следующем примере кода инициализируется структура WDF_USB_CONTROL_SETUP_PACKET , а затем вызывается WdfUsbTargetDeviceSendControlTransferSynchronously для отправки передачи элемента управления, зависящем от поставщика.
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 (включая 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_INIT_VENDOR
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по