API_REF/Public_API: comparison epoc32/include/hwrmlight.h

equal deleted inserted replaced

-:e1b950c65cb4
+:837f303aceeb
 /*
-* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
+* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
 * All rights reserved.
 * This component and the accompanying materials are made available
-* 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
+* under the terms of "Eclipse Public License v1.0"
 * which accompanies this distribution, and is available
-* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
 *
 * Initial Contributors:
 * Nokia Corporation - initial contribution.
 *
 * Contributors:
 *
-* Description:  This file contains the header of the
+* Description:
-*                CHWRMLight class.
 *
 */
 #ifndef HWRMLIGHT_H
 #define HWRMLIGHT_H
 // CONSTANTS
 /**
 * Minimum allowed intensity setting for Light.
+*
+* @publishedAll
+* @released
 */
 const TInt KHWRMLightMinIntensity = 1;
 /**
 * Maximum allowed intensity setting for Light.
+*
+* @publishedAll
+* @released
 */
 const TInt KHWRMLightMaxIntensity = 100;
 /**
 * Indicates default intensity in various methods.
+*
+* @publishedAll
+* @released
 */
 const TInt KHWRMDefaultIntensity = 0;
 /**
 * Maximum allowed duration value.
+*
+* @publishedAll
+* @released
 */
 const TInt KHWRMLightMaxDuration = (KMaxTInt / 1000) - 1;
 /**
 * Infinite duration value.
+*
+* @publishedAll
+* @released
 */
 const TInt KHWRMInfiniteDuration = 0;
 /**
 * Indicates device default Blink cycle time.
+*
+* @publishedAll
+* @released
 */
 const TInt KHWRMDefaultCycleTime = 0;
-// FORWARD DECLARATIONS
 class MHWRMLightObserver;
+class CHWRMEnhancedLight;
-// CLASS DECLARATIONS
+/**
+* RGB values.
+*
+* @publishedAll
+*/
+struct THWRMLightColor
+{
+TUint8 iRed;
+TUint8 iGreen;
+TUint8 iBlue;
+};
 /**
 * The class used to control the device lights.
 *
 * The HW Resource Manager Light API is a library API providing the ability
 * of the MHWRMLightObserver implementing class for the NewL-method.
 *
 * Usage:
 *
 * @code
-* #include <HWRMLight.h>  // link against HWRMLightClient.lib
+* #include <hwrmlight.h>
 *
 * // A CHWRMLight instance can be created by using NewL() or NewLC() methods.
 * // Up-to-date status information not required, no callbacks.
 * CHWRMLight* light = CHWRMLight::NewL();
 *
 *
 * // To clean up, delete the created object:
 * delete light;
 * @endcode
 *
-* @lib HWRMLIGHTCLIENT.DLL
+* @publishedAll
-* @since S60 3.0
+* @released
 */
 class CHWRMLight : public CBase
 {
 public:
 		/**
 		* Possible light states that can be get for the different light targets
 		*/
 		enum TLightStatus
 			{
-			ELightStatusUnknown = 0, ///< For debugging/development and signaling an error conditions.
+			/**
-			ELightOn,                ///< Light state switch to light on.
+			For debugging/development and signaling an error conditions.
-			ELightOff,               ///< Light state switch to light off.
+			*/
-			ELightBlink            ///< Light state switch to light blinking.
+			ELightStatusUnknown = 0,
+			/**
+			Light state switch to light on.
+			*/
+			ELightOn,
+			/**
+			Light state switch to light off.
+			*/
+			ELightOff,
+			/**
+			Light state switch to light blinking.
+			*/
+			ELightBlink
 			};
 /**
 * Possible light targets.
 * Targets can be used as bitmask. Some common masks are provided as enum.
 *
 * At least one target must be defined.
 */
 enum TLightTarget
 {
-ENoTarget                    = 0x0,     ///< No target. Not a valid target value, used only
+/**
-///< for error checking.
+No target. Not a valid target value, used only for error checking.
+*/
-EPrimaryDisplay              = 0x1,     ///< Primary display of the device.
+ENoTarget                    = 0x0,
-EPrimaryKeyboard             = 0x2,     ///< Primary keyboard of the device.
+/**
-EPrimaryDisplayAndKeyboard   = 0x3,     ///< Both primary display and the
+Primary display of the device.
-///< primary keyboard of the device.
+*/
+EPrimaryDisplay              = 0x1,
-ESecondaryDisplay            = 0x4,     ///< Secondary display of the device.
+/**
-ESecondaryKeyboard           = 0x8,     ///< Secondary keyboard of the device.
+Primary keyboard of the device.
-ESecondaryDisplayAndKeyboard = 0xC,     ///< Both secondary display and the
+*/
-///< secondary keyboard of the device.
+EPrimaryKeyboard             = 0x2,
+/**
-ECustomTarget1               = 0x10,    ///< Device specific custom target 1.
+Both primary display and the primary keyboard of the device.
-ECustomTarget2               = 0x20,    ///< Device specific custom target 2.
+*/
-ECustomTarget3               = 0x40,    ///< Device specific custom target 3.
+EPrimaryDisplayAndKeyboard   = 0x3,
-ECustomTarget4               = 0x80,    ///< Device specific custom target 4.
+/**
+Secondary display of the device.
+*/
+ESecondaryDisplay            = 0x4,
+/**
+Secondary keyboard of the device.
+*/
+ESecondaryKeyboard           = 0x8,
+/**
+Both secondary display and the secondary keyboard of the device.
+*/
+ESecondaryDisplayAndKeyboard = 0xC,
+/**
+Device specific custom target 1.
+*/
+ECustomTarget1               = 0x10,
+/**
+Device specific custom target 2.
+*/
+ECustomTarget2               = 0x20,
+/**
+Device specific custom target 3.
+*/
+ECustomTarget3               = 0x40,
+/**
+Device specific custom target 4.
+*/
+ECustomTarget4               = 0x80,
 /**
 * Special target used to control all currently available system lights.
 *
 * System lights normally include all displays and keyboards,
 * but not custom lights. This is however device dependent.
 * @leave KErrNotSupported Device doesn't support Light feature.
 * @leave KErrNoMemory There is a memory allocation failure.
 */
 IMPORT_C static CHWRMLight* NewLC(MHWRMLightObserver* aCallback);
+		/**
+		* Destructor
+		*/
+		IMPORT_C ~CHWRMLight();
 public: // New functions
 	/**
 	* Reserves light target exclusively for this client.
 	* @leave KErrNotReady Trying to reserve while on background.
 * @leave KErrNoMemory There is a memory allocation failure.
 		*
 	 	* @see TLightTarget
 	*/
-	virtual void ReserveLightL(TInt aTarget)=0;
+	virtual void ReserveLightL(TInt aTarget);
 	/**
 	* Reserves light target exclusively for this client.
 	* A higher priority client may cause lower priority client reservation
 	* to be temporarily suspended. Commands can still be issued in suspended
 *                        on foreground/background status of the client.
 *                        Only trusted clients are allowed to set this flag to ETrue.
 	*                        A client is considered trusted if it has nonstandard
 *                        priority defined in the internal lights policy of the
 *                        HW Resource Manager. A client can be defined trusted
-*                        only by S60 or a product.
+*                        only by a product.
 	*
 	* @leave KErrNotSupported One or more of specified targets are not supported.
 	* @leave KErrAccessDenied Paramenter aForceNoCCoeEnv is ETrue and client is not trusted.
 	* @leave KErrBadHandle Parameter ForceNoCCoeEnv is EFalse and no CCoeEnv present.
 	* @leave KErrNotReady Trying to reserve while on background and parameter
 *                     aForceNoCCoeEnv is EFalse.
 * @leave KErrNoMemory There is a memory allocation failure.
 		*
 	 	* @see TLightTarget
 	*/
-	virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv)=0;
+	virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv);
 	/**
 	* Releases light target if it was previously reserved for this client.
 	* If this client has not reserved any of the specified lights,
 	* this method does nothing.
 		* @param aTarget Defines which light should be released. Multiple lights can
 		*                be specified with using bitwise-or.
 		*
 	 	* @see TLightTarget
 	*/
-	virtual void ReleaseLight(TInt aTarget)=0;
+	virtual void ReleaseLight(TInt aTarget);
 	    /**
 	    * The LightOnL method switches the specified target light on
 	    * for infinite duration using default intensity. Lights will use fade-in.
 * @leave KErrNoMemory There is a memory allocation failure.
 * @leave KErrGeneral There is a hardware error.
 		*
 	 	* @see TLightTarget
 		*/
-		virtual void LightOnL(TInt aTarget) = 0;
+		virtual void LightOnL(TInt aTarget);
 	    /**
 	    * The LightOnL method switches the specified target light on
 	    * for the specified duration using default intensity. Lights will use fade-in.
 *
 * @leave KErrGeneral There is a hardware error.
 		*
 	 	* @see TLightTarget
 		*/
 		virtual void LightOnL(TInt aTarget,
-		                      TInt aDuration) = 0;
+		                      TInt aDuration);
 	    /**
 	    * The LightOnL method switches the specified target light on
 	    * for the specified duration using specified intensity. Fade-in can also be controlled.
 	    *
 	 	* @see TLightTarget
 		*/
 		virtual void LightOnL(TInt aTarget,
 		                      TInt aDuration,
 		                      TInt aIntensity,
-		                      TBool aFadeIn) = 0;
+		                      TBool aFadeIn);
 	    /**
 	    * The LightBlinkL method blinks the target light(s) of the device for infinite duration
 	    * using default intensity.
 *
 * Calling this method is equal to call
+* @code
 * LightBlinkL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultCycleTime,
 *             KHWRMDefaultCycleTime, KHWRMDefaultIntensity).
+	   	* @endcode
 	   	*
 		* @param aTarget Defines which light should be controlled. Multiple lights can
 		*                be specified with using bitwise-or.
 	   	*
 * @leave KErrNotSupported One or more of specified targets are not supported.
 * @leave KErrNoMemory There is a memory allocation failure.
 * @leave KErrGeneral There is a hardware error.
 		*
 	 	* @see TLightTarget
 		*/
-		virtual void LightBlinkL(TInt aTarget) = 0;
+		virtual void LightBlinkL(TInt aTarget);
 	    /**
 	    * The LightBlinkL method blinks the target light(s) of the device for specified duration
 	    * using default intensity.
 *
 * @leave KErrGeneral There is a hardware error.
 		*
 	 	* @see TLightTarget
 		*/
 		virtual void LightBlinkL(TInt aTarget,
-		                         TInt aDuration) = 0;
+		                         TInt aDuration);
 	    /**
 	    * The LightBlinkL method blinks the target light(s) of the device for specified duration
 	    * using specified intensity. On- and Off-cycle times of the blinking can also be controlled.
 	   	*
 		*/
 		virtual void LightBlinkL(TInt aTarget,
 		                         TInt aDuration,
 		                         TInt aOnDuration,
 		                         TInt aOffDuration,
-		                         TInt aIntensity) = 0;
+		                         TInt aIntensity);
 	    /**
 	    * The LightOffL method switches the device light off for the specified target for
 	    * infinite duration. Lights will be switched off with fade-out.
 *
 * @leave KErrNoMemory There is a memory allocation failure.
 * @leave KErrGeneral There is a hardware error.
 		*
 	 	* @see TLightTarget
 		*/
-		virtual void LightOffL(TInt aTarget) = 0;
+		virtual void LightOffL(TInt aTarget);
 	    /**
 	    * The LightOffL method switches the device light off for the specified target for
 	    * the specified duration time. Lights will be switched off with fade-out.
 *
 * @leave KErrGeneral There is a hardware error.
 		*
 	 	* @see TLightTarget
 		*/
 		virtual void LightOffL(TInt aTarget,
-		                       TInt aDuration) = 0;
+		                       TInt aDuration);
 	    /**
 	    * The LightOffL method switches the device light off for the specified target for
 	    * the specified duration time. Lights fade-out can also be controlled.
 		*
 		*
 	 	* @see TLightTarget
 		*/
 		virtual void LightOffL(TInt aTarget,
 		                       TInt aDuration,
-		                       TBool aFadeOut) = 0;
+		                       TBool aFadeOut);
 /**
 * This method retrieves the current light status.
 *
 		* @param aTarget Defines which light status is returned.
 *         multiple targets were specified, CHWRMLight::ELightStatusUnknown is returned.
 *
 * @see MHWRMLightObserver
 	 	* @see TLightTarget
 */
-virtual TLightStatus LightStatus(TInt aTarget) const = 0;
+virtual TLightStatus LightStatus(TInt aTarget) const;
 /**
 * This method retrieves the supported light targets of the device.
 * Any attempt to use or reserve unsupported targets will fail with
 * KErrNotSupported.
 *
 * @return Bitmask containing supported light targets.
 *
 * @see TLightTarget
 */
-virtual TInt SupportedTargets() const = 0;
+virtual TInt SupportedTargets() const;
+/*
+*   Used for setting color of Light Target(s).
+*
+* @param aTarget Defines which light should be controlled. Multiple lights can
+*                be specified with using bitwise-or.
+*
+* @param aRGB RGB Values to be set for the target(s).
+*
+* @leave KErrNotSupported One or more of specified targets are not supported.
+* @leave KErrBadHandle Light session has been invalidated.
+* @leave KErrTimedOut Timeout occurred in controlling light.
+* @leave KErrInUse One or more of specified targets are not reserved for
+*                  this client but are reserved for others.
+* @leave KErrNoMemory There is a memory allocation failure.
+* @see THWRMLightColor
+*/
+IMPORT_C void SetLightColorL(TInt aTarget, THWRMLightColor& aRGB);
+/*
+*   Used for setting default color of Light Target(s).
+*
+* @param aTarget Defines which light should be controlled. Multiple lights can
+*                be specified with using bitwise-or.
+* @leave KErrNotSupported One or more of specified targets are not supported.
+* @leave KErrBadHandle Light session has been invalidated.
+* @leave KErrTimedOut Timeout occurred in controlling light.
+* @leave KErrInUse One or more of specified targets are not reserved for
+*                  this client but are reserved for others.
+* @leave KErrNoMemory There is a memory allocation failure.
+*/
+IMPORT_C void SetLightDefaultColorL(TInt aTarget);
+/**
+* The LightOnL method switches the specified target light on
+* for the specified duration and specified color.
+*
+* @param aTarget Defines which light should be controlled. Multiple lights can
+*                be specified with using bitwise-or.
+* @param aDuration Duration of the time the light is switched on measured in milliseconds.
+*                  After the duration expires, the light state for target will be changed
+*                  to whatever state was caused by the last infinite time duration call, or
+*                  default state determined by inactivity timer, in case there has not
+*                  been a previous infinite time duration call in this session.
+*                  If the aDuration time is KHWRMInfiniteDuration then it means
+*                  an infinite value that has to be stopped by calling of any of
+*                  the other light control methods.
+*                  Duration can have maximum value of KHWRMLightMaxDuration.
+* @param aRGBParam RGB Values to be set for the target(s).
+*
+* @leave KErrArgument One of the parameters is out of range.
+* @leave KErrNotSupported One or more of specified targets are not supported.
+* @leave KErrBadHandle Light session has been invalidated.
+* @leave KErrTimedOut Timeout occurred in controlling light.
+* @leave KErrInUse One or more of specified targets are not reserved for
+*                  this client but are reserved for others.
+* @leave KErrNoMemory There is a memory allocation failure.
+* @leave KErrGeneral There is a hardware error.
+*
+* @see TLightTarget
+* @see THWRMLightColor
+*/
+IMPORT_C void LightOnL(TInt aTarget, TInt aDuration, const THWRMLightColor& aRGBParam);
+/**
+* The LightOnL method switches the specified target light on
+* for the specified duration using specified intensity and color. Fade-in can also be controlled.
+*
+* @param aTarget Defines which light should be controlled. Multiple lights can
+*                be specified with using bitwise-or.
+* @param aDuration Duration of the time the light is switched on measured in milliseconds.
+*                  After the duration expires, the light state for target will be changed
+*                  to whatever state was caused by the last infinite time duration call, or
+*                  default state determined by inactivity timer, in case there has not
+*                  been a previous infinite time duration call in this session.
+*                  If the aDuration time is KHWRMInfiniteDuration then it means
+*                  an infinite value that has to be stopped by calling of any of
+*                  the other light control methods.
+*                  Duration can have maximum value of KHWRMLightMaxDuration.
+* @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default
+*                   intensity will be used.
+*                   Note: All devices might not support user defined intensity, in which case
+*                   device will behave in its default fashion.
+* @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in.
+*                Note: All devices will not support fade-in, in which case device will
+*                behave in its default fashion.
+* @param aRGBParam RGB Values to be set for the target(s).
+*
+* @leave KErrArgument One of the parameters is out of range.
+* @leave KErrNotSupported One or more of specified targets are not supported.
+* @leave KErrBadHandle Light session has been invalidated.
+* @leave KErrTimedOut Timeout occurred in controlling light.
+* @leave KErrInUse One or more of specified targets are not reserved for
+*                  this client but are reserved for others.
+* @leave KErrNoMemory There is a memory allocation failure.
+* @leave KErrGeneral There is a hardware error.
+*
+* @see TLightTarget
+* @see THWRMLightColor
+*/
+IMPORT_C void LightOnL(TInt aTarget, TInt aDuration, TInt aIntensity, TBool aFadeIn,
+const  THWRMLightColor& aRGBParam);
+/**
+* The LightBlinkL method blinks the target light(s) of the device for specified duration and color
+* using default intensity.
+*
+*
+* @param aTarget Defines which light should be controlled. Multiple lights can
+*                be specified with using bitwise-or.
+* @param aDuration Duration of the time the light is set to blink measured in milliseconds.
+*                  After the duration expires, the light state for target will be changed
+*                  to whatever state was caused by the last infinite time duration call, or
+*                  default state determined by inactivity timer, in case there has not
+*                  been a previous infinite time duration call in this session.
+*                  If the aTotalDuration time is KHWRMInfiniteDuration then it
+*                  means an infinite value that has to be
+*                  stopped by calling of any of the other light control methods.
+*                  Duration can have maximum value of KHWRMLightMaxDuration.
+*
+* @param aRGBParam RGB Values to be set for the target(s).
+*
+* @leave KErrArgument Parameter aDuration is out of range.
+* @leave KErrNotSupported One or more of specified targets are not supported.
+* @leave KErrBadHandle Light session has been invalidated.
+* @leave KErrTimedOut Timeout occurred in controlling light.
+* @leave KErrInUse One or more of specified targets are not reserved for
+*                  this client but are reserved for others.
+* @leave KErrNoMemory There is a memory allocation failure.
+* @leave KErrGeneral There is a hardware error.
+*
+* @see TLightTarget
+* @see THWRMLightColor
+*/
+IMPORT_C void LightBlinkL(TInt aTarget, TInt aDuration, const THWRMLightColor& aRGBParam);
+/**
+* The LightBlinkL method blinks the target light(s) of the device for specified duration
+* using specified intensity and color. On- and Off-cycle times of the blinking can also be controlled.
+*
+* @param aTarget Defines which light should be controlled. Multiple lights can
+*                be specified with using bitwise-or.
+* @param aDuration Duration of the time the light is set to blink measured in milliseconds.
+*                  After the duration expires, the light state for target will be changed
+*                  to whatever state was caused by the last infinite time duration call, or
+*                  default state determined by inactivity timer, in case there has not
+*                  been a previous infinite time duration call in this session.
+*                  If the aTotalDuration time is KHWRMInfiniteDuration then it
+*                  means an infinite value that has to be
+*                  stopped by calling of any of the other light control methods.
+*                  Duration can have maximum value of KHWRMLightMaxDuration.
+* @param aOnDuration Duration time, measured in milliseconds, of how long the Light is
+*                    switched on in every Blink cycle.
+*                    Duration can have maximum value of KHWRMLightMaxDuration.
+*                    For device default cycle duration, use value KHWRMDefaultCycleTime.
+*                    If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime,
+*                    both must be KHWRMDefaultCycleTime.
+*                    Some devices might not support variable blink cycle times, in which
+*                    case default value will be substituted.
+* @param aOffDuration Duration time, measured in milliseconds, of how long the Light
+*                     is switched off in every Blink cycle.
+*                     Duration can have maximum value of KHWRMLightMaxDuration.
+*                     For device default cycle duration, use value KHWRMDefaultCycleTime.
+*                     If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime,
+*                     both must be KHWRMDefaultCycleTime.
+*                     Some devices might not support variable blink cycle times, in which
+*                     case default value will be substituted.
+* @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default
+*                   intensity will be used.
+*                   Note: All devices might not support user defined intensity, in which case
+*                   device will behave in its default fashion.
+*
+* @param aRGBParam RGB Values to be set for the target(s).
+*
+* @leave KErrArgument One of the parameters is out of range or otherwise invalid.
+* @leave KErrNotSupported One or more of specified targets are not supported.
+* @leave KErrBadHandle Light session has been invalidated.
+* @leave KErrTimedOut Timeout occurred in controlling light.
+* @leave KErrInUse One or more of specified targets are not reserved for
+*                  this client but are reserved for others.
+* @leave KErrNoMemory There is a memory allocation failure.
+* @leave KErrGeneral There is a hardware error.
+*
+* @see TLightTarget
+* @see THWRMLightColor
+*/
+IMPORT_C void LightBlinkL(TInt aTarget, TInt aDuration, TInt aOnDuration, TInt aOffDuration,
+TInt aIntensity, const THWRMLightColor& aRGBParam);
+private:
+		CHWRMLight();
+		void ConstructL(MHWRMLightObserver* aCallback);
+private:
+CHWRMEnhancedLight* iEnhanced;
 };
 /**
 * A callback interface for light status reporting.
 *
 *
 * A callback object header example:
 *
 * @code
 * // INCLUDES
-* #include <HWRMLight.h> // Link against HWRMLightClient.lib.
+* #include <hwrmlight.h> // Link against HWRMLightClient.lib.
 *
 * class CTests : public CBase,
 *                public MHWRMLightObserver
 *     {
 *     public:
 *         }
 *     }
 *
 * @endcode
 *
-* @since S60 3.0
+* @publishedAll
+* @released
 */
 class MHWRMLightObserver
 {
 public:

branch	Symbian3
changeset 4	837f303aceeb
parent 2	2fe1408b6811