Função WdfUsbTargetDeviceCreateUrb (wdfusb.h)

[Aplica-se somente ao KMDF]

O método WdfUsbTargetDeviceCreateUrb aloca um URB (bloco de solicitação USB).

Sintaxe

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

Parâmetros

[in] UsbDevice

Um identificador para um objeto de dispositivo USB que foi obtido de uma chamada anterior para WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Attributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES fornecida pelo chamador que contém atributos para o novo objeto de memória. Se o driver fornecer esse parâmetro, o membro ParentObject da estrutura deverá ser um objeto de dispositivo USB (WDFUSBDEVICE) ou um objeto de solicitação (WDFREQUEST) criado pela estrutura ou qualquer objeto cuja cadeia de pais leve a um desses tipos. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

Um ponteiro para um local do tipo WDFMEMORY que recebe um identificador para um objeto de memória de estrutura.

[out, optional] Urb

Um ponteiro para uma estrutura URB que recebe o endereço do URB recém-alocado. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

WdfUsbTargetDeviceCreateUrb retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INVALID_DEVICE_STATE	O driver não especificou uma versão de contrato de cliente quando chamou WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES	Não havia memória suficiente para criar um novo URB.

 

Esse método também pode retornar outros valores NTSTATUS.

Comentários

Antes de chamar WdfUsbTargetDeviceCreateUrb, um driver deve chamar WdfUsbTargetDeviceCreateWithParameters. Se tiver êxito, WdfUsbTargetDeviceCreateUrb retornará um identificador para um objeto de memória de estrutura que descreve o URB recém-alocado. Normalmente, um driver chama WdfUsbTargetDeviceCreateUrb de dentro de um manipulador de solicitação.

Um driver pode chamar WdfUsbTargetDeviceCreateUrb para alocar uma estrutura URB antes de chamar WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb é semelhante em operação a WdfMemoryCreate. Ambos os métodos alocam um objeto de memória de estrutura e ambos os métodos também fornecem a opção de receber o buffer (nesse caso, o URB) associado ao objeto de memória. Em ambos os casos, o chamador também pode recuperar o buffer mais tarde chamando WdfMemoryGetBuffer.

Se o driver fornecer um parâmetro Urb ao chamar WdfUsbTargetDeviceCreateUrb, você poderá formatar o URB manualmente ou chamando as rotinas do UsbBuildXxx.

O objeto de memória e seu buffer são excluídos quando o objeto pai é excluído. Um driver também pode excluir um objeto de memória e seu buffer chamando WdfObjectDelete.

Exemplos

O exemplo de código a seguir declara um objeto de memória de estrutura. O exemplo chama WdfUsbTargetDeviceCreateUrb para alocar um bloco de solicitação USB e, em seguida, chama WdfUsbTargetDeviceFormatRequestForUrb para formatar uma solicitação que usa o conteúdo da estrutura URB. Por fim, o exemplo registra uma função de retorno de chamada CompletionRoutine e envia a solicitação para um destino de E/S.

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Plataforma de Destino	Universal
Versão mínima do KMDF	1.11
Cabeçalho	wdfusb.h (inclua Wdfusb.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf)

Confira também

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb