Monitoring requests for the phone to become a USB host

Purpose

The USB Manager includes a function that allows the USB control application to monitor the USB Manager for errors and messages. Among the possible messages are notifications of session requests from local applications and session requests (in the form of Session Request Protocol (SRP) signals) from remotely attached USB devices.

• Detecting session requests from local applications

  When a local application wants to request access to the bus, it calls the RUsb::RequestSession() function (see Making requests from a local application for the phone to become USB host). This session request will then be propagated to the USB control application in the form of a message notification from the USB Manager. If the control application decides to grant the session request, it will first make sure that USB services are running (see Starting USB services, and will then call RUsb::BusRequest() to attempt to make the phone become the USB host.

• Detecting SRP signalling from remotely attached B-devices

  When a B-device wants to become the USB host (while VBus is not powered), the B-device will use SRP signalling to indicate this to the A-device. When the A-device detects an in-coming SRP signal, the signal is propagated to the USB control application in the form of a message notification from the USB Manager. If the USB control application decides to grant the attached B-device's request to become the USB host (and therefore for the A-device to become the peripheral), it will first make sure that USB services are running (see Starting USB services, and will then call RUsb::BusRespondSrp().

  In this situation, one of two outcomes is possible depending on whether the remote device (the one that issued the SRP signal) supports Host Negotiation Protocol (HNP) or not. If the remote B-device:

  • supports HNP, then the consequence of the A-device's call to RUsb::BusRespondSrp() will be that a role-swap occurs and the B-device becomes the USB host (while remaining the B-device).

  • does not support HNP, then the consequence of the A-device's call to RUsb::BusRespondSrp() will be that the A-device simply becomes the USB host.

To monitor these session requests from local applications and remote devices, the USB control application must have an RUsb::MessageNotification() request pending with USB Manager. (This is mechanism by which the USB Manager propagates the requests to the control application.)

There is also a function for cancelling a pending request for notification of such requests. It is called RUsb::MessageNotificationCancel().:

Both when a local application calls RUsb::RequestSession(), and when a remotely attached peripheral (that does not support HNP) has sent an SRP request message to the OTG stack on the device, the USB control application's response is to request the bus. The way it attempts this, however, is different in each case. (The RUsb::MessageNotification() function is also used to inform the USB control application (and other USB-aware applications) of other events, for example, KErrUsbOTGVbusError; some special processing is required to clear a KErrUsbOTGVbusError error.) For more information, see Controlling when the phone is the USB host.

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 stack, host stack and OTG components included in the ROM (see Enabling the USB Manager library's host/OTG functions).

Receiving notification of requests for the phone to become host

Basic Procedure

The high-level steps involved in making sure your control application is notified of requests for the phone to become the USB host are:

• subscribing to the USB Manager for message notifications

Subscribing to the USB Manager for message notifications

To subscribe to the USB Manager for message notifications (including requests from a local application or remote device for the phone to activate USB services and either become the USB host or initiate a role-swap), do the following:

1. Make an asynchronous call to RUsb::MessageNotification().

   RUsb usb;
   User::LeaveIfError(usb.Connect());
   
   ...
   
   TRequestStatus status;
   TInt message;
   usb.MessageNotification(status, message);
   User::WaitForRequest(status);                   //Note that this is an instance when it 
                                                   //is appropriate to use a Symbian active object
                                       
   if ( status == KerrNone )
       {
       // use it
       switch (message)
           {
            case KErrUsbOtgVbusError:
                  //Handle event
                  break;
               case KErrUsbDeviceRejected:
                        //Handle event
                  break;
               case KErrUsbDeviceFailed:
                        //Handle event
                  break;
               case KErrUsbBadDevice:
                        //Handle event
                  break;
               case KErrUsbBadHubPosition:
                        //Handle event
                  break;
               case KErrUsbBadHub:
                        //Handle event
                  break;
               case KErrUsbEventOverflow:     
                        //Handle event
                  break;
            case KUsbMessageSrpReceived:        // An SRP request has been received from a remote device
                                                   // Start USB services (if they are not already running)
                 Tint err = usb.BusRespondSrp(); // Call the RUsb::BusRespondSrp() function 
                 if (err != KerrNone)
                  {  
                     //Handle error 
                  }
                  break;
   
            case KUsbMessageRequestSession:     // A request for the phone to become host has been 
                                                   // received from a local application 
                                             // Start USB services (if they are not already running)
                 Tint err = usb.BusRequest();// Call the RUsb::BusRequest() function 
                 if (err != KerrNone)
                  {  
                     //Handle error 
                  }
                  break;
             …
               default:
                          // default processing
           }
       }
   else
      {
      // handle an error
      }
   
   ...
   
   usb.Close();

   Note: The constants listed in the case statement above are defined in the file: ...epoc32\include\usbshared.h.

   For information about starting USB services, see Starting USB services.

2. Repeat the asynchronous call to RUsb::MessageNotification() to ensure that a pending request for notification captures the next message.

3. For further information about session requests from local applications and SRP requests from remotely attached devices, see Controlling when the phone is the USB host.