diff -r 000000000000 -r 4e1aa6a622a0 devicesrv_pub/accessory_monitoring_api/inc/AccMonitor.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/devicesrv_pub/accessory_monitoring_api/inc/AccMonitor.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,293 @@ +/* +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: This API is used for getting +* information about connected accessories. The accessory +* connections and disconnections can also be listened through +* this API. +* +*/ + + +#ifndef ACCMONITOR_H +#define ACCMONITOR_H + +// INCLUDES +#include +#include + +// FORWARD DECLARATIONS +class MAccMonitorObserver; + +// CLASS DECLARATION +/** +* The Accessory Monitoring API interface offers accessory information about +* connected accessories. It also offers an easy-to-use implementation of a +* CActive-based wrapper for accessory connection status changed event +* notifications. The clients can get information about the connected +* accessories capabilities and, if the capabilities have values, get the +* values from these capabilites. This API consist of classes CAccMonitor, +* CAccMonitorInfo and MAccMonitorObserver. If the user wants to use the +* observer this API offers, the user has to implement callback function +* for receiving accessory connection and disconnection status notifications. +* The connected accessories are offered to the client in an array. This array +* presents the connected accessories as instances of CAccMonitorInfo class. +* The CAccMonitorInfo offers accessory information encapsulated to a class. It +* presents accessory device type, physical connection and device address +* information with basic getter functions. The rest of the accessories +* features are contained in an array. This array can be accessed with functions +* that are in CAccMonitorInfo. +* This class is not intended for user derivation. +* +* Usage: +* +* Example query for some accessory's information. All connected accessories are +* fetched and the instance of CAccessoryInfo is getted: +* @code +* CAccMonitor* accMonitor = CAccMonitor::NewLC(); +* RConnectedAccessories connectedAccessories; +* CleanupClosePushL( connectedAccessories ); +* accMonitor->GetConnectedAccessoriesL( connectedAccessories ); +* CAccMonitorInfo* accInfo = CAccMonitorInfo::NewLC(); +* TInt countOfArray = connectedAccessories.Count(); +* for( TInt i = 0; i != countOfArray; i++ ) +* { +* TAccMonCapability deviceType = connectedAccessories[ i ]->AccDeviceType(); +* if( deviceType == KAccMonHeadset ) +* { +* // Some Headset is connected, get the information to accInfo +* accInfo->CopyL( connectedAccessories[ i ] ); +* } +* } +* // Destroy the pointers from the array, because those are owned by the client +* CleanupStack::PopAndDestroy( accInfo ); +* CleanupStack::PopAndDestroy( &connectedAccessories ); +* CleanupStack::PopAndDestroy( accMonitor ); +* @endcode +* +* Example query for some accessorys capabilties. The user has fetched the +* CAccMonitorInfo to accInfo instance from connected accessories: +* @code +* TInt arrayCount = accInfo->Count(); +* for( TInt i = 0; i != arrayCount; i++ ) +* { +* TAccMonCapability accCapa = accInfo->AccCapabilityAtIndex( i ); +* if( accCapa == KAccMonStereoAudio ) +* { +* // Accessory has stereo capability, handle this situation. +* } +* } +* @endcode +* +* Initialization example for the observer(from a class that implements +* MAccMonitorObserver interface). +* Observer starts to listen for headset connects: +* @code +* CAccMonitor* accMonitor = CAccMonitor::NewLC(); +* RAccMonCapabilityArray capabilityArray; +* CleanupClosePushL( capabilityArray ); +* capabilityArray.Append( KAccMonHeadset ); +* accMonitor->StartObservingL( this, capabilityArray ); +* CleanupStack::PopAndDestroy( &capabilityArray ); +* CleanupStack::PopAndDestroy( accMonitor ); +* @endcode +* +* Uninitialization example: +* @code +* accMonitor->StopObserving(); +* @endcode +* +* Connected method implementation example: +* @code +* void CMyAccMonitorTest::Connected( CAccMonitorInfo* aAccessoryInfo ) +* { +* // Notification about the connected accessory. aAccessoryInfo must +* // be copied because the pointer is deleted after connected method +* iAccessoryInfo->CopyL( aAccessoryInfo ); +* } +* @endcode +* +* @lib AccMonitor.lib +* @since S60 5.0 +*/ +NONSHARABLE_CLASS( CAccMonitor ) : public CBase + { +public: + + /** + * Symbian two phased constructor. + */ + IMPORT_C static CAccMonitor* NewL(); + + /** + * Symbian two phased constructor. Puts the instance to cleanup stack. + */ + IMPORT_C static CAccMonitor* NewLC(); + +public: + + /** + * Used to get the connected accessories which are returned in an + * RPointerArray that is typed to RConnectedAccessories. + * + * @param aAccessoriesArray is a reference to an array that is + * filled with CAccMonitorInfo instances which are accessories + * connected to the S60 device. + * @leave KErrNotFound if no accessories are connected. + * KErrNotReady if a device is not ready to start operation. + * @return The amount of connected accessories. + */ + virtual TInt GetConnectedAccessoriesL( + RConnectedAccessories& aAccessoriesArray ) const = 0; + + /** + * Sets observer to listen all connect/disconnect accessory notifications + * and starts the observer. + * + * @param aObserver is the pointer to the callback functions. + * @leave TInt KErrAlreadyExists if observer is active allready, + * otherwise KErrNone or standard Symbian error code. + */ + virtual void StartObservingL( + MAccMonitorObserver* aObserver ) = 0; + + /** + * Sets observer to listen connect/disconnect accessory notifications + * and starts the observer. Accessories that need to be listened can be + * defined with CAccMonitorInfo. This CAccMonitorInfo represents an + * instance of some connected or previously connected accessory. + * + * @param aObserver is the pointer to the callback functions. + * @param aInfo is the instance of the accessory that needs to be + * listened. Accessory that needs to be listened is copied + * from connected accessories array. If an empty instance is set + * as the parameter no notifications are sent. + * @leave TInt KErrAlreadyExists if observer is active allready, + * otherwise KErrNone or standard Symbian error code. + */ + virtual void StartObservingL( + MAccMonitorObserver* aObserver, + const CAccMonitorInfo* aInfo ) = 0; + + /** + * Sets observer to listen connect/disconnect accessory notifications + * and starts the observer. Accessories that need to be listened can be + * defined. + * + * @param aObserver is the pointer to the callback functions. + * @param aCapabilityArray is an array of capabilities. Accessory + * type that needs to be listened is constructed with this + * capability array. For exmple if KAccMonHeadset capability + * is inserted to the array the observer receives all + * notifications about connected/disconnected headsets. + * If an empty array is set as parameter no notifications are + * sent to the observer. + * @leave TInt KErrAlreadyExists if observer is active already, + * otherwise KErrNone or standard Symbian error code. + */ + virtual void StartObservingL( + MAccMonitorObserver* aObserver, + const RAccMonCapabilityArray& aCapabilityArray ) = 0; + + /** + * Stops observing accessory connection status changes. + * Listening will be automatically stopped when CAccMonintoringApi + * object is deleted. + */ + virtual void StopObserving() = 0; + + /** + * Checks whether observer is already observing. + * + * @return ETrue if observing + */ + virtual TBool IsObserving() const = 0; + + /** + * Gets the value for a capability that is defined in Accessory + * Monitoring API. + * + * @param aAccInfo is the accessory for which the value needs to be + * fetched. + * @param aCapability is capability which value needs to be + * fetched. + * @param aValue is the value for the capability. + * @leave KErrNotFound if no capability is not defined for this + * accessory, KErrArgument if this accessory is not + * connected, otherwise standard Symbian error code. + */ + virtual void GetCapabilityValueL( + const CAccMonitorInfo* aInfo, + const TUint32 aCapability, + TInt& aValue ) const = 0; + +protected: + + /** + * Default Constructor + */ + CAccMonitor(); + + /** + * Symbian OS 2nd phase constructor + */ + virtual void ConstructL() = 0; + + }; + + +/** +* The observer offers methods to observe connection/disconnection +* notifications from some defined accessory or all accessory +* connection/disconnection notifications. +*/ +class MAccMonitorObserver + { +public: + + /** + * A callback method for accessory connection notifications. + * + * @param aAccessoryInfo instance of the connected accessory. + * The content of the pointer must be copied to an instance + * CAccMonitorInfo because the original pointer is destroyed + * after the ConnectedL metdhod. + */ + virtual void ConnectedL( + CAccMonitorInfo* aAccessoryInfo ) = 0; + + /** + * A callback method for accessory disconnection notifications. + * + * @param aAccessoryInfo instance of the connected accessory. + * The content of the pointer must be copied to an instance + * CAccMonitorInfo because the original pointer is destroyed + * after the DisconnectedL metdhod. + */ + virtual void DisconnectedL( + CAccMonitorInfo* aAccessoryInfo ) = 0; + + /** + * A callback for error situations. + * + * @param Standard Symbian error code. + */ + virtual void AccMonitorObserverError( TInt aError ) = 0; + + }; + + + +#endif // ACCMONITOR_H + +// End of File