WDF_USB_DEVICE_CREATE_CONFIG
WDF_USB_DEVICE_CREATE_CONFIG_INIT
WdfUsbTargetDeviceCreateIsochUrb method
WdfUsbTargetDeviceCreateUrb method
WdfUsbTargetDeviceCreateWithParameters method
WdfUsbTargetDeviceQueryUsbCapability method
展开 最小化

WdfUsbTargetDeviceFormatRequestForString 方法

The WdfUsbTargetDeviceFormatRequestForString method builds a request for the USB string descriptor that is associated with a USB device's string index value.

语法

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

参数

UsbDevice [in]

A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate.

Request [in]

A handle to a framework request object.

Memory [in]

A handle to a framework memory object.

Offset [in, optional]

A pointer to a caller-allocated WDFMEMORY_OFFSET structure that supplies optional byte offset and length values. The framework uses these values to determine the beginning address and length, within the output buffer, for storing the string descriptor. If this pointer is NULL, the descriptor is stored at the beginning of the output buffer, and the maximum string length is the buffer length.

StringIndex [in]

An index value that identifies the string. This index value is obtained from a USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR, or USB_INTERFACE_DESCRIPTOR structure.

LangID [in, optional]

A language identifier. The string will be retrieved for the language that this identifier specifies. For information about obtaining a device's supported language identifiers, see the USB specification.

返回值

WdfUsbTargetDeviceFormatRequestForString returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:

返回代码说明
STATUS_INVALID_PARAMETER

The buffer's byte count was not an even number.

STATUS_INSUFFICIENT_RESOURCES

There was insufficient memory.

STATUS_INTEGER_OVERFLOW

The offset that Offset specifies was invalid.

 

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

评论

After WdfUsbTargetDeviceFormatRequestForString returns, the driver must call WdfRequestSend to send the request. After WdfRequestSend returns, the driver can pass the Memory handle to WdfMemoryGetBuffer to obtain a pointer to the memory buffer. The buffer will contain a USB_STRING_DESCRIPTOR structure that describes the string descriptor.

For more information about the WdfUsbTargetDeviceFormatRequestForString method and USB I/O targets, see USB I/O Targets.

示例

The following code example creates a request object and a memory object, and it passes the object handles to WdfUsbTargetDeviceFormatRequestForString. Then, the example sets a CompletionRoutine callback function for the request and sends the request to an I/O target.

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;
}

要求

版本

Available in version 1.0 and later versions of KMDF.

标头

Wdfusb.h (包括Wdfusb.h)

Wdf<MajorVersionNumber>000.sys (see Framework Library Versions.)

IRQL

<=DISPATCH_LEVEL

另请参见

USB_CONFIGURATION_DESCRIPTOR
USB_DEVICE_DESCRIPTOR
USB_INTERFACE_DESCRIPTOR
USB_STRING_DESCRIPTOR
WDFMEMORY_OFFSET
WdfMemoryGetBuffer
WdfRequestSend
WdfRequestSetCompletionRoutine
WdfUsbTargetDeviceAllocAndQueryString
WdfUsbTargetDeviceCreate

 

 

社区附加资源

添加
显示:
© 2015 Microsoft