/*

* Copyright (c) 2002-2006 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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  This file contains the header of the 

*                CHWRMLight class.

*

*/

#ifndef HWRMLIGHT_H

#define HWRMLIGHT_H

// INCLUDES

#include <e32base.h>

// CONSTANTS

/**

* Minimum allowed intensity setting for Light.

*/

const TInt KHWRMLightMinIntensity = 1;

/**

* Maximum allowed intensity setting for Light.

*/

const TInt KHWRMLightMaxIntensity = 100;

/**

* Indicates default intensity in various methods.

*/

const TInt KHWRMDefaultIntensity = 0;

/**

* Maximum allowed duration value.

*/

const TInt KHWRMLightMaxDuration = (KMaxTInt / 1000) - 1;

/**

* Infinite duration value.

*/

const TInt KHWRMInfiniteDuration = 0;

/**

* Indicates device default Blink cycle time.

*/

const TInt KHWRMDefaultCycleTime = 0;

// FORWARD DECLARATIONS

class MHWRMLightObserver;

// CLASS DECLARATIONS

/**

* 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>  // link against HWRMLightClient.lib

*

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

*

* @lib HWRMLIGHTCLIENT.DLL

* @since S60 3.0

*/

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.

			ELightOff,               ///< Light state switch to light off.

			ELightBlink            ///< Light state switch to light blinking.

			};

        /**

        * 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

            {

            ENoTarget                    = 0x0,     ///< No target. Not a valid target value, used only

                                                    ///< for error checking.

            EPrimaryDisplay              = 0x1,     ///< Primary display of the device.

            EPrimaryKeyboard             = 0x2,     ///< Primary keyboard of the device. 

            EPrimaryDisplayAndKeyboard   = 0x3,     ///< Both primary display and the 

                                                    ///< primary keyboard of the device.  

            ESecondaryDisplay            = 0x4,     ///< Secondary display of the device.

            ESecondaryKeyboard           = 0x8,     ///< Secondary keyboard of the device. 

            ESecondaryDisplayAndKeyboard = 0xC,     ///< Both secondary display and the 

                                                    ///< secondary keyboard of the device.  

            ECustomTarget1               = 0x10,    ///< Device specific custom target 1.

            ECustomTarget2               = 0x20,    ///< Device specific custom target 2.

            ECustomTarget3               = 0x40,    ///< Device specific custom target 3.

            ECustomTarget4               = 0x80,    ///< Device specific custom target 4.

            /**

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

    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)=0;

    	/**

    	* 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 S60 or 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;

    	/**

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

	    /** 

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

	    /** 

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

	    /** 

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

	    /** 

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

	    * using default intensity.

        *

        * Calling this method is equal to call 

        * LightBlinkL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultCycleTime, 

        *             KHWRMDefaultCycleTime, KHWRMDefaultIntensity).

	   	*

		* @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) = 0;

	    /** 

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

	    /** 

	    * 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