WdfUsbTargetDeviceAllocAndQueryString function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbTargetDeviceAllocAndQueryString method allocates a buffer, then it retrieves the Unicode string that is associated with a specified USB device and descriptor index value.

Syntax

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] PUSHORT                NumCharacters,
  [in]            UCHAR                  StringIndex,
  [in, optional]  USHORT                 LangID
);

Parameters

[in] UsbDevice

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

[in, optional] StringMemoryAttributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains caller-supplied attributes for the new memory object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

A pointer to a location that receives a handle to the memory object that contains the Unicode string. The string is NULL-terminated only if the device supplies a NULL-terminated string.

[out, optional] NumCharacters

A pointer to a location that receives the number of characters that are contained in the string descriptor. If the Unicode string is NULL-terminated, this number includes the NULL character. This parameter is optional and can be NULL.

[in] StringIndex

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

[in, optional] LangID

A language identifier. The Unicode 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.

Return value

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

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INSUFFICIENT_RESOURCES	A memory buffer could not be allocated.
STATUS_DEVICE_DATA_ERROR	The USB device returned an invalid descriptor.
STATUS_BUFFER_OVERFLOW	The supplied buffer was too small.

This method also might return other NTSTATUS values.

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

Remarks

The WdfUsbTargetDeviceAllocAndQueryString method, which your driver only needs to call once to obtain a string descriptor, is an alternative to the WdfUsbTargetDeviceQueryString method, which must be called twice to obtain a string.

The method locates the specified USB string descriptor, copies the Unicode string from the descriptor into a memory object, and returns a handle to the memory object.

After calling WdfUsbTargetDeviceAllocAndQueryString, your driver can pass the StringMemory handle to WdfMemoryGetBuffer to access the contents of the memory object.

For more information about USB string descriptors, see the USB specification.

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

Examples

The following code example calls WdfUsbTargetDeviceAllocAndQueryString to obtain a manufacturer's name string, in USA English (0x0409), from a USB device descriptor. (The driver previously stored the descriptor in driver-defined context space.)

PMY_DEVICE_CONTEXT  myDeviceContext;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &numCharacters,
                                        myDeviceContext->UsbDeviceDescr.iManufacturer,
                                        0x0409
                                        );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Share via