Retrieving a Peripheral Device's String Descriptors

Purpose

When the Symbian platform phone is an A-device and is in host mode, it can retrieve the manufacturer and product string descriptors from an attached peripheral. It can also find out from the peripheral what languages it is capable of presenting these strings in. And finally it can request the strings in a particular one of the supported languages.

After a peripheral device has been enumerated and had its function drivers loaded.

Intended Audience

This document is for Symbian licensees who are implementing USB services, including host and On-The-Go services, on a Symbian device.

Required Background

For details of, and links to, the USB and On-The-Go (OTG) specifications on the USB Implementers Forum website, see The USB Manager library.

Setup and Configuration Requirements

The device you are designing needs to have Symbian's USB client and USB host/OTG stacks included in the ROM.

Also for the Symbian platform phone to retrieve a peripheral device's string descriptors the following conditions must be true:

• The Symbian platform phone must be the A-device and it must be in host mode.

• The remote peripheral needs to have been enumerated.

• The Symbian platform phone needs to have loaded function drivers successfully for the remote peripheral.

For information about confirming when the phone is an A-device and in host mode, see Monitoring the phone's USB host/OTG state.

For information about checking when a peripheral's function drivers have been successfully loaded, see Monitoring USB peripheral attachment and detachment.

Retrieving a peripheral's string descriptors

Basic Procedure

The high-level steps involved in retrieving a peripheral's string descriptors are shown here:

1. Find out what languages the peripheral can present its descriptors in.

2. Handle any mapping that is required because of the different language codes used by different manufacturers.

3. Request the descriptors (specifying a language, if desired).

Finding out which languages the peripheral can present its descriptors in

To find out which languages an attached peripheral can present its manufacturer and product string descriptors in, do the following:

1. Capture the peripheral's device ID.

2. Create an array to store its list of language ID's in (when they are returned).

3. Call the USB Manager's RUsb::GetSupportedLanguages() function, passing it the empty array and the peripheral's device ID.

For example:

TRequestStatus status;
TDeviceEventInformation deviceInfo;  //member variable for storing details of attaching peripheral 
usb.HostEventNotification(status, deviceInfo); //request notification of attachment of peripheral
User::WaitForRequest(status);     

TUint deviceId; //The number that identifies the particular USB peripheral that is being interrogated

if ((deviceInfo->iEventType == EDeviceAttachment) && 
   (deviceInfo->iError == KErrNone))
   {
    deviceId = deviceInfo->iDeviceId;   //Capture the peripheral's device ID
    RArray<TUint>& langIds;             //Create an array to store the device's list of language IDs in
    
    //Ask the device what languages it can present its descriptor strings in
    TInt err = usb.GetSupportedLanguages(deviceId, langIds); 
    if err == KErrNone 
     {
      //Handle error
     }
   }

Handling any mapping required between different lists of language codes

At the time of writing, most peripherals are likely to return an array containing at least the value 0x0409, which is the Microsoft language ID code for US English.

Note: The Microsoft list of language ID codes is not the same as the USB-IF list or the Symbian list of language ID codes.

Therefore, before deciding which language ID value to pass to the USB Manager functions for requesting descriptors in a particular language, you may need to look up the values returned by RUsb::GetSupportedLanguages() in arrays respresenting the Microsoft, USB-IF, and Symbian lists respectively.

Links to the USB-IF, Microsoft and Symbian lists of language identifiers are provided below:

• The USB Implementers Forum list of language identifiers

• The Microsoft list of language identifiers

• The Sybmian list of language identifiers

Retrieving a peripheral's string descriptors in a particular language

The USB Manager provides functions that enable you to retrieve a peripheral's manufacturer and product string descriptors. The functions for doing this are called: RUsb::GetManufacturerStringDescriptor() and RUsb::GetProductStringDescriptor().

These functions both take an aLangId parameter whose value will be selected from the list of values returned by the RUsb::GetSupportedLanguages() function (described above).

... 

TInt err = usb.GetSupportedLanguages(deviceId, langIds);  //Ask the device what languages it can 
                                                                                                                                                                                                               //present its descriptor strings in
    if (err == KErrNone) 
     {
      //Handle error
     }
     else
     {
       //Handle any mapping required to ascertain which languages are supported by the peripheral
       //Apply your own criteria for selecting the language you want to receieve the strings in
       //Request the descriptors in the language required
       err = usb.GetManufacturerStringDescriptor(chosenLanguageId); //Request manufacturer descriptor
       if (err == KErrNone) 
         {
            //Handle error
         }
       err = usb.GetProductStringDescriptor(chosenLanguageId);      //Request the product descriptor
       if (err == KErrNone) 
         {
            //Handle error
         }

If you do not specify a language when you request the peripheral's string descriptors, then the language used will be determined by the peripheral itself.