/*

* 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 "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:

*

*/

#ifndef HWRMLIGHT_H

#define HWRMLIGHT_H

// INCLUDES

#include <e32base.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;

class MHWRMLightObserver;

class CHWRMEnhancedLight;

/**  

* 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 

* to control the various light targets of the device. The API provides also

* methods to retrieve the current light status and the supported light targets

* of the device. The API is meant for all applications which need to control 

* lights of the device.

*

* Type of the HW Resource Manager Light API is a synchronous method call meaning 

* the method call will block the client application. Every new call of the light

* API method stops all ongoing light control orders. Light state after duration

* based orders expire is the state specified by the last non-duration based order. 

*

* The API consist of the classes CHWRMLight and MHWRMLightObserver. If the client

* requires up-to-date status information, it should also provide callback pointer

* of the MHWRMLightObserver implementing class for the NewL-method.

*

* Usage:

*

* @code

* #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();

*

* // After this, lights can be directly controlled via the provided class methods. 

* light-> LightOnL (EPrimaryDisplay, 5000); // Turn display lights on for five seconds.

* light->LightOffL(EPrimaryDisplay); // Turn display lights off indefinitely.

*

* // To clean up, delete the created object:

* delete light;

* @endcode

*

* @publishedAll

* @released

*/

class CHWRMLight : public CBase

    {

    public:

		/**

		* Possible light states that can be get for the different light targets

		*/

		enum TLightStatus

			{

			/**

			For debugging/development and signaling an error conditions.

			*/

			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.

        * 

        * Note that all targets are not supported by all devices.

        * Attempting to use unsupported target will result in

        * KErrNotSupported.

        *

        * At least one target must be defined.

        */

        enum TLightTarget

            {

            /**

            No target. Not a valid target value, used only for error checking.

            */

            ENoTarget                    = 0x0,    

            /**

            Primary display of the device.

            */            

            EPrimaryDisplay              = 0x1,     

            /**

            Primary keyboard of the device. 

            */

            EPrimaryKeyboard             = 0x2,     

            /**

            Both primary display and the primary keyboard of the device.  

            */

            EPrimaryDisplayAndKeyboard   = 0x3,                

            /**

            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.

            *

            * A target mask including this target is 

            * always changed to a device state specific target mask. 

            * Note that the  system target with any other target is not supported. 

            *

            * This target is always supported but it is never

            * included in supported targets mask.

            *

            * @see CHWRMLight::SupportedTargets()

            */

            ESystemTarget                = 0x80000000  

            };

    public:  // Constructors

        /**

        * Two-phased constructor.

        *

        * @return A pointer to a new instance of the CHWRMLight class.

        *

        * @leave KErrNotSupported Device doesn't support Light feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMLight* NewL();

        /**

        * Two-phased constructor. 

        * Leaves instance to cleanup stack.

        *

        * @return A pointer to a new instance of the CHWRMLight class.

        *

        * @leave KErrNotSupported Device doesn't support Light feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMLight* NewLC();

        /**

        * Two-phased constructor.

        * Use this method for creating a Light client with callbacks.

        *

        * @param aCallback Pointer to the callback instance.

        * @return A pointer to a new instance of the CHWRMLight class.

        *

        * @leave KErrNotSupported Device doesn't support Light feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMLight* NewL(MHWRMLightObserver* aCallback);

        /**

        * Two-phased constructor. 

        * Use this method for creating a Light client with callbacks.

        * Leaves instance to cleanup stack.

        *

        * @param aCallback Pointer to the callback instance

        * @return A pointer to a new instance of the CHWRMLight class.

        *

        * @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.

    	* A higher priority client may cause lower priority client reservation

    	* to be temporarily suspended. Commands can still be issued in suspended 

    	* state, but they will not be acted upon unless suspension is lifted

    	* within specified duration.

    	* The suspended client will not get any notification about suspension.

    	* If light target is already reserved by a higher or equal priority application, 

    	* reserving will still succeeds, but reservation is immediately suspended.

    	*

    	* Calling this method is equal to calling ReserveLightL( aTarget, EFalse, EFalse),

    	* i.e. any previously frozen state will not be restored and CCoeEnv

    	* background/foreground status is always used to control further reservations.

    	*

		* @param aTarget Defines which light should be reserved. Multiple lights can

		*                be specified with using bitwise-or.

    	*

    	* @leave KErrNotSupported One or more of specified targets are not supported.

    	* @leave KErrAccessDenied No CCoeEnv present.

    	* @leave KErrNotReady Trying to reserve while on background.

        * @leave KErrNoMemory There is a memory allocation failure. 

		*

	 	* @see TLightTarget

    	*/

    	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 

    	* state, but they will not be acted upon unless suspension is lifted

    	* within specified duration.

    	* The suspended client will not get any notification about suspension.

    	* If light target is already reserved by a higher or equal priority application, 

    	* reserving will still succeeds, but reservation is immediately suspended.

    	*

    	*

		* @param aTarget Defines which light should be reserved. Multiple lights can

		*                be specified with using bitwise-or.

    	* @param aRestoreState If ETrue, the state frozen on last release will be

    	*                      restored upon successful reservation.

    	*                      I.e. if light was blinking when it was released by this

        *                      client the last time, it would start blinking again upon

        *                      successful reservation.

    	*                      For the first reservation of each session this parameter 

        *                      is always considered EFalse regardless of what is supplied,

        *                      as there is no previous frozen state to restore.

    	* @param aForceNoCCoeEnv If EFalse, then reservation requires that this client is

        *                        on the foreground at the time of reservation and light

        *                        target will be automatically released and re-reserved based

        *                        on background/foreground status of the this client. This 

        *                        also implies that CCoeEnv::Static() != NULL is required.

    	*                        If ETrue, the client will not require CCoeEnv to be present

        *                        nor does it automatically reserve/release light by depending

        *                        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 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);

    	/**

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

    	* Any reserved light targets that are released and have no other suspended

    	* clients will be reset to default state, which is either lights on or lights off, 

    	* depending on system inactivity time.

    	*

		* @param aTarget Defines which light should be released. Multiple lights can

		*                be specified with using bitwise-or.

		*

	 	* @see TLightTarget

    	*/

    	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.

        *

        * Calling this method is equal to calling 

        * LightOnL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultIntensity, ETrue).

	    *

		* @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. 

        * @leave KErrGeneral There is a hardware error.

		*

	 	* @see TLightTarget

		*/

		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.

        *

        * Calling this method is equal to call 

        * LightOnL(aTarget, aDuration, KHWRMDefaultIntensity, ETrue).

	    *

		* @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.

		*

        * @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

		*/

		virtual void LightOnL(TInt aTarget, 

		                      TInt aDuration);

	    /** 

	    * The LightOnL method switches the specified target light on

	    * for the specified duration using specified intensity. 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.

		*

        * @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

		*/

		virtual void LightOnL(TInt aTarget, 

		                      TInt aDuration, 

		                      TInt aIntensity,

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

		*/

		virtual void LightBlinkL(TInt aTarget);

	    /** 

	    * The LightBlinkL method blinks the target light(s) of the device for specified duration

	    * using default intensity.

        *

        * Calling this method is equal to calling

        * LightBlinkL(aTarget, aDuration, KHWRMDefaultCycleTime, 

        *             KHWRMDefaultCycleTime, KHWRMDefaultIntensity).

	   	*

		* @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.

	   	*

        * @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

		*/

		virtual void LightBlinkL(TInt aTarget, 

		                         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.

	   	*

		* @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.

	   	*

        * @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

		*/

		virtual void LightBlinkL(TInt aTarget, 

		                         TInt aDuration, 

		                         TInt aOnDuration, 

		                         TInt aOffDuration, 

		                         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. 

        *

        * Calling this method is equal to call 

        * LightOffL(aTarget, KHWRMInfiniteDuration, ETrue).

		*

		* @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. 

        * @leave KErrGeneral There is a hardware error.

		*

	 	* @see TLightTarget

		*/

		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.

        *

        * Calling this method is equal to call LightOffL(aTarget, aDuration, ETrue).

		*

		* @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 off 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.

		*

        * @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

		*/

		virtual void LightOffL(TInt aTarget, 

		                       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.

		*

		* @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 off 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 aFadeOut If ETrue, lights will not turn off instantly but instead smoothly fade-out

		*                 Note: All devices will not support fade-out, in which case device will

		*                 behave in its default fashion.

		*

        * @leave KErrArgument 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

		*/

		virtual void LightOffL(TInt aTarget, 

		                       TInt aDuration, 

		                       TBool aFadeOut);

        /**

        * This method retrieves the current light status. 

        *

		* @param aTarget Defines which light status is returned. 

		*                This method only supports single target, as different

		*                targets might have different statuses.

        * @return TLightStatus indicating the current light status. If there is a problem or

        *         multiple targets were specified, CHWRMLight::ELightStatusUnknown is returned.

        * 

        * @see MHWRMLightObserver

	 	* @see TLightTarget

        */

        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;

        /*

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

*

* If the client requires up-to-date status information, the client needs 

* to derive a class from the MHWRMlightObserver interface and implement 

* the LightStatusChanged() method. 

* 

* A callback object header example:

*

* @code 

* // INCLUDES

* #include <hwrmlight.h> // Link against HWRMLightClient.lib.

*

* class CTests : public CBase,

*                public MHWRMLightObserver

*     {

*     public:

*         CTests();

*         ~CTests();

*                           

*         void ConstructL();

*         static CTests* NewL();

*                

*         // from MHWRMLightObserver

*         virtual void LightStatusChanged(TInt aTarget, 

*                                         CHWRMLight::TLightStatus aStatus);

*

*    private:

*         CHWRMLight* iLight;

*    };

*

* @endcode

*

* A callback method implementation example:

*

* @code

* void CTests::LightStatusChanged(TInt aTarget, 

*                          CHWRMLight::TLightStatus aStatus)

*     {

*     RDebug::Print(_L("### Light state changed for target: 0x%x"), aTarget);

*     switch ( aStatus )

*         {

*         case CHWRMLight::ELightOn:

*             RDebug::Print(_L("### Light state changed: ELightOn"));

*             break;

*         case CHWRMLight::ELightOff:

*             RDebug::Print(_L("### Light state changed: ELightOff"));

*             break;

*         case CHWRMLight::ELightBlink:

*             RDebug::Print(_L("### Light state changed: ELightBlink"));

*             break;

*         case CHWRMLight::ELightStatusUnknown:

*             RDebug::Print(_L("### Light state changed: ELightStatusUnknown"));

*             break;

*         default:

*             RDebug::Print(_L("### Light state changed: UNDEFINED !"));

*             break;

*         }

*     }

*

* @endcode

*

* @publishedAll

* @released

*/

class MHWRMLightObserver

    {    

    public:

        /** 

        * Called when the device light status changes.

        * Note that if the light status for certain target changes

        * very rapidly, some state transitions might be missed.

        * It is however guaranteed that latest state is always obtained.

        *

        * @param aTarget Indicates target(s) the new status applies to.

        * @param aStatus Indicates light request status.

		*

	 	* @see CHWRMLight::TLightTarget

	 	* @see CHWRMLight::TLightStatus

		*/

        virtual void LightStatusChanged(TInt aTarget, 

                                        CHWRMLight::TLightStatus aStatus) = 0;

	};

#endif      // HWRMLIGHT_H   

// End of File