Accessory Monitoring API
Changes in Accessory Monitoring API documentation
Changes in Accessory Monitoring API
Purpose
The purpose of this API is to provide information about connected
accessories. It also provides a mechanism to detect accessory connection/disconnection
notifications.
Constraints
Accessory Monitoring API requires S60 5th Edition or later releases.
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.The API provides stand-alone implementation units that
are used by the client and the API provides information about the
devices hardware resources.
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.
Related APIs
-
CAccMonitorInfo
-
CAccessoryMonitor
-
MAccessoryMonitorObserver
Using Accessory Monitoring API
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/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
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 );
Related APIs
-
CAccMonitor
-
CAccMonitorInfo
-
GetConnectedAccessoriesL()
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;
Related APIs
-
AccCapabilityAtIndex()
-
CAccMonitorInfo
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
Related APIs
-
CAccMonitor
-
GetCapabilityValueL()
Listening accessory connection/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
Disconnected
L() method.
CAccMonitor* accMonitor = CAccMonitor::NewLC()
TBool isObserving = accMonitor->IsObserving();
if( isObserving )
{
accMonitor->StartObserverL( this );
}
CleanupStack::PopAndDestroy( accMonitor );
Related APIs
-
ConnectedL()
-
Disconnected
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 );
Related APIs
-
Connected
-
Disconnected()
-
StartObservingL()
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
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 );
Related APIs
-
CAccMonitorInfo
-
Connected
-
Disconnected
-
StartObservingL()
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 );
}
Related APIs
-
CAccMonitorInfo
-
ConnectedL()
-
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 error handling
is used.
Related APIs
-
AccMonitorObserverError()
-
RunL()
Memory overhead
No significant memory overhead. ROM consumption is 4KB.
Extensions to the API
No extensions.
Related APIs
-
CAccMonitorInfo
-
ConnectedL()
-
DisconnectedL()
-
MAccMonitorObserver
-
StartListeningL()
Glossary
Abbreviations
|
API
|
Application Programming Interface.
|
|
OS
|
Operating System
|
Definitions
|
|
|
|
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.
|
