Attempt to represent the S^2->S^3 header reorganisation as a series of "hg rename" operations
/*
* 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
* 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) = 0;
/**
* 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) = 0;
/**
* 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) = 0;
/**
* 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) = 0;
/**
* 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 = 0;
/**
* This method retrieves the supported light targets of the device.
* Any attempt to use or reserve unsupported targets will fail with
* KErrNotSupported.
*
* @return Bitmask containing supported light targets.
*
* @see TLightTarget
*/
virtual TInt SupportedTargets() const = 0;
};
/**
* 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
*
* @since S60 3.0
*/
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