The USB Manager Library Overview

This document introduces you to the USB Manager library.

Purpose

The USB Manager library provides a client interface to functionality for monitoring, controlling and configuring USB services on a Symbian device.

Intended Audience

This document is for Symbian licensees who are implementing USB services, including (if applicable) host and On-The-Go services, on a Symbian device.

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.

The USB Manager Library Details

The DLL that provides the functionality and the library to which your code must link are identified below.

DLL LIB Description

usbman.dll

usbman.lib

The library for monitoring, controlling and configuring USB services, including USB host and OTG services.

Architectural Relationship

The USB Manager library is one of the libraries of the USB Manager Symbian platform component. The functionality it provides has been implemented using Symbian's client-server architecture: the usbman.dll file represents the client side of a client-server relationship, and the server side is represented either by an executable called usbsvr.exe or by an executable called usbsvrotg.exe (depending on whether your device supports USB host/OTG connectivity or not).

The usbsvr.exe file supports USB services for a Symbian phone that is designed to perform as a USB peripheral only.

The usbsvrotg.exe file supports USB services for a Symbian phone that can additionally perform as a USB host with On-The-Go (OTG) capabilities (enabling it to swap roles automatically with a remotely connected USB device).

The usbsvrotg.exe file includes functionality for monitoring and controlling USB host/OTG services on a Symbian device. This functionality is specifically for devices that have had Symbian's low-level USB host/OTG stack ported to their hardware.

If the device you are designing has had Symbian's low-level USB host/OTG stack ported to it, then you need to include the executable called usbsvrotg.exe (instead of usbsvr.exe) when you build the ROM. For more information, including important information about the name of the file (which will in fact always be usbsvr.exe) when it appears in the ROM, see Enabling the USB Manager library's host/OTG functions.

Description

The USB Manager library provides the client interface to functionality for:

  • Starting and stopping USB services

  • Monitoring USB services

  • Inspecting, selecting and loading particular USB personalities

For devices that support USB host/OTG services (in other words, devices that have had Symbian's low-level USB host/OTG stack ported to their hardware), the USB Manager library also provides the client interface to functionality that enables:

  • a single USB control application to control USB host/OTG services on the device,

  • a single USB control application and any USB-aware applications to monitor host/OTG services on the device,

  • any USB-aware application to tell the USB Manager that it wants the phone to become the USB host.

Key USB Manager Classes

There is only one key class for the USB Manager library. It is called RUsb.

Using the USB Manager

The USB Manager libarary presents different APIs, depending on whether the Symbian platform phone it is running on supports USB host/OTG services.

This section describes the functionality available to the following three different categories of application:

This section also describes the USB host/OTG publish-and-subscribe properties associated with the USB Manager:

Any application

The USB Manager provides functionality to any application with the necessary capabilities (as specified for each function in the file <file>...epoc32\include\usbman.h</file>) for:
  • Starting USB service

  • Stopping USB services<

  • Checking whether USB services are running

  • Monitoring the phone's status as a USB peripheral device

  • Monitoring USB peripheral attachment and detachment

  • Discovering details of the USB personalities available Loading a USB personality

Note: A Symbian platform phone that supports USB host services (and therefore has a USB control application running), only the USB control application can start and stop the USB Manager or load a different USB personality.

The USB control application (on an OTG phone)

The USB Manager library includes functionality for controlling USB host/OTG services on a Symbian device. (This functionality is only available on devices that have had the Symbian low-level USB host/OTG stack ported to their hardware.) To enable this functionality, you need to include the executable usbsvrotg.exe (instead of usbsvr.exe) when you build the ROM. For information about how to do this, see:

The USB Manager library's host/OTG control functionality can only be accessed from a single application, referred to as the USB control application. An application becomes the USB control application by locking other applications out of the USB Manager's control functionality. For instructions about how to make an application into the USB control application, see:

The USB Manager library provides functionality exclusively to the USB control application for:

The USB control application (if it is running) also has exclusive control over starting and stopping USB services and loading USB personalities.

USB-aware applications (on an OTG phone)

A USB-aware application on a Symbian platform phone that supports host/OTG services can request the USB Manager to notify the USB control application if it needs it to attempt to make the phone become the USB host.

The reason these requests need to pass through the USB control application is to enable device-wide policies to be applied to the decisions that grant or deny them. For example, if the phone's user has deliberately switched USB services off, it would not be appropriate to grant a request from a local application to make the phone become USB host.

An application will need to do this, for example, when it wants to make use of a remotely attached USB peripheral.

For more information, see:

Host/OTG publish-and-subscribe properties

There are a number of publish-and-subscribe property keys associated with the USB Manager library's USB host/OTG functionality. For information about these, see: Monitoring VBus, ID-pin, OTG state and bus activity

Related concepts

Related information