1.1 --- a/epoc32/include/accmonitor.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/accmonitor.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,293 @@
1.4 -accmonitor.h
1.5 +/*
1.6 +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: This API is used for getting
1.19 +* information about connected accessories. The accessory
1.20 +* connections and disconnections can also be listened through
1.21 +* this API.
1.22 +*
1.23 +*/
1.24 +
1.25 +
1.26 +#ifndef ACCMONITOR_H
1.27 +#define ACCMONITOR_H
1.28 +
1.29 +// INCLUDES
1.30 +#include <e32base.h>
1.31 +#include <AccMonitorInfo.h>
1.32 +
1.33 +// FORWARD DECLARATIONS
1.34 +class MAccMonitorObserver;
1.35 +
1.36 +// CLASS DECLARATION
1.37 +/**
1.38 +* The Accessory Monitoring API interface offers accessory information about
1.39 +* connected accessories. It also offers an easy-to-use implementation of a
1.40 +* CActive-based wrapper for accessory connection status changed event
1.41 +* notifications. The clients can get information about the connected
1.42 +* accessories capabilities and, if the capabilities have values, get the
1.43 +* values from these capabilites. This API consist of classes CAccMonitor,
1.44 +* CAccMonitorInfo and MAccMonitorObserver. If the user wants to use the
1.45 +* observer this API offers, the user has to implement callback function
1.46 +* for receiving accessory connection and disconnection status notifications.
1.47 +* The connected accessories are offered to the client in an array. This array
1.48 +* presents the connected accessories as instances of CAccMonitorInfo class.
1.49 +* The CAccMonitorInfo offers accessory information encapsulated to a class. It
1.50 +* presents accessory device type, physical connection and device address
1.51 +* information with basic getter functions. The rest of the accessories
1.52 +* features are contained in an array. This array can be accessed with functions
1.53 +* that are in CAccMonitorInfo.
1.54 +* This class is not intended for user derivation.
1.55 +*
1.56 +* Usage:
1.57 +*
1.58 +* Example query for some accessory's information. All connected accessories are
1.59 +* fetched and the instance of CAccessoryInfo is getted:
1.60 +* @code
1.61 +* CAccMonitor* accMonitor = CAccMonitor::NewLC();
1.62 +* RConnectedAccessories connectedAccessories;
1.63 +* CleanupClosePushL( connectedAccessories );
1.64 +* accMonitor->GetConnectedAccessoriesL( connectedAccessories );
1.65 +* CAccMonitorInfo* accInfo = CAccMonitorInfo::NewLC();
1.66 +* TInt countOfArray = connectedAccessories.Count();
1.67 +* for( TInt i = 0; i != countOfArray; i++ )
1.68 +* {
1.69 +* TAccMonCapability deviceType = connectedAccessories[ i ]->AccDeviceType();
1.70 +* if( deviceType == KAccMonHeadset )
1.71 +* {
1.72 +* // Some Headset is connected, get the information to accInfo
1.73 +* accInfo->CopyL( connectedAccessories[ i ] );
1.74 +* }
1.75 +* }
1.76 +* // Destroy the pointers from the array, because those are owned by the client
1.77 +* CleanupStack::PopAndDestroy( accInfo );
1.78 +* CleanupStack::PopAndDestroy( &connectedAccessories );
1.79 +* CleanupStack::PopAndDestroy( accMonitor );
1.80 +* @endcode
1.81 +*
1.82 +* Example query for some accessorys capabilties. The user has fetched the
1.83 +* CAccMonitorInfo to accInfo instance from connected accessories:
1.84 +* @code
1.85 +* TInt arrayCount = accInfo->Count();
1.86 +* for( TInt i = 0; i != arrayCount; i++ )
1.87 +* {
1.88 +* TAccMonCapability accCapa = accInfo->AccCapabilityAtIndex( i );
1.89 +* if( accCapa == KAccMonStereoAudio )
1.90 +* {
1.91 +* // Accessory has stereo capability, handle this situation.
1.92 +* }
1.93 +* }
1.94 +* @endcode
1.95 +*
1.96 +* Initialization example for the observer(from a class that implements
1.97 +* MAccMonitorObserver interface).
1.98 +* Observer starts to listen for headset connects:
1.99 +* @code
1.100 +* CAccMonitor* accMonitor = CAccMonitor::NewLC();
1.101 +* RAccMonCapabilityArray capabilityArray;
1.102 +* CleanupClosePushL( capabilityArray );
1.103 +* capabilityArray.Append( KAccMonHeadset );
1.104 +* accMonitor->StartObservingL( this, capabilityArray );
1.105 +* CleanupStack::PopAndDestroy( &capabilityArray );
1.106 +* CleanupStack::PopAndDestroy( accMonitor );
1.107 +* @endcode
1.108 +*
1.109 +* Uninitialization example:
1.110 +* @code
1.111 +* accMonitor->StopObserving();
1.112 +* @endcode
1.113 +*
1.114 +* Connected method implementation example:
1.115 +* @code
1.116 +* void CMyAccMonitorTest::Connected( CAccMonitorInfo* aAccessoryInfo )
1.117 +* {
1.118 +* // Notification about the connected accessory. aAccessoryInfo must
1.119 +* // be copied because the pointer is deleted after connected method
1.120 +* iAccessoryInfo->CopyL( aAccessoryInfo );
1.121 +* }
1.122 +* @endcode
1.123 +*
1.124 +* @lib AccMonitor.lib
1.125 +* @since S60 5.0
1.126 +*/
1.127 +NONSHARABLE_CLASS( CAccMonitor ) : public CBase
1.128 + {
1.129 +public:
1.130 +
1.131 + /**
1.132 + * Symbian two phased constructor.
1.133 + */
1.134 + IMPORT_C static CAccMonitor* NewL();
1.135 +
1.136 + /**
1.137 + * Symbian two phased constructor. Puts the instance to cleanup stack.
1.138 + */
1.139 + IMPORT_C static CAccMonitor* NewLC();
1.140 +
1.141 +public:
1.142 +
1.143 + /**
1.144 + * Used to get the connected accessories which are returned in an
1.145 + * RPointerArray that is typed to RConnectedAccessories.
1.146 + *
1.147 + * @param aAccessoriesArray is a reference to an array that is
1.148 + * filled with CAccMonitorInfo instances which are accessories
1.149 + * connected to the S60 device.
1.150 + * @leave KErrNotFound if no accessories are connected.
1.151 + * KErrNotReady if a device is not ready to start operation.
1.152 + * @return The amount of connected accessories.
1.153 + */
1.154 + virtual TInt GetConnectedAccessoriesL(
1.155 + RConnectedAccessories& aAccessoriesArray ) const = 0;
1.156 +
1.157 + /**
1.158 + * Sets observer to listen all connect/disconnect accessory notifications
1.159 + * and starts the observer.
1.160 + *
1.161 + * @param aObserver is the pointer to the callback functions.
1.162 + * @leave TInt KErrAlreadyExists if observer is active allready,
1.163 + * otherwise KErrNone or standard Symbian error code.
1.164 + */
1.165 + virtual void StartObservingL(
1.166 + MAccMonitorObserver* aObserver ) = 0;
1.167 +
1.168 + /**
1.169 + * Sets observer to listen connect/disconnect accessory notifications
1.170 + * and starts the observer. Accessories that need to be listened can be
1.171 + * defined with CAccMonitorInfo. This CAccMonitorInfo represents an
1.172 + * instance of some connected or previously connected accessory.
1.173 + *
1.174 + * @param aObserver is the pointer to the callback functions.
1.175 + * @param aInfo is the instance of the accessory that needs to be
1.176 + * listened. Accessory that needs to be listened is copied
1.177 + * from connected accessories array. If an empty instance is set
1.178 + * as the parameter no notifications are sent.
1.179 + * @leave TInt KErrAlreadyExists if observer is active allready,
1.180 + * otherwise KErrNone or standard Symbian error code.
1.181 + */
1.182 + virtual void StartObservingL(
1.183 + MAccMonitorObserver* aObserver,
1.184 + const CAccMonitorInfo* aInfo ) = 0;
1.185 +
1.186 + /**
1.187 + * Sets observer to listen connect/disconnect accessory notifications
1.188 + * and starts the observer. Accessories that need to be listened can be
1.189 + * defined.
1.190 + *
1.191 + * @param aObserver is the pointer to the callback functions.
1.192 + * @param aCapabilityArray is an array of capabilities. Accessory
1.193 + * type that needs to be listened is constructed with this
1.194 + * capability array. For exmple if KAccMonHeadset capability
1.195 + * is inserted to the array the observer receives all
1.196 + * notifications about connected/disconnected headsets.
1.197 + * If an empty array is set as parameter no notifications are
1.198 + * sent to the observer.
1.199 + * @leave TInt KErrAlreadyExists if observer is active already,
1.200 + * otherwise KErrNone or standard Symbian error code.
1.201 + */
1.202 + virtual void StartObservingL(
1.203 + MAccMonitorObserver* aObserver,
1.204 + const RAccMonCapabilityArray& aCapabilityArray ) = 0;
1.205 +
1.206 + /**
1.207 + * Stops observing accessory connection status changes.
1.208 + * Listening will be automatically stopped when CAccMonintoringApi
1.209 + * object is deleted.
1.210 + */
1.211 + virtual void StopObserving() = 0;
1.212 +
1.213 + /**
1.214 + * Checks whether observer is already observing.
1.215 + *
1.216 + * @return ETrue if observing
1.217 + */
1.218 + virtual TBool IsObserving() const = 0;
1.219 +
1.220 + /**
1.221 + * Gets the value for a capability that is defined in Accessory
1.222 + * Monitoring API.
1.223 + *
1.224 + * @param aAccInfo is the accessory for which the value needs to be
1.225 + * fetched.
1.226 + * @param aCapability is capability which value needs to be
1.227 + * fetched.
1.228 + * @param aValue is the value for the capability.
1.229 + * @leave KErrNotFound if no capability is not defined for this
1.230 + * accessory, KErrArgument if this accessory is not
1.231 + * connected, otherwise standard Symbian error code.
1.232 + */
1.233 + virtual void GetCapabilityValueL(
1.234 + const CAccMonitorInfo* aInfo,
1.235 + const TUint32 aCapability,
1.236 + TInt& aValue ) const = 0;
1.237 +
1.238 +protected:
1.239 +
1.240 + /**
1.241 + * Default Constructor
1.242 + */
1.243 + CAccMonitor();
1.244 +
1.245 + /**
1.246 + * Symbian OS 2nd phase constructor
1.247 + */
1.248 + virtual void ConstructL() = 0;
1.249 +
1.250 + };
1.251 +
1.252 +
1.253 +/**
1.254 +* The observer offers methods to observe connection/disconnection
1.255 +* notifications from some defined accessory or all accessory
1.256 +* connection/disconnection notifications.
1.257 +*/
1.258 +class MAccMonitorObserver
1.259 + {
1.260 +public:
1.261 +
1.262 + /**
1.263 + * A callback method for accessory connection notifications.
1.264 + *
1.265 + * @param aAccessoryInfo instance of the connected accessory.
1.266 + * The content of the pointer must be copied to an instance
1.267 + * CAccMonitorInfo because the original pointer is destroyed
1.268 + * after the ConnectedL metdhod.
1.269 + */
1.270 + virtual void ConnectedL(
1.271 + CAccMonitorInfo* aAccessoryInfo ) = 0;
1.272 +
1.273 + /**
1.274 + * A callback method for accessory disconnection notifications.
1.275 + *
1.276 + * @param aAccessoryInfo instance of the connected accessory.
1.277 + * The content of the pointer must be copied to an instance
1.278 + * CAccMonitorInfo because the original pointer is destroyed
1.279 + * after the DisconnectedL metdhod.
1.280 + */
1.281 + virtual void DisconnectedL(
1.282 + CAccMonitorInfo* aAccessoryInfo ) = 0;
1.283 +
1.284 + /**
1.285 + * A callback for error situations.
1.286 + *
1.287 + * @param Standard Symbian error code.
1.288 + */
1.289 + virtual void AccMonitorObserverError( TInt aError ) = 0;
1.290 +
1.291 + };
1.292 +
1.293 +
1.294 +
1.295 +#endif // ACCMONITOR_H
1.296 +
1.297 +// End of File