Checking Whether USB Services are Running

Purpose

The USB Manager library's service state notification functions provide information to USB-aware applications about the state of USB services on the phone. They inform applications of whether USB services on the phone are currently idle, starting, started or stopping (or whether an error condition exists).

Intended Audience

This document is for platform developers who are implementing USB 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 stack included in the ROM.

Monitoring the state of the phone's USB services

Basic procedure

1. Make a request for the current state of USB services on the phone

2. Make an asynchronous request to be notified of any change in the state of USB services on the phone

3. If necessary, cancel a pending request for the current state of USB services

Finding out the current state of USB services

In a USB-aware application call the RUsb::GetServiceState() function. For example:

RUsb usb;                      //Create an instance of the USB Manager client interface
usb.Connect();                 //Create a session between the USB Manager client interface and server
TUsbServiceState serviceState;     //Create a service state variable to store the state in 
TInt err = usb.GetServiceState(serviceState);//Call the function, passing it a variable to populate 
if err != KErrNone
 { 
   //Handle error
 } 

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

The possible values of TUsbServiceState are: EUsbServiceIdle (this indicates that USB services have not been started), EUsbServiceStarting, EUsbServiceStarted and EUsbServiceStopping; and there is also an error state (EUsbServiceFatalError).

Getting notified of changes in the state of USB services

In a USB-aware application call the RUsb::ServiceStateNotification() function. For example:

TRequestStatus status;             //Create a status indicator for the asynchronous request
usb.ServiceStateNotification(serviceState, status);  \\Request service state notification
User::WaitForRequest(status);      //Suspend program flow until state notification call returns
if ( status != KErrNone )
  {
    // Handle error
  } 
                                   //The value of serviceState will now have been updated

The TUsbServiceState object holds the new USB service state. Note that the example above uses an asynchronous request for purposes of illustration. However, you will probably need to wrap the RUsb::ServiceStateNotification() 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 status of USB services on the phone, you need to repeat the asynchronous request.

Cancelling a pending service state notification request

To cancel a pending service state notification, call the RUsb::ServiceStateNotificationCancel() function.

usb.ServiceStateNotificationCancel();

You need to call this function from the active object's DoCancel() function.