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.
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.
Accessory Monitoring API can be used in:
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.
Figure 2: Getting accessory information
The client gets connected accessory information.
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 );
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;
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
Figure 4: Listening accessory connections/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 Disconnected
L() method.
CAccMonitor* accMonitor = CAccMonitor::NewLC() TBool isObserving = accMonitor->IsObserving(); if( isObserving ) { accMonitor->StartObserverL( this ); } CleanupStack::PopAndDestroy( accMonitor );
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 );
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 Connected
L() method when the listened
accessory is connected. When the listened accessory is disconnected the clients
are notified with the Disconnected
L() 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 );
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 ); }
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.
No significant memory overhead. ROM consumption is 4KB.
No extensions.