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