accessory monitoring api Specification

Contents

1 Overview

API for monitoring accessory information


API categorypublic
API typec++
API librariesaccmonitor.lib
Location/sf/os/deviceio/deviceio_pub/accessory_monitoring_api
Buildfiles/sf/os/deviceio/deviceio_pub/accessory_monitoring_api/group/bld.inf


1.1 Description

This API is intended to be used by clients that need to access information about connected accessories or clients that need notifications about accessories that connect or disconnect to the device. The API provides stand-alone implementation units that are used by clients.

1.2 Changes

The Accessory Monitoring API is introduced in Symbian OS, S60 5.0.

1.3 Use Cases

  • Retrieving connected accessories.
  • Retrieving accessory capabilities.
  • Retrieving capability values.
  • Listening for all accessory notifications.
  • Listening for accessory type notifications.
  • Listening for specific accessory notifications.
  • Handling connected or disconnected notifications.

1.4 Class Structure

Summary of API classes and header files
ClassesFiles
CAccMonitor /epoc32/include/AccMonitor.h CAccMonitorInfo /epoc32/include/AccMonitorInfo.h, /epoc32/include/AccMonitorInfo.inl MAccMonitorObserver /epoc32/include/AccMonitor.h No classes/epoc32/include/AccMonitorCapabilities.h
API class structure
API class structure

The CAccessoryMonitor class in Accessory Monitoring API provides functions for retrieving connected accessory information and listening for the accessory connection notifications. The client must implement the MAccessoryMonitorObserver class to receive accessory connection or disconnection notifications. Information about one accessory is wrapped to instances of class CAccMonitorInfo . Accessory capability definitions for Accessory Monitoring API are declared in the accmonitorcapabilities.h file.

2 Using The API

The Accessory Monitoring API can be used in:

Accessory information from Accessory Monitoring API is presented as instances of the CAccMonitorInfo class. This class contains accessory capabilities and these capabilities describe the features of one accessory. Some capabilities can be defined more precisely by defining values to these capabilities. These values can be asked from the Accessory Monitoring API.

Accessory connection or disconnection notifications can be listened for using the StartListeningL() method. Connection notifications on client side are received from the MAccMonitorObserver class. The client must implement the pure virtual functions from this class. Connection notifications are received through the ConnectedL() method and disconnection notifications are received through the DisconnectedL() method.

2.1 Retrieving the accessory information

Retrieving the accessory information
Retrieving the accessory information

2.1.1 Retrieving all connected accessories

Clients create an instance of the CAccMonitor class and calls the GetConnectedAccessoriesL() method. This method returns all connected accessories in an array that contains instances of the CAccMonitorInfo class. The following example shows how to retrieve accessory's information from the arrayÖ 

CAccMonitor* accMonitor = CAccMonitor::NewLC();
RConnectedAccessories connectedAccessories;
CleanupClosePushL( connectedAccessories );
accMonitor->GetConnectedAccessoriesL( connectedAccessories );
count = connectedAccessories.Count();
for( TInt i = 0; i != count; i++ )
   {
   if( connectedAccessories( i )->AccDeviceType() == KAccMonHeadset );
	 		{
       _LIT( KHeadsetText, "A headset is connected" );
       RDebug::Printf( KHeadsetText );
			}
   }
CleanupStack::PopAndDestroy( &connectedAccessories );
CleanupStack::PopAndDestroy( accMonitor );

2.1.2 Retrieving accessory capabilities

Clients retrieve the capabilities information from an instance of CAccMonitorInfo All the accessories capabilities are owned by this instance. Use AccCapabilityAtIndex() to retrieve one capability as shown in the following example: 

// Connected accessories are retrieved as shown in the previous example.
const TInt lastConnectedAccessory( 0 );
// The accessory that was connected last is first in the array
cAccMonitorInfo* accInfo
		= cAccMonitorInfo::NewL( connectedAccessories( lastConnectedAccessory ) );
for( TInt i = 0; i != accInfo->Count(); i++ )
   {
   if( accInfo->AccCapabilityAtIndex( i ) == KAccMonStereoAudio )
       {
       // Some accessory has stereo audio capability
			_LIT( StereoText, "Stereo audio can be played to some accessory" );
			RDebug::Printf( StereoText );
       }
   }
delete accInfo;

2.1.3 Retrieving the capability value for an accessory

Clients can retrieve a value for a capability using the CAccMonitor class's GetCapabilityValueL() method. 

// Connected accessories and their capabilities are retieved in previous examples
TAccMonitorCapability capability( KAccMonVideoOut );
TInt value( 0 );
accMonitor->GetCapabilityValueL( accInfo, capability, value );
// Capability value is retuned to value variable
Retrieving capability value for an accessory
Retrieving capability value for an accessory

2.2 Listening for accessory connection or disconnection notifications

Listening for accessory connections or disconnection notifications
Listening for accessory connections or disconnection notifications

2.2.1 Listening for all accessory connection or disconnection notifications

Clients start to listen for all accessory connection disconnection notifications with the StartObservingL( aObserver ) method. Accessory Monitoring API notifies its clients with the ConnectedL() method when an accessory is connected. When an accessory is disconnected, the clients are notified with the DisconnectedL method. 

CAccMonitor* accMonitor = CAccMonitor::NewLC()
TBool isObserving = accMonitor->IsObserving();
if( isObserving )
	{
  accMonitor->StartObserverL( this );
  }
CleanupStack::PopAndDestroy( accMonitor );

2.2.2 Listening for accessory type connection or disconnection notifications

Clients can start listening for specific types of accessory connection or disconnection notifications with the StartObservingL( aObserver, aCapabilityArray ) method. The accessory type that needs to be listened can be defined with accessory capabilities. These capabilities are given as a parameter to the function in an array. For example if the client wants to listen for headset connection or disconnection notifications, the headset capability needs to be appended to an array and this array is given as a parameter to the StartObservingL() function.

The Accessory Monitoring API notifies its clients with the Connected method when the monitored accessory is connected. When the monitored accessory is disconnected the clients are notified with the Disconnected() method. The following example starts to listen to headset connection or disconnection notifications: 

CAccMonitor* accMonitor = CAccMonitor::NewLC();
RAccMonCapabilityArray capabilityArray;
CleanupClosePushL( capabilityArray );
capabilityArray.Append( KAccMonHeadset );
TBool isObserving = accMonitor->IsObserving();
if( isObserving )
	{
  accMonitor->StartObserverL( this, capabilityArray );
	}
CleanupStack::PopAndDestroy( &capabilityArray );
CleanupStack::PopAndDestroy( accMonitor );

2.2.3 Listening for a specific accessory's connection or disconnection notifications

Clients start to listen for a specific accessory's connection or disconnection notifications through the StartObservingL( aObserver, aAccMonitorInfo ) method. An instance of

CAccMonitorInfo of the accessory that needs to be monitored is given as parameter to the StartObservingL() method. This means that this accessory must have been connected to the terminal to get the information of this accessory. The Accessory Monitoring API notifies its clients using the ConnectedL() method when the monitored accessory is connected. When the monitored accessory is disconnected, clients are notified with the DisconnectedL() method. The following example starts to listen for connection or disconnection notifications from a specific accessory that is connected: 
CAccMonitor* accMonitor = CAccMonitor::NewLC();
RConnectedAccessories array;
CleanupClosePushL( array );
accMonitor->GetConnectedAccessoryL( array );
if( isObserving )
	{
  for( TInt i = 0; count != i; i++ )
		{
		if( array( i )->AccDeviceType() == KAccMonHeadset
		&& array( i )->AccPhysicalConnection() == KAccMonWired )
			{
			// Start observing just that wired headset that is connected
			accMonitor->StartObserverL( this, array( i ) );
			break;
			}
		}
  	}
CleanupStack::PopAndDestroy( &array );
CleanupStack::PopAndDestroy( accMonitor );

2.2.4 Handling connected or disconnected notifications

The Accessory Monitoring API calls the ConnectedL() method that the client implements to retrieve information about the connected accessory. The information is delivered in the aAccessoryInfo parameter. The content of this pointer must be copied to an instance of the

CAccMonitorInfo class using the CopyL() method because the original pointer is destroyed by the Accessory Monitoring API after the ConnectedL() method is run. 
void CMyAccMonitorTest::ConnectedL( CAccMonitorInfo* aAccessoryInfo )
    {
    //Reserve memory for the accessory information instance
		iAccessoryInfo = CAccMonitorInfo::NewL();
	  // Notification about the connected accessory. aAccessoryInfo must
    // be copied because the original pointer is deleted after connected method
    iAccessoryInfo->CopyL( aAccessoryInfo );
    }

2.3 Error handling

When a leave occurs in the active object's RunL() method, the AccMonitorObserverError() method is called by the Accessory Monitoring API. This method must be implemented by the client, otherwise the standard Symbian error handling mechanism is used.

2.4 Memory and Performance Considerations

No significant memory overhead. ROM consumption is 4KB.

3 Glossary

3.1 Abbreviations

API Application Programming Interface
OS Operating System

3.2 Definitions

Definition Description
Accessory A peripheral that is connected to the device.
Accessory capability A feature or a quality that an accessory has, for example the stereo audio capability means that the accessory has capability for handling stereo audio.
Accessory type Accessory that is defined with different features. For example a mono headset is an accessory that has headset capability and mono audio capability.
Capability value A value that the accessory capability can have.