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

  • Статья

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

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

Синтаксис

NTSTATUS WdfUsbTargetPipeAbortSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

Параметры

[in] Pipe

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

[in, optional] Request

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

[in, optional] RequestOptions

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

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

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

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

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

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

Комментарии

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

Запрос прерывания USB приводит к тому, что целевой объект ввода-вывода драйвера отменяет все запросы ввода-вывода, отправленные в канал. Когда драйвер вызывает WdfUsbTargetPipeAbortSynchronously, платформа отправляет запрос URB_FUNCTION_ABORT_PIPE целевому объекту ввода-вывода. Дополнительные сведения об отмене операций в USB-канале (также называемом "прерыванием канала") см. в спецификации USB.

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

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

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

Чтобы создать и отправить новый запрос, укажите дескриптор запроса NULL для параметра Request или создайте новый объект запроса и укажите его дескриптор:

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

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

Дополнительные сведения о методе WdfUsbTargetPipeAbortSynchronously и целевых объектах USB-ввода-вывода см. в разделе Usb I/O Targets.

Примеры

В следующем примере кода отправляются прерваемые запросы ко всем каналам, настроенным для интерфейса USB-устройства.

UCHAR  i;
ULONG  count;
NTSTATUS  status;
PDEVICE_CONTEXT  pDevContext;

pDevContext = GetDeviceContext(Device);

count = WdfUsbInterfaceGetNumConfiguredPipes(
                                             pDevContext->UsbInterface
                                             );

for (i = 0; i < count; i++) {
    WDFUSBPIPE pipe;

    pipe = WdfUsbInterfaceGetConfiguredPipe(
                                            pDevContext->UsbInterface,
                                            i,
                                            NULL
                                            );
    status = WdfUsbTargetPipeAbortSynchronously(
                                                pipe,
                                                WDF_NO_HANDLE,
                                                NULL
                                                );
    if (!NT_SUCCESS(status)) {
        break;
    }
}

Требования

Требование Значение
Целевая платформа Универсальное
Минимальная версия 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), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

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

WdfRequestCancelSentRequest

WdfUsbTargetPipeResetSynchronously