The USB Manager Extension Plug-in Library Overview

This document introduces you to the USB Manager Extension Plug-in interface library usbmanextensionplugin.dll.

You need to read it in conjunction with The USB Battery Charging Plug-in Library Overview.

Purpose

The USB Manager Extension Plug-in library provides an Ecom interface to Symbian's reference battery charging plug-in, usbbatterychargingplugin.dll.

Support for USB battery charging was added to Symbian platform by means of an Ecom interface and reference plug-in combination; this allowed Symbian to extend the USB Manager's functionality with the battery charging features without forcing licencees to re-compile the USB Manager.

Intended Audience

This document is for Symbian licensees who are implementing support for battery charging over USB.

The USB Manager Extension Plug-in Library Details

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

DLL LIB Short description

usbmanextensionplugin.dll

usbmanextensionplugin.lib

Ecom interface whose client implementation is the USB battery charging plug-in.

Architectural Relationship

The main logic for battery charging is in the Symbian reference implementation of the client to this Ecom interface.

The Ecom interface (the USB Manager Extension Plug-in library) provides the battery charging client implementation with:

  • Access to the USB Logical Device Driver (LDD).

    This is required to enable the client implementation to set the bMaxPower field in the configuration descriptor.

  • Device state change notifications from the USB Manager.

    These enable the client implementation to know when the device is in a "configured" state and is therefore entitled to draw power from the host.

Description

This Ecom interface's battery charging client implementation sets the bMaxPower field of the Symbian device's USB configuration descriptor. This is the field that informs the USB host of the maximum power the device will consume when it is in a "configured" state. The USB host will decide whether it can supply the level of current specified; if it cannot, it will not put the device into a "configured" state. Only when a device is in a "configured" state is it entitled to draw the current it specified in bMaxPower during enumeration.

To enable its client implementation to set the bMaxPower value, the USB Manager Extension Plug-in library provides a function for the client to call which returns a handle to an instance of the Symbian USB client Logical Device Driver (see Using the USB Manager Extension Plug-in library below).

This Ecom interface also enables its client implementation to receive device state change notifications from the USB Manager. This enables it to know, for example, when the device is "configured" (and so can draw power) and when it is in a suspend state (and so must draw no more power than it is entitled to draw in a suspend state).

Key USB Manager Extension Plug-in library Classes

The key classes belonging to the USB Manager Extension Plug-in library are listed in the table below: and MUsbDeviceNotify.

Classes

Description

CUsbmanExtensionPlugin

This class defines the Ecom interface whose client implementation is the battery charging reference client. This class creates an instance of the MUsbManExtensionPluginObserver (see next item in this table) which provides the battery charging client with the access it needs to the Logical Device Driver and to device state notifications.

MUsbManExtensionPluginObserver

The battery charging reference client calls the DevUsbcClient() function belonging to this mixin class (to obtain a handle to the Logical Device Driver), and the RegisterStateObserverL function to register for device state notifications with the USB Manager.

MUsbDeviceNotify

The mixin class that the USB Manager uses to notify the Ecom interface (and its other registered recipients) of device state changes.

Using the USB Manager Extension Plug-in library

The USB Manager Extension Plug-in Ecom interface provides the following categories of functionality to its client implementation (the USB battery charging plug-in):

  • Enables it to get a handle to an RDevUsbcClient object

  • Enables it to register with the USB Manager for device state change notifications

Getting a handle to an RDevUsbcClient (to access the configuration descriptor)

Registering with the USB Manager for device state change notifications

To register for device state change notifications the client implementation calls the Ecom interface's MUsbmanExtensionPluginObserver::RegisterStateObserverL() in its second-phase contructor. The RegisterStateObserver() function takes as a parameter a reference to an object of the class MUsbDeviceNotify, and the USB Manager adds the object to its list of recipients for device state change notifications.