Changes

This is initial version. This API is effective from S60 3.2. onwards.

cusbdevicecontrolplugin.h

New public method

New public method

CUsbCMHandler

virtual TInt Handle(const RBuf8& aSetupPacket, RBuf8& aData) = 0;

New public method

CUsbCMHandler

virtual void Initialize(RDevUsbcClient& aUsbcClient, RUsbWatcher& aUsbWatcher, RUsb& aUsbManager) = 0;

Related APIs
  • CUsbCMHandler

Purpose

This API is intended for routing vendor-specific messages from the host to target handler. The API allows to extend functionality by using the ECOM framework. Messages, sent to handlers, are control messages, and therefore sent through end-point zero (EP0). Host can send vendor-specific control messages to handlers, to call the needed functionality on the device side.

Constraints

This API is valid for all S60 platforms starting from 3.2.

Classification and release information

This API is Local Connectivity Domain API and was first published in S60 release 3.2.

API description

The purpose of USB Device Control Plug-in API is to give standard extendable way for adding new functionality to devices, which communicates via USB, using vendor-specific commands.

Handlers are added as plug-ins, using ECOM framework. Each added plug-in solves some specific problem, and host, when needs some functionality from device side, just sends vendor-specific message to a device.

Through the API that message is received and processed by handler.

Through the API handlers get access to USB Client API, RUsb API, USB Watcher API, USB Watcher Info API. There is no need for handlers to make own connection to the mentioned API handles.

Some more information about the API can be found in USB Device Control Design Document.

Use cases

There are two important use cases.

The first use case is when USB Device Control initializes the handler with USB handles. Through those handles the handler can get access to USB Client API, RUsb API, USB Watcher API, USB Watcher Info API.

The second use case is when handler receives a message, processes it, and returns the result.

Internally, both of these use cases are handler specific. Only the interface is common.

API class structure

USB Device Control API is an abstract class CUsbCMHandler which is inherited from CBase. This inheritance is needed because handlers potentially place data to a heap. So, the API has also a virtual destructor, which destroys the ECOM session. Client must implement two abstract methods: CUsbCMHandler::Handle(), and CUsbCMHandler::Initialize(). Through CUsbCMHandler::Handle() handler receives messages and returns result, and through CUsbCMHandler::Initialize() handler receives handles to USB APIs.

Related APIs
  • CBase
  • CUsbCMHandler
  • CUsbCMHandler::Handle()
  • CUsbCMHandler::Initialize()

Using USB Device Control Plug-in API

This API is used so that handlers must implement interface's abstract methods. Functionality of the methods is handler specific.

Error handling

Handlers must return the error KErrNotSupported, if the received message is not recognized by the handler. Handlers must return KErrNone in a case if the request is processed. In case the error has happened during the request processing, handlers must return an error KErrGeneral.

Related APIs
  • KErrGeneral
  • KErrNone
  • KErrNotSupported

Memory overhead

Since all API methods are implemented by clients, there is no memory overhead problem with this API.

Extensions to the API

USB Device Control API can be extended in any possible way. One example is adding methods to the CUsbCMHandler class.

Related APIs
  • CUsbCMHandler

Limitations of the API

There are no limitations to the API.

Glossary

Abbreviations

USB Universal Serial Bus

API

Application Programming Interface

Definitions

None.

References

USB Device Control Design Document