--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/resourcemgmt/hwresourcesmgr/light/inc/HWRMLight.h Tue Feb 02 00:53:00 2010 +0200
@@ -0,0 +1,993 @@
+/*
+* 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