S60 5.0 Accessory Monitoring API

DN076056
CONFIDENTIAL

©Nokia 2007
This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia. This material also contains confidential information, which may not be disclosed to others without the prior written consent of Nokia.

Nokia is a registered trademark of Nokia Corporation. S60 and logo is a trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other company and product names mentioned herein may be trademarks or tradenames of their respective owners.

Change History

Version

Date

Status

Description

1.0

30.01.2007

Approved

 

 

 

 

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API description
Use cases
API class structure
Using Accessory Monitoring API
Getting accessory information
Getting all connected accessories
Getting accessory capabilities
Getting capability value for an accessory
Listening accessory connection/disconnection notifications
Listening all accessory connection/disconnection notifications
Listening accessory type connection/disconnection notifications
Listening a specific accessory connection/disconnection notifications
Handling Connected/Disconnected notifications
Error handling
Memory overhead
Extensions to the API
Glossary
Abbreviations
Definitions
References

Purpose

The purpose of this API is to provide information about connected accessories. It also provides a mechanism to detect accessory connection/disconnection notifications.

 


S60 or Symbian OS exceptions

Accessory Monitoring API requires S60 5.0 or later release.

API description

The Accessory Monitoring API interface offers accessory information about connected accessories. This API is meant to be used by clients that need to access information about connected accessories or clients that need notifications about accessories that connect/disconnect to the device. This API can be accessed by all S60 clients. The API provides stand-alone implementation units that are used by the client and the API provides information about the devices hardware resources.

 


Use cases

 


API class structure

Figure 1. API class structure

The CAccessoryMonitor class in Accessory Monitoring API has functions for getting connected accessory information and listening the accessory connection notifications. The client must implement the MAccessoryMonitorObserver class to receive accessory connection/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.

 


Using Accessory Monitoring API

Accessory Monitoring API can be used in:
  • Getting accessory information
  • Listening accessory connection/disconnection notifications
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/disconnection notifications can be listened with the StartListeningL() method. Connection notifications in 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.

Getting accessory information

Figure 2. Getting accessory information

The client gets connected accessory information.

Getting all connected accessories

The client creates 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. Getting accessory’s information from the array is presented in the following code example:

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 );

Getting accessory capabilities

A client gets the capabilities from an instance of CAccMonitorInfo with methods provided by this class. All the accessories capabilities are owned by this instance. One capability can be got with method AccCapabilityAtIndex() as is presented in the next example:

// Connected accessories are gotten as in 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;

Getting capability value for an accessory

A client gets a value for a capability. This value for the capability is gotten from the CAccMonitor class with the GetCapabilityValueL() method. An example of this is presented in the next example.

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

Listening accessory connection/disconnection notifications

Figure 4. Listening accessory connections/disconnection notifications

Listening all accessory connection/disconnection notifications

The client starts to listen to 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 );

Listening accessory type connection/disconnection notifications

The client can start listening specific types of accessory connection/disconnection notifications with the StartObservingL( aObserver, aCapabilityArray ) method. The accessory type that needs to be listened can defined with accessory capabilities. These capabilities are given as parameter to the function in an array. For example if the client wants to listen headset connection/disconnection notifications, the headset capability needs to be appended to an array and this array is given as parameter to the StartObservingL() function. Accessory Monitoring API notifies its clients with the Connected method when the listened accessory is connected. When the listened accessory is disconnected the clients are notified with the Disconnected() method. An example of starting to listen to headset connection/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 );

Listening a specific accessory connection/disconnection notifications

The client starts to listen a specific accessory connection/disconnection notifications with the StartObservingL( aObserver, aAccMonitorInfo ) method. An instance of CAccMonitorInfo of the accessory that needs to be listened is given as parameter to the StartObservingL() method, so this means that this accessory must have been connected to the terminal to get the information of this accessory. Accessory Monitoring API notifies its clients with the ConnectedL() method when the listened accessory is connected. When the listened accessory is disconnected the clients are notified with the DisconnectedL() method. An example of starting to listen to connection/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 );

Handling Connected/Disconnected notifications

When Accessory Monitoring API calls the ConnectedL() method that the client has implemented, the accessory that was listened is connected to the device. The information about the connected accessory is delivered in the parameter aAccessoryInfo. The content of this pointer must be copied to an instance of the CAccMonitorInfo class (with the CopyL() method) because the original pointer is destroyed by Accessory Monitoring API after this the ConnectedL() method has been 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 );
    }

Error handling

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

Memory overhead

No significant memory overhead. ROM consumption is 4KB.

Extensions to the API

No extensions.

Glossary

 


Abbreviations

Table 3.

Abbreviation

Description

API Application Programming Interface.
OS Operating System

 


Definitions

Table 4.

Definition

Description

Accessory A peripheral that is connected to the device.
Accessory capability A feature or a quality that an accessory has, for example 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.

References

None.


Back to top