WdfUsbTargetDeviceQueryString function (wdfusb.h)
[Applies to KMDF and UMDF]
The WdfUsbTargetDeviceQueryString method retrieves the Unicode string that is associated with a specified USB device and descriptor index value.
Syntax
NTSTATUS WdfUsbTargetDeviceQueryString(
[in] WDFUSBDEVICE UsbDevice,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PUSHORT String,
[in, out] 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] Request
A handle to a framework request object. This parameter is optional and can be NULL. For more information, see the following Remarks section.
[in, optional] RequestOptions
A pointer to a caller-allocated WDF_REQUEST_SEND_OPTIONS structure that specifies options for the request. This pointer is optional and can be NULL. For more information, see the following Remarks section.
[out, optional] String
A pointer to a caller-allocated buffer that receives the requested Unicode string. The string is NULL-terminated only if the device supplies a NULL-terminated string. If this pointer is NULL, WdfUsbTargetDeviceQueryString returns the required buffer size (that is, the required number of Unicode characters) in the location that NumCharacters points to.
[in, out] NumCharacters
A pointer to a caller-allocated variable. The caller supplies the number of Unicode characters that the buffer can hold. When WdfUsbTargetDeviceQueryString returns, the variable receives the number of characters (including the NULL terminator, if supplied) that are in the Unicode string that the String buffer receives.
[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
WdfUsbTargetDeviceQueryString returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:
| Return code | Description |
|---|---|
|
An invalid parameter was detected. |
|
A memory buffer could not be allocated. |
|
The USB device returned an invalid descriptor. |
|
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
Drivers should call WdfUsbTargetDeviceQueryString twice, by using the following steps:
- Set the String pointer to NULL, so that WdfUsbTargetDeviceQueryString will return the required buffer size in the address that the NumCharacters parameter points to.
- Allocate buffer space to hold the number of Unicode characters that are in the requested string. For example, a driver might call ExAllocatePoolWithTag to allocate a buffer, or it might call WdfMemoryCreate to create a framework memory object.
- Call WdfUsbTargetDeviceQueryString again, setting the String value to a pointer to the new buffer and setting NumCharacters to the buffer's length (that is, the number of Unicode characters, not the byte length).
If your driver specifies a non-NULL value for the Request parameter, the framework uses the specified request object, and another driver thread can call WdfRequestCancelSentRequest, if necessary, to attempt to cancel the string query request. If the driver specifies a NULL value for Request, the framework uses an internal request object that the driver cannot cancel.
Your driver can specify a non-NULL RequestOptions parameter, whether the driver provides a non-NULL or a NULL Request parameter. You can, for example, use the RequestOptions parameter to specify a time-out value.
For more information about USB string descriptors, see the USB specification.
For more information about the WdfUsbTargetDeviceQueryString method and USB I/O targets, see USB I/O Targets.
Examples
The following code example calls WdfUsbTargetDeviceQueryString to obtain the required buffer size, calls WdfMemoryCreate to create a memory object and buffer, and then calls WdfUsbTargetDeviceQueryString again to obtain the 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;
USHORT numCharacters;
PUSHORT stringBuf;
WDFMEMORY memoryHandle;
myDeviceContext = GetDeviceContext(device);
status = WdfUsbTargetDeviceQueryString(
myDeviceContext->UsbTargetDevice,
NULL,
NULL,
NULL,
&numCharacters,
myDeviceContext->UsbDeviceDescr.iManufacturer,
0x0409
);
ntStatus = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
POOL_TAG,
numCharacters * sizeof(WCHAR),
&memoryHandle,
(PVOID)&stringBuf
);
if (!NT_SUCCESS(ntStatus)) {
return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
myDeviceContext->UsbTargetDevice,
NULL,
NULL,
stringBuf,
&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) |