The functionality described in this document is for OTG-enabled Symbian phones only.
This document tells you how to make a particular application into a USB control application which has exclusive access to the USB Manager library's functionality for controlling USB services.
The USB Manager library includes functionality for making an application's session with the USB Manager into a "control" session. This functionality is only for Symbian phones that support USB host/OTG services. Its purpose is to make sure that all USB control (including control of USB host/OTG services) resides with a single application.
When an application has set up a control session, then that application becomes the USB control application. If any application apart from the USB control application subsequently attempts to call a USB control function, it will receive an error code (KErrAccessDenied). For a list of the functions that are:
Available exclusively to the USB control application, see The USB Manager functions that are denied to other applications.
Available to other applications aswell, see The USB Manager functions that are available to other applications.
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 had Symbian's low-level host/OTG stack ported to it.
To perform the instructions in this document you need to have an application that you intend to make into a USB control application.
Symbian provide an example implementation of a USB control application. It demonstrates the correct usage of the USB Manager library functions for managing USB host/OTG services, and provides one way (which you might want to follow) of implementing the control application.
The Symbian example implementation is provided at the following location: sf/os/shortlinksrv/usbmgmt/usbmgrtest/usbcontrolapp.
The following tasks will be covered in this tutorial:
Calling the RUsb::SetCtlSessionMode() function
Basic procedure
In the application that you intend to make into the control application, include the function call RUsb::SetCtlSessionMode(). For example:
RUsb usb; User::LeaveIfError(usb.Connect()); TInt err = usb.SetCtlSessionMode(ETrue); if ( err != KErrNone ) { // handle an error }
This has the effect of giving the application that called the RUsb::SetCtlSessionMode() function exclusive access to the USB control functions listed in the next section. This exclusive access remains with the application for as long as the USB Manager session in which the function was called remains open.
When you have successfully called the RUsb::SetCtlSessionMode() function with ETrue as the parameter, all other applications are prevented from calling the USB Manager functions listed below. These functions will return KErrAccessDenied to any applications that call them apart from the USB control application. Access to them remains exclusive to the control application as long as its USB session remains open or until it calls RUsb::SetCtlSessionMode(EFalse).
When you have called the RUsb::SetCtlSessionMode() function, all other applications are prevented from calling the USB Manager functions listed in the previous section. However, other applications, particularly your USB-aware applications, can still access the following USB Manager library functions: