Monitoring the phone's status as a USB peripheral device

Purpose

The USB Manager library's peripheral device state notification functions provide information to USB-aware applications about the phone's status as a USB peripheral. One of the ways you can use them is to monitor for cable insertion events that you are using as a trigger for starting USB services (on a peripheral-only phone). You can also use them to monitor the progress of the phone's attachment to a remote USB host.

Intended Audience

This document is for Symbian licensees who are implementing USB services on a Symbian device.

Required Background

For details of, and links to, the USB specification on the USB Implementers Forum website, see USB Manager library (refer especially to Chapter 9 of the USB specification).

Setup and Configuration Requirements

The device you are designing needs to have Symbian's USB client stack included in the ROM.

Finding out about the phone's status as a USB peripheral

Basic procedure

1. Make a request for the phone's current status as a USB peripheral.

2. Make an asynchronous request to be notified of any change in the phone's status as a peripheral.

3. If necessary, cancel a pending request for the phone's current status as a USB peripheral.

Using the USB device state notification functions

Getting the phone's current peripheral status

To get details of the current state of the phone's status as a peripheral, create a variable of type TUsbDeviceState, then pass it as a parameter in a call to the RUsb::GetDeviceState() function. For example:

    
RUsb usb;                         //create an instance of the USB Manager client interface
usb.Connect();                    //create a session between the client interface and the USBMAN server
TUsbDeviceState deviceState;          //create a variable to store the device state in
TInt err = usb.GetDeviceState(deviceState);  //get the device state
if err != KErrNone
 { 
   //Handle error
 }

The current state of the USB device is now stored in the variable of type TUsbDeviceState that you created (TUsbDeviceState is an enumerated type, which is defined in the file: ... epoc32\include\usbstates.h. Later (when you have followed the instructions in the next section), after you receive notification that there has been a change in the device state, you can call RUsb::GetDeviceState() again for an update.

Getting notified of changes to the phone's peripheral status

To get notifications of changes in the state of the phone's USB hardware:

1. Create an event mask variable to pass to the RUsb::DeviceStateNotification() function, specifying all of the events about which you want to receive notifications:

   TUint eventMask = (EUsbDeviceStateUndefined 
                       | EUsbDeviceStateDefault
                       | EUsbDeviceStateAttached
                       | EUsbDeviceStatePowered
                       | EUsbDeviceStateConfigured
                       | EUsbDeviceStateAddress
                       | EUsbDeviceStateSuspended 
                      );

   The values in this example include all possible values in the TUsbDeviceState enumerated type. When the phone is not acting as a USB peripheral, its state is EUsbDeviceStateUndefined; this would be the case, for example, if the phone supported USB On-The-Go (OTG) services and was acting as a USB host, if the phone was a peripheral-only device but no USB cable had been connected, or if a USB cable had been connected whose VBus line was not powered.

   Except for EUsbDeviceStateUndefined, these values map onto the states defined in Table 9-1 ("Visible Device States") of the USB 2.0 specification. If the device state is EUsbDeviceStateUndefined, then no USB cable is plugged into the phone (and USB services can be stopped and the session to the USB Manager closed; see Stopping USB services). If it is anything else, then a cable is plugged into the phone and USB services need to be started (see Starting USB services).

   Note: You can inspect the possible values for all USB device and service states in the file: ... epoc32\include\usbstates.h. This file defines the enumerated types TUsbServiceState and TUsbDeviceState.

2. Create a status indicator of TRequestStatus type and pass it, along with the deviceState and status variables, to the RUsb::DeviceStateNotification() function:

   TRequestStatus status;               \\Create a status indicator for the anysnchronous request    
   usb.DeviceStateNotification(eventMask, deviceState,    status); \\Request device state notification
   User::WaitForRequest(status);        \\Suspend program flow until state notification call returns
                                        \\deviceState will now contain the current state of the device

   Note: The example above uses an asynchronous request for purposes of illustration. However, you will probably need to wrap the RUsb::DeviceStateNotification() request in an active object. (For more information about these Symbian concepts, see Asynchronous programming and Active objects.)

   Note also that, each time you receive a notification of a change in the phone's USB peripheral status, you need to repeat the asynchronous request.

Cancelling a pending request for notification of changes to the phone's peripheral status

To cancel a pending request for notification of hardware state changes, use the RUsb::DeviceStateNotificationCancel() function:

usb.DeviceStateNotificationCancel();