1 accmonitor.h

     1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This API is used for getting 

    15 *                 information about connected accessories. The accessory 

    16 *                 connections and disconnections can also be listened through

    17 *                 this API.

    18 *

    19 */

    20 

    21 

    22 #ifndef ACCMONITOR_H

    23 #define ACCMONITOR_H

    24 

    25 // INCLUDES

    26 #include <e32base.h>

    27 #include <AccMonitorInfo.h>

    28 

    29 // FORWARD DECLARATIONS

    30 class MAccMonitorObserver;

    31 

    32 // CLASS DECLARATION

    33 /**

    34 * The Accessory Monitoring API interface offers accessory information about

    35 * connected accessories. It also offers an easy-to-use implementation of a 

    36 * CActive-based wrapper for accessory connection status changed event 

    37 * notifications. The clients can get information about the connected 

    38 * accessories capabilities and, if the capabilities have values, get the

    39 * values from these capabilites. This API consist of classes CAccMonitor,

    40 * CAccMonitorInfo and MAccMonitorObserver. If the user wants to use the

    41 * observer this API offers, the user has to  implement callback function

    42 * for receiving accessory connection and disconnection status notifications. 

    43 * The connected accessories are offered to the client in an array. This array

    44 * presents the connected accessories as instances of CAccMonitorInfo class.

    45 * The CAccMonitorInfo offers accessory information encapsulated to a class. It

    46 * presents accessory device type, physical connection and device address 

    47 * information with basic getter functions. The rest of the accessories

    48 * features are contained in an array. This array can be accessed with functions

    49 * that are in CAccMonitorInfo.

    50 * This class is not intended for user derivation.

    51 *

    52 * Usage:

    53 * 

    54 * Example query for some accessory's information. All connected accessories are

    55 * fetched and the instance of CAccessoryInfo is getted:

    56 * @code

    57 * CAccMonitor* accMonitor = CAccMonitor::NewLC();

    58 * RConnectedAccessories connectedAccessories;

    59 * CleanupClosePushL( connectedAccessories );

    60 * accMonitor->GetConnectedAccessoriesL( connectedAccessories );

    61 * CAccMonitorInfo* accInfo = CAccMonitorInfo::NewLC();

    62 * TInt countOfArray = connectedAccessories.Count();

    63 * for( TInt i = 0; i != countOfArray; i++ )

    64 *   {

    65 *   TAccMonCapability deviceType = connectedAccessories[ i ]->AccDeviceType();

    66 *   if( deviceType == KAccMonHeadset )

    67 *     {

    68 *     // Some Headset is connected, get the information to accInfo

    69 *     accInfo->CopyL( connectedAccessories[ i ] );

    70 *     }

    71 *   }

    72 * // Destroy the pointers from the array, because those are owned by the client

    73 * CleanupStack::PopAndDestroy( accInfo );

    74 * CleanupStack::PopAndDestroy( &connectedAccessories );

    75 * CleanupStack::PopAndDestroy( accMonitor );

    76 * @endcode

    77 * 

    78 * Example query for some accessorys capabilties. The user has fetched the

    79 * CAccMonitorInfo to accInfo instance from connected accessories:

    80 * @code

    81 * TInt arrayCount = accInfo->Count();

    82 * for( TInt i = 0; i != arrayCount; i++ )

    83 *   {

    84 *   TAccMonCapability accCapa = accInfo->AccCapabilityAtIndex( i );

    85 *   if( accCapa == KAccMonStereoAudio )

    86 *     {

    87 *     // Accessory has stereo capability, handle this situation.

    88 *     }

    89 *   }

    90 * @endcode

    91 *

    92 * Initialization example for the observer(from a class that implements

    93 * MAccMonitorObserver interface).

    94 * Observer starts to listen for headset connects:

    95 * @code

    96 * CAccMonitor* accMonitor = CAccMonitor::NewLC();

    97 * RAccMonCapabilityArray capabilityArray;

    98 * CleanupClosePushL( capabilityArray );

    99 * capabilityArray.Append( KAccMonHeadset );

   100 * accMonitor->StartObservingL( this, capabilityArray );

   101 * CleanupStack::PopAndDestroy( &capabilityArray );

   102 * CleanupStack::PopAndDestroy( accMonitor );

   103 * @endcode

   104 *

   105 * Uninitialization example:

   106 * @code

   107 * accMonitor->StopObserving(); 

   108 * @endcode

   109 *

   110 * Connected method implementation example:

   111 * @code

   112 * void CMyAccMonitorTest::Connected( CAccMonitorInfo* aAccessoryInfo )

   113 *    {

   114 *    // Notification about the connected accessory. aAccessoryInfo must

   115 *    // be copied because the pointer is deleted after connected method

   116 *    iAccessoryInfo->CopyL( aAccessoryInfo );

   117 *    }

   118 * @endcode

   119 *

   120 *  @lib AccMonitor.lib

   121 *  @since S60 5.0

   122 */

   123 NONSHARABLE_CLASS( CAccMonitor ) : public CBase 

   124   {

   125 public:

   126 

   127     /**

   128     * Symbian two phased constructor.

   129     */

   130     IMPORT_C static CAccMonitor* NewL();

   131     

   132     /**

   133     * Symbian two phased constructor. Puts the instance to cleanup stack.

   134     */

   135     IMPORT_C static CAccMonitor* NewLC();

   136 

   137 public: 

   138 

   139     /**

   140     * Used to get the connected accessories which are returned in an 

   141     * RPointerArray that is typed to RConnectedAccessories.

   142     *

   143     * @param    aAccessoriesArray is a reference to an array that is 

   144     *           filled with CAccMonitorInfo instances which are accessories

   145     *           connected to the S60 device.

   146     * @leave    KErrNotFound if no accessories are connected.

   147     *           KErrNotReady if a device is not ready to start operation.

   148     * @return   The amount of connected accessories.

   149     */

   150     virtual TInt GetConnectedAccessoriesL(

   151       RConnectedAccessories& aAccessoriesArray ) const = 0;

   152     

   153     /**      

   154     * Sets observer to listen all connect/disconnect accessory notifications

   155     * and starts the observer.

   156     *

   157     * @param    aObserver is the pointer to the callback functions.

   158     * @leave    TInt KErrAlreadyExists if observer is active allready,

   159     *           otherwise KErrNone or standard Symbian error code.

   160     */

   161     virtual void StartObservingL( 

   162       MAccMonitorObserver* aObserver ) = 0;

   163                    

   164     /**

   165     * Sets observer to listen connect/disconnect accessory notifications

   166     * and starts the observer. Accessories that need to be listened can be

   167     * defined with CAccMonitorInfo. This CAccMonitorInfo represents an

   168     * instance of some connected or previously connected accessory.

   169     *

   170     * @param    aObserver is the pointer to the callback functions.

   171     * @param    aInfo is the instance of the accessory that needs to be

   172     *           listened. Accessory that needs to be listened is copied

   173     *           from connected accessories array. If an empty instance is set

   174     *           as the parameter no notifications are sent.

   175     * @leave    TInt KErrAlreadyExists if observer is active allready,

   176     *           otherwise KErrNone or standard Symbian error code.

   177     */

   178     virtual void StartObservingL( 

   179       MAccMonitorObserver* aObserver,

   180       const CAccMonitorInfo* aInfo ) = 0;

   181     

   182     /**

   183     * Sets observer to listen connect/disconnect accessory notifications

   184     * and starts the observer. Accessories that need to be listened can be

   185     * defined.

   186     *

   187     * @param    aObserver is the pointer to the callback functions.

   188     * @param    aCapabilityArray is an array of capabilities. Accessory 

   189     *           type that needs to be listened is constructed with this

   190     *           capability array. For exmple if KAccMonHeadset capability

   191     *           is inserted to the array the observer receives all

   192     *           notifications about connected/disconnected headsets.

   193     *           If an empty array is set as parameter no notifications are

   194     *           sent to the observer.

   195     * @leave    TInt KErrAlreadyExists if observer is active already,

   196     *           otherwise KErrNone or standard Symbian error code.

   197     */

   198     virtual void StartObservingL( 

   199       MAccMonitorObserver* aObserver,

   200       const RAccMonCapabilityArray& aCapabilityArray ) = 0;

   201     

   202     /**

   203     * Stops observing accessory connection status changes.

   204     * Listening will be automatically stopped when CAccMonintoringApi

   205     * object is deleted.

   206     */

   207     virtual void StopObserving() = 0;

   208     

   209     /**

   210     * Checks whether observer is already observing.

   211     *

   212     * @return   ETrue if observing

   213     */

   214     virtual TBool IsObserving() const = 0;

   215     

   216     /**

   217     * Gets the value for a capability that is defined in Accessory

   218     * Monitoring API.

   219     *

   220     * @param    aAccInfo is the accessory for which the value needs to be

   221     *           fetched.

   222     * @param    aCapability is capability which value needs to be

   223     *           fetched.

   224     * @param    aValue is the value for the capability.

   225     * @leave    KErrNotFound if no capability is not defined for this

   226     *           accessory, KErrArgument if this accessory is not

   227     *           connected, otherwise standard Symbian error code.

   228     */

   229     virtual void GetCapabilityValueL( 

   230       const CAccMonitorInfo* aInfo,

   231       const TUint32 aCapability,

   232       TInt& aValue ) const = 0;

   233     

   234 protected:

   235 

   236     /**

   237     * Default Constructor 

   238     */

   239     CAccMonitor();

   240     

   241     /**

   242     * Symbian OS 2nd phase constructor 

   243     */

   244     virtual void ConstructL() = 0;

   245         

   246     };

   247 

   248 

   249 /**

   250 * The observer offers methods to observe connection/disconnection

   251 * notifications from some defined accessory or all accessory

   252 * connection/disconnection notifications.

   253 */

   254 class MAccMonitorObserver

   255     {

   256 public:

   257     

   258         /**

   259         * A callback method for accessory connection notifications.

   260         *

   261         * @param    aAccessoryInfo instance of the connected accessory.

   262         *           The content of the pointer must be copied to an instance

   263         *           CAccMonitorInfo because the original pointer is destroyed

   264         *           after the ConnectedL metdhod.

   265         */

   266         virtual void ConnectedL(

   267           CAccMonitorInfo* aAccessoryInfo ) = 0;

   268                 

   269         /**

   270         * A callback method for accessory disconnection notifications.

   271         *

   272         * @param    aAccessoryInfo instance of the connected accessory.

   273         *           The content of the pointer must be copied to an instance

   274         *           CAccMonitorInfo because the original pointer is destroyed

   275         *           after the DisconnectedL metdhod.

   276         */

   277         virtual void DisconnectedL(

   278           CAccMonitorInfo* aAccessoryInfo ) = 0;

   279      

   280         /**

   281         * A callback for error situations.

   282         *

   283         * @param    Standard Symbian error code.

   284         */

   285         virtual void AccMonitorObserverError( TInt aError ) = 0;

   286 

   287     };

   288         

   289     

   290 

   291 #endif // ACCMONITOR_H

   292 

   293 // End of File