/*

 * 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 <e32base.h>

 #include <accmonitorinfo.h>

 // 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