Función WdfUsbTargetDeviceFormatRequestForString (wdfusb.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfUsbTargetDeviceFormatRequestForString crea una solicitud para el descriptor de cadena USB asociado al valor de índice de cadena de un dispositivo USB.

Sintaxis

NTSTATUS WdfUsbTargetDeviceFormatRequestForString(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         Memory,
  [in, optional] PWDFMEMORY_OFFSET Offset,
  [in]           UCHAR             StringIndex,
  [in, optional] USHORT            LangID
);

Parámetros

[in] UsbDevice

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

[in] Request

Identificador de un objeto de solicitud de marco.

[in] Memory

Identificador de un objeto de memoria de marco.

[in, optional] Offset

Puntero a una estructura de WDFMEMORY_OFFSET asignada por el autor de la llamada que proporciona valores opcionales de desplazamiento y longitud de bytes. El marco usa estos valores para determinar la dirección y la longitud iniciales, dentro del búfer de salida, para almacenar el descriptor de cadena. Si este puntero es NULL, el descriptor se almacena al principio del búfer de salida y la longitud máxima de la cadena es la longitud del búfer.

[in] StringIndex

Valor de índice que identifica la cadena. Este valor de índice se obtiene de una estructura de USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR o USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Identificador de idioma. La cadena se recuperará para el idioma que especifica este identificador. Para obtener información sobre cómo obtener los identificadores de idioma admitidos de un dispositivo, consulte la especificación USB.

Valor devuelto

WdfUsbTargetDeviceFormatRequestForString 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	El recuento de bytes del búfer no era un número par.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente.
STATUS_INTEGER_OVERFLOW	El desplazamiento que offset especifica no era válido.

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

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Después de que se devuelva WdfUsbTargetDeviceFormatRequestForString , el controlador debe llamar a WdfRequestSend para enviar la solicitud. Después de que WdfRequestSend vuelva, el controlador puede pasar el identificador de memoria a WdfMemoryGetBuffer para obtener un puntero al búfer de memoria. El búfer contendrá una estructura USB_STRING_DESCRIPTOR que describe el descriptor de cadena.

Para obtener más información sobre el método WdfUsbTargetDeviceFormatRequestForString y los destinos de E/S USB, consulte Destinos de E/S USB.

Ejemplos

En el ejemplo de código siguiente se crea un objeto de solicitud y un objeto de memoria y se pasan los identificadores del objeto a WdfUsbTargetDeviceFormatRequestForString. A continuación, el ejemplo establece una función de devolución de llamada CompletionRoutine para la solicitud y envía la solicitud a un destino de E/S.

NTSTATUS status;
PDEVICE_CONTEXT deviceContext = GetDeviceContext(device);
WDFREQUEST request;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
    &attributes,
    WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
    &request);

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfMemoryCreate(
    WDF_NO_OBJECT_ATTRIBUTES,
    NonPagedPool,
    0,
    STR_DESC_STRING_SIZE,
    &memHandle,
    NULL);
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(request);
    return status;
}

status = WdfUsbTargetDeviceFormatRequestForString(
    deviceContext->UsbTargetDevice,
    request,
    memHandle,
    NULL,
    deviceContext->UsbDeviceDescr.iManufacturer,
    0x0409);

if (NT_SUCCESS(status)) {
    WdfRequestSetCompletionRoutine(
        request,
        MyCompletionRoutine,
        NULL);

    if (WdfRequestSend(
            request,
            WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
            NULL)) {
        status = STATUS_PENDING;
    }
    
}
else {
    WdfObjectDelete(memHandle);
    WdfObjectDelete(request);
    return status;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)