Making requests from a local application for the phone to become USB host

Purpose

The USB control application is the only application that can directly attempt to make the phone become the USB host. Therefore the USB Manager provides a function (RUsb::RequestSession()) that allows USB-aware applications to request it to do so. When a local application calls this function, USB Manger notifies the USB control application (by means of a pending RUsb::MessageNotfication() request). If the control application decides to grant the request, it issues an RUsb::BusRequest() function, which causes the USB Manager to attempt to make the phone become the USB host (see Controlling when the phone is the USB host).

This sequence of events is summarised in the diagram below.

Note: The control application has the job of making policy decisions. Therefore it might choose not to grant a local application's session request, for example, because USB support has been globally disabled on the phone, or because battery power is very low.

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 phone you are developing code for needs to have Symbian's USB client stack, host stack and OTG components included in the ROM (see Enabling the USB Manager library's host/OTG functions).

You need to add the functionality described in this document into a USB-aware application on the Symbian platform phone.

Using the USB Manager's request session function for local applications

There is a single main pre-requisite for a request by a local application to make the phone become the USB host. The pre-requisite is that, as a result of an action by the phone's user, the local application wants to test whether a USB perpheral is attached that can be of use to it. This pre-requisite (concerning user action) is important because it is insisted upon by the USB On-The-Go specification. When two OTG devices that are capable of role-swapping are connected together, it is the one on which the user is performing an action that must initiate an attempt to make the phone become USB host.

On Symbian phones, applications must make this request by calling the USB Manager's RUsb::RequestSession() function.

An OTG device that does not power VBus on the insertion of an A plug will also use RUsb::RequestSession() to trigger the raising of VBus when an action by the phone's user indicates that this is desirable. The user action may be, for example, to select a specifically USB-related option from the user interface (something like "Activate USB Host", for example). Alternatively, it may be an indirect action: for example, in a phone containing Symbian's Mass Storage Function Driver implementation, when the user requests a list of available memory drives, this will result in a call by a local USB-aware application to RUsb::RequestSession(), because the phone needs to become the USB host to enumerate an attached mass storage device and include the device in its list of available drives. (In fact, in the case of mass storage, the USB-aware application that calls the Usb::RequestSession() function is the file system itself.)

Note: Although the RUsb::RequestSession() function does return a value indicating the success or failure of the function call, it does not return any explicit information to the calling application as to whether the phone has actually become the USB host. This means that the calling application must depend for this information on the consequences of the phone's becoming host being apparent in some way. In the case of a user requesting a list of available drives, for example, the phone's achievement of the role of host will be apparent to the calling application from the appearance in the filing system of mass storage drives on a remotely attached device.

The important point to remember is that a call to RUsb::RequestSession() is a speculative action by the local application. The application's requirement is for some specific type of device to enumerate and use. So, for example, the phone might become the USB host as a result of a local application calling RUsb::RequestSession(), but if the application wants to enumerate a camera and it finds a mass storage device it will be unable to accomplish its purpose.

Basic Procedure

The high level steps involved are shown here:

• Subscribe to the publish-and-subscribe key for monitoring OTG state.

• Handle any user action (from the user interface) that requires the phone to become USB host.

• Call the USB Manager's host-role requesting function.

• If the phone becomes USB host, communicate with the attached peripheral.

Calling the USB Manager's USB host-role requesting function

Before editing your USB-aware application by following the instructions below, note that the USB control application is assumed to take full responsibility for starting USB services before it grants any request from a USB-aware application to make the phone become the USB host.

1. In your USB-aware application, create a publish-and-subscribe property resource to use to monitor the phone's OTG state (for more information, see Monitoring the phone's USB host/OTG state).

   RProperty otgState;
   User::LeaveIfError(otgState.Attach(KUidUsbManCategory, KUsbOtgStateProperty));

2. Subscribe for notification of the next change to the OTG state.

   TRequestStatus status;
   otgState.Subscribe(status);

3. Handle any user action (communicated from the phone's user interface) that requires the phone to become the USB host.

4. In your USB-aware application, call the USB Manager's host-role requesting function (RUsb::RequestSession()) and wait for notification that the OTG state has changed.

   //  Some user action has caused the local application to become host and
   //  see if any peripherals are attached
   
   TInt err;
   err=RUsb::RequestSession();
   if (err != KErrNone)
     {
     // Handle error
     }
   User::WaitForRequest(status);

5. When it has changed, re-subscribe for notification of OTG state changes, and get the current state value.

   otgState.Subscribe(status);
   TInt stateValue;
   otgState.Get(stateValue);
   
   //    The device may now be in either A-Host or B-Host role (if the RequestSession() was successful),
   // in which case the attached peripheral will be enumerated and available for communication.

6. If the OTG state is either A-Host or B-Host, the phone's host stack will enumerate the attached peripheral and it will be possible to detect Function Drivers loading (see Monitoring USB peripheral attachment and detachment).