3.3.5.3.9 Processing an OS Descriptor request
Special processing on the client is needed when processing TS_URB_OS_FEATURE_DESCRIPTOR_REQUEST. The following describes how to get the OS-specific string descriptor.
To retrieve a device's OS string descriptor, send a standard GET_DESCRIPTOR control request to the device. For details on how to construct GET_DESCRIPTOR control requests, see [USB-SPC2.0] section 9.4 "Standard Device Requests." The request must have the format shown in the following table.
|
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|---|---|---|---|---|---|
|
1000 0000B |
GET_DESCRIPTOR |
0x03EE |
0x0000 |
0x12 |
Returned string |
bmRequestType: IN. This 1-byte field is divided into three parts that indicate the data transfer direction, the descriptor type, and the recipient. To retrieve a USB string descriptor, bmRequestType MUST be set to 10000000B (0x80).
bRequest: IN. This field specifies the request type. Set this field to the standard GET_DESCRIPTOR request code.
wValue: IN. This field is split into two parts for GET_DESCRIPTOR requests.
The high byte contains the descriptor type. To retrieve a string descriptor, set this byte to 0x03.
The low byte contains the descriptor's string index, which indicates where the descriptor is stored in firmware. To retrieve an OS string descriptor, set this byte to 0xEE.
wIndex: IN. This field specifies the descriptor's language ID. It must be set to 0 for OS string descriptors.
wLength: IN. This field specifies the length of the buffer, in bytes, that is to receive the string descriptor. The device is to respond to values ranging from 0x02-0xFF. Set wLength to 0x12 for OS string descriptors.
Data: OUT. This field is a pointer to the buffer that will receive the requested descriptor. The format of the descriptor is described in the following table.
For more details on how to send control requests, see [USB-SPC2.0].
If a device does not have a valid string descriptor at 0xEE, it responds with a Stall or Request Error.<4>
If an OS string descriptor request is successful, the device returns the descriptor in the request's Data field. Version 1.00 of the OS string descriptor has a fixed length of 18 bytes, with a structure as shown in the following table. This format MUST be used by all OS string descriptors.
|
Length |
Type |
Signature |
MS Vendor Code |
Pad |
|---|---|---|---|---|
|
0x14 |
0x03 |
MSFT100 |
unsigned byte |
0x00 |
Length: An unsigned byte and MUST be set to 0x14.
Type: An unsigned byte and MUST be set to 0x03.
Signature: A Unicode string and MUST be set to "MSFT100".
MS Vendor Code: An unsigned byte, it will be used to retrieve associated feature descriptors.
Pad: An unsigned byte and MUST be set to 0x00.
When processing the Signature and MS VendorCode fields:
The Signature field contains a Unicode character array that identifies the descriptor as an OS string descriptor and includes the version number. For version 1.00, this array must be set to "MSFT100" (0x4D00 0x5300 0x4600 0x5400 0x3100 0x3000 0x3000).
The MS VendorCode field is used to retrieve the associated feature descriptors. This code is used as Request field in TS_URB_CONTROL_VENDOR_OR_CLASS_REQUEST section 2.2.9.12.
Because independent hardware vendors can store string descriptors at any index, there is no guarantee that a string descriptor stored at 0xEE is an OS string descriptor.<5>