Compartir a través de

Función WdfUsbTargetDeviceCreateUrb (wdfusb.h)

  • Artículo

[Solo se aplica a KMDF]

El método WdfUsbTargetDeviceCreateUrb asigna un bloque de solicitud USB (URB).

Sintaxis

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

Parámetros

[in] UsbDevice

Identificador de un objeto de dispositivo USB obtenido de una llamada anterior a WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Attributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES proporcionada por el autor de la llamada que contiene atributos para el nuevo objeto de memoria. Si el controlador proporciona este parámetro, el miembro ParentObject de la estructura debe ser un objeto de dispositivo USB (WDFUSBDEVICE) o un objeto de solicitud (WDFREQUEST) creado por el marco, o cualquier objeto cuya cadena de elementos primarios conduce a uno de estos tipos. Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

Puntero a una ubicación con tipo WDFMEMORY que recibe un identificador para un objeto de memoria de marco.

[out, optional] Urb

Puntero a una estructura URB que recibe la dirección del URB recién asignado. Este parámetro es opcional y puede ser NULL.

Valor devuelto

WdfUsbTargetDeviceCreateUrb devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los valores siguientes:

Código devuelto Descripción
STATUS_INVALID_PARAMETER
 Se ha detectado un parámetro no válido.
STATUS_INVALID_DEVICE_STATE
 El controlador no especificó una versión de contrato de cliente cuando llamó a WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES
 No había memoria suficiente para crear un nuevo URB.
 

Este método también podría devolver otros valores NTSTATUS.

Comentarios

Antes de llamar a WdfUsbTargetDeviceCreateUrb, un controlador debe llamar a WdfUsbTargetDeviceCreateWithParameters. Si se ejecuta correctamente, WdfUsbTargetDeviceCreateUrb devuelve un identificador a un objeto de memoria de marco que describe el URB recién asignado. Normalmente, un controlador llama a WdfUsbTargetDeviceCreateUrb desde un controlador de solicitudes.

Un controlador puede llamar a WdfUsbTargetDeviceCreateUrb para asignar una estructura URB antes de llamar a WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb es similar en funcionamiento a WdfMemoryCreate. Ambos métodos asignan un objeto de memoria de marco y ambos métodos también proporcionan la opción de recibir el búfer (en este caso, el URB) asociado al objeto de memoria. En ambos casos, el autor de la llamada también puede recuperar el búfer más adelante llamando a WdfMemoryGetBuffer.

Si el controlador proporciona un parámetro Urb cuando llama a WdfUsbTargetDeviceCreateUrb, puede dar formato manualmente al URB o mediante una llamada a las rutinas UsbBuildXxx.

El objeto de memoria y su búfer se eliminan cuando se elimina el objeto primario. Un controlador también puede eliminar un objeto de memoria y su búfer llamando a WdfObjectDelete.

Ejemplos

En el ejemplo de código siguiente se declara un objeto de memoria de marco. En el ejemplo se llama a WdfUsbTargetDeviceCreateUrb para asignar un bloque de solicitud USB y, a continuación, llama a WdfUsbTargetDeviceFormatRequestForUrb para dar formato a una solicitud que use el contenido de la estructura URB. Por último, el ejemplo registra una función de devolución de llamada CompletionRoutine y envía la solicitud a un 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 Value
Cliente mínimo compatible Windows Vista
Plataforma de destino Universal
Versión mínima de KMDF 1.11
Encabezado wdfusb.h (incluya Wdfusb.h)
Library Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL <=DISPATCH_LEVEL
Reglas de cumplimiento de DDI DriverCreate(kmdf)

Consulte también

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb