williamr@2: /* williamr@4: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@4: * Description: williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@4: williamr@4: williamr@2: #ifndef HWRMLIGHT_H williamr@2: #define HWRMLIGHT_H williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: williamr@2: // CONSTANTS williamr@2: williamr@2: /** williamr@2: * Minimum allowed intensity setting for Light. williamr@4: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: const TInt KHWRMLightMinIntensity = 1; williamr@2: williamr@2: /** williamr@2: * Maximum allowed intensity setting for Light. williamr@4: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: const TInt KHWRMLightMaxIntensity = 100; williamr@2: williamr@2: /** williamr@2: * Indicates default intensity in various methods. williamr@4: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: const TInt KHWRMDefaultIntensity = 0; williamr@2: williamr@2: /** williamr@2: * Maximum allowed duration value. williamr@4: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: const TInt KHWRMLightMaxDuration = (KMaxTInt / 1000) - 1; williamr@2: williamr@2: /** williamr@2: * Infinite duration value. williamr@4: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: const TInt KHWRMInfiniteDuration = 0; williamr@2: williamr@2: /** williamr@2: * Indicates device default Blink cycle time. williamr@4: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: const TInt KHWRMDefaultCycleTime = 0; williamr@2: williamr@2: williamr@2: class MHWRMLightObserver; williamr@4: class CHWRMEnhancedLight; williamr@2: williamr@4: /** williamr@4: * RGB values. williamr@4: * williamr@4: * @publishedAll williamr@4: */ williamr@4: williamr@4: struct THWRMLightColor williamr@4: { williamr@4: TUint8 iRed; williamr@4: TUint8 iGreen; williamr@4: TUint8 iBlue; williamr@4: }; williamr@4: williamr@2: williamr@2: /** williamr@2: * The class used to control the device lights. williamr@2: * williamr@2: * The HW Resource Manager Light API is a library API providing the ability williamr@2: * to control the various light targets of the device. The API provides also williamr@2: * methods to retrieve the current light status and the supported light targets williamr@2: * of the device. The API is meant for all applications which need to control williamr@2: * lights of the device. williamr@2: * williamr@2: * Type of the HW Resource Manager Light API is a synchronous method call meaning williamr@2: * the method call will block the client application. Every new call of the light williamr@2: * API method stops all ongoing light control orders. Light state after duration williamr@2: * based orders expire is the state specified by the last non-duration based order. williamr@2: * williamr@2: * The API consist of the classes CHWRMLight and MHWRMLightObserver. If the client williamr@2: * requires up-to-date status information, it should also provide callback pointer williamr@2: * of the MHWRMLightObserver implementing class for the NewL-method. williamr@2: * williamr@2: * Usage: williamr@2: * williamr@2: * @code williamr@4: * #include williamr@2: * williamr@2: * // A CHWRMLight instance can be created by using NewL() or NewLC() methods. williamr@2: * // Up-to-date status information not required, no callbacks. williamr@2: * CHWRMLight* light = CHWRMLight::NewL(); williamr@2: * williamr@2: * // After this, lights can be directly controlled via the provided class methods. williamr@2: * light-> LightOnL (EPrimaryDisplay, 5000); // Turn display lights on for five seconds. williamr@2: * light->LightOffL(EPrimaryDisplay); // Turn display lights off indefinitely. williamr@2: * williamr@2: * // To clean up, delete the created object: williamr@2: * delete light; williamr@2: * @endcode williamr@2: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: class CHWRMLight : public CBase williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Possible light states that can be get for the different light targets williamr@2: */ williamr@2: enum TLightStatus williamr@2: { williamr@4: /** williamr@4: For debugging/development and signaling an error conditions. williamr@4: */ williamr@4: ELightStatusUnknown = 0, williamr@4: /** williamr@4: Light state switch to light on. williamr@4: */ williamr@4: ELightOn, williamr@4: /** williamr@4: Light state switch to light off. williamr@4: */ williamr@4: ELightOff, williamr@4: /** williamr@4: Light state switch to light blinking. williamr@4: */ williamr@4: ELightBlink williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Possible light targets. williamr@2: * Targets can be used as bitmask. Some common masks are provided as enum. williamr@2: * williamr@2: * Note that all targets are not supported by all devices. williamr@2: * Attempting to use unsupported target will result in williamr@2: * KErrNotSupported. williamr@2: * williamr@2: * At least one target must be defined. williamr@2: */ williamr@2: enum TLightTarget williamr@2: { williamr@4: /** williamr@4: No target. Not a valid target value, used only for error checking. williamr@4: */ williamr@4: ENoTarget = 0x0, williamr@4: /** williamr@4: Primary display of the device. williamr@4: */ williamr@4: EPrimaryDisplay = 0x1, williamr@4: /** williamr@4: Primary keyboard of the device. williamr@4: */ williamr@4: EPrimaryKeyboard = 0x2, williamr@4: /** williamr@4: Both primary display and the primary keyboard of the device. williamr@4: */ williamr@4: EPrimaryDisplayAndKeyboard = 0x3, williamr@4: /** williamr@4: Secondary display of the device. williamr@4: */ williamr@4: ESecondaryDisplay = 0x4, williamr@4: /** williamr@4: Secondary keyboard of the device. williamr@4: */ williamr@4: ESecondaryKeyboard = 0x8, williamr@4: /** williamr@4: Both secondary display and the secondary keyboard of the device. williamr@4: */ williamr@4: ESecondaryDisplayAndKeyboard = 0xC, williamr@4: /** williamr@4: Device specific custom target 1. williamr@4: */ williamr@4: ECustomTarget1 = 0x10, williamr@4: /** williamr@4: Device specific custom target 2. williamr@4: */ williamr@4: ECustomTarget2 = 0x20, williamr@4: /** williamr@4: Device specific custom target 3. williamr@4: */ williamr@4: ECustomTarget3 = 0x40, williamr@4: /** williamr@4: Device specific custom target 4. williamr@4: */ williamr@4: ECustomTarget4 = 0x80, williamr@2: /** williamr@2: * Special target used to control all currently available system lights. williamr@2: * williamr@2: * System lights normally include all displays and keyboards, williamr@2: * but not custom lights. This is however device dependent. williamr@2: * williamr@2: * A target mask including this target is williamr@2: * always changed to a device state specific target mask. williamr@2: * Note that the system target with any other target is not supported. williamr@2: * williamr@2: * This target is always supported but it is never williamr@2: * included in supported targets mask. williamr@2: * williamr@2: * @see CHWRMLight::SupportedTargets() williamr@2: */ williamr@2: ESystemTarget = 0x80000000 williamr@2: }; williamr@2: williamr@2: public: // Constructors williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * williamr@2: * @return A pointer to a new instance of the CHWRMLight class. williamr@2: * williamr@2: * @leave KErrNotSupported Device doesn't support Light feature. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: */ williamr@2: IMPORT_C static CHWRMLight* NewL(); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * Leaves instance to cleanup stack. williamr@2: * williamr@2: * @return A pointer to a new instance of the CHWRMLight class. williamr@2: * williamr@2: * @leave KErrNotSupported Device doesn't support Light feature. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: */ williamr@2: IMPORT_C static CHWRMLight* NewLC(); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * Use this method for creating a Light client with callbacks. williamr@2: * williamr@2: * @param aCallback Pointer to the callback instance. williamr@2: * @return A pointer to a new instance of the CHWRMLight class. williamr@2: * williamr@2: * @leave KErrNotSupported Device doesn't support Light feature. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: */ williamr@2: IMPORT_C static CHWRMLight* NewL(MHWRMLightObserver* aCallback); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * Use this method for creating a Light client with callbacks. williamr@2: * Leaves instance to cleanup stack. williamr@2: * williamr@2: * @param aCallback Pointer to the callback instance williamr@2: * @return A pointer to a new instance of the CHWRMLight class. williamr@2: * williamr@2: * @leave KErrNotSupported Device doesn't support Light feature. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: */ williamr@2: IMPORT_C static CHWRMLight* NewLC(MHWRMLightObserver* aCallback); williamr@2: williamr@4: williamr@4: /** williamr@4: * Destructor williamr@4: */ williamr@4: IMPORT_C ~CHWRMLight(); williamr@4: williamr@2: public: // New functions williamr@2: williamr@2: williamr@2: /** williamr@2: * Reserves light target exclusively for this client. williamr@2: * A higher priority client may cause lower priority client reservation williamr@2: * to be temporarily suspended. Commands can still be issued in suspended williamr@2: * state, but they will not be acted upon unless suspension is lifted williamr@2: * within specified duration. williamr@2: * The suspended client will not get any notification about suspension. williamr@2: * If light target is already reserved by a higher or equal priority application, williamr@2: * reserving will still succeeds, but reservation is immediately suspended. williamr@2: * williamr@2: * Calling this method is equal to calling ReserveLightL( aTarget, EFalse, EFalse), williamr@2: * i.e. any previously frozen state will not be restored and CCoeEnv williamr@2: * background/foreground status is always used to control further reservations. williamr@2: * williamr@2: * @param aTarget Defines which light should be reserved. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrAccessDenied No CCoeEnv present. williamr@2: * @leave KErrNotReady Trying to reserve while on background. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual void ReserveLightL(TInt aTarget); williamr@2: williamr@2: /** williamr@2: * Reserves light target exclusively for this client. williamr@2: * A higher priority client may cause lower priority client reservation williamr@2: * to be temporarily suspended. Commands can still be issued in suspended williamr@2: * state, but they will not be acted upon unless suspension is lifted williamr@2: * within specified duration. williamr@2: * The suspended client will not get any notification about suspension. williamr@2: * If light target is already reserved by a higher or equal priority application, williamr@2: * reserving will still succeeds, but reservation is immediately suspended. williamr@2: * williamr@2: * williamr@2: * @param aTarget Defines which light should be reserved. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aRestoreState If ETrue, the state frozen on last release will be williamr@2: * restored upon successful reservation. williamr@2: * I.e. if light was blinking when it was released by this williamr@2: * client the last time, it would start blinking again upon williamr@2: * successful reservation. williamr@2: * For the first reservation of each session this parameter williamr@2: * is always considered EFalse regardless of what is supplied, williamr@2: * as there is no previous frozen state to restore. williamr@2: * @param aForceNoCCoeEnv If EFalse, then reservation requires that this client is williamr@2: * on the foreground at the time of reservation and light williamr@2: * target will be automatically released and re-reserved based williamr@2: * on background/foreground status of the this client. This williamr@2: * also implies that CCoeEnv::Static() != NULL is required. williamr@2: * If ETrue, the client will not require CCoeEnv to be present williamr@2: * nor does it automatically reserve/release light by depending williamr@2: * on foreground/background status of the client. williamr@2: * Only trusted clients are allowed to set this flag to ETrue. williamr@2: * A client is considered trusted if it has nonstandard williamr@2: * priority defined in the internal lights policy of the williamr@2: * HW Resource Manager. A client can be defined trusted williamr@4: * only by a product. williamr@2: * williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrAccessDenied Paramenter aForceNoCCoeEnv is ETrue and client is not trusted. williamr@2: * @leave KErrBadHandle Parameter ForceNoCCoeEnv is EFalse and no CCoeEnv present. williamr@2: * @leave KErrNotReady Trying to reserve while on background and parameter williamr@2: * aForceNoCCoeEnv is EFalse. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv); williamr@2: williamr@2: /** williamr@2: * Releases light target if it was previously reserved for this client. williamr@2: * If this client has not reserved any of the specified lights, williamr@2: * this method does nothing. williamr@2: * Any reserved light targets that are released and have no other suspended williamr@2: * clients will be reset to default state, which is either lights on or lights off, williamr@2: * depending on system inactivity time. williamr@2: * williamr@2: * @param aTarget Defines which light should be released. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual void ReleaseLight(TInt aTarget); williamr@2: williamr@2: williamr@2: /** williamr@2: * The LightOnL method switches the specified target light on williamr@2: * for infinite duration using default intensity. Lights will use fade-in. williamr@2: * williamr@2: * Calling this method is equal to calling williamr@2: * LightOnL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultIntensity, ETrue). williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual void LightOnL(TInt aTarget); williamr@2: williamr@2: /** williamr@2: * The LightOnL method switches the specified target light on williamr@2: * for the specified duration using default intensity. Lights will use fade-in. williamr@2: * williamr@2: * Calling this method is equal to call williamr@2: * LightOnL(aTarget, aDuration, KHWRMDefaultIntensity, ETrue). williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aDuration Duration of the time the light is switched on measured in milliseconds. williamr@2: * After the duration expires, the light state for target will be changed williamr@2: * to whatever state was caused by the last infinite time duration call, or williamr@2: * default state determined by inactivity timer, in case there has not williamr@2: * been a previous infinite time duration call in this session. williamr@2: * If the aDuration time is KHWRMInfiniteDuration then it means an williamr@2: * infinite value that has to be stopped by calling of any of the other williamr@2: ' light control methods. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * williamr@2: * @leave KErrArgument Parameter aDuration is out of range. williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@2: virtual void LightOnL(TInt aTarget, williamr@4: TInt aDuration); williamr@2: williamr@2: /** williamr@2: * The LightOnL method switches the specified target light on williamr@2: * for the specified duration using specified intensity. Fade-in can also be controlled. williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aDuration Duration of the time the light is switched on measured in milliseconds. williamr@2: * After the duration expires, the light state for target will be changed williamr@2: * to whatever state was caused by the last infinite time duration call, or williamr@2: * default state determined by inactivity timer, in case there has not williamr@2: * been a previous infinite time duration call in this session. williamr@2: * If the aDuration time is KHWRMInfiniteDuration then it means williamr@2: * an infinite value that has to be stopped by calling of any of williamr@2: * the other light control methods. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default williamr@2: * intensity will be used. williamr@2: * Note: All devices might not support user defined intensity, in which case williamr@2: * device will behave in its default fashion. williamr@2: * @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in. williamr@2: * Note: All devices will not support fade-in, in which case device will williamr@2: * behave in its default fashion. williamr@2: * williamr@2: * @leave KErrArgument One of the parameters is out of range. williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@2: virtual void LightOnL(TInt aTarget, williamr@2: TInt aDuration, williamr@2: TInt aIntensity, williamr@4: TBool aFadeIn); williamr@2: williamr@2: /** williamr@2: * The LightBlinkL method blinks the target light(s) of the device for infinite duration williamr@2: * using default intensity. williamr@2: * williamr@2: * Calling this method is equal to call williamr@4: * @code williamr@2: * LightBlinkL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultCycleTime, williamr@2: * KHWRMDefaultCycleTime, KHWRMDefaultIntensity). williamr@4: * @endcode williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual void LightBlinkL(TInt aTarget); williamr@2: williamr@2: /** williamr@2: * The LightBlinkL method blinks the target light(s) of the device for specified duration williamr@2: * using default intensity. williamr@2: * williamr@2: * Calling this method is equal to calling williamr@2: * LightBlinkL(aTarget, aDuration, KHWRMDefaultCycleTime, williamr@2: * KHWRMDefaultCycleTime, KHWRMDefaultIntensity). williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aDuration Duration of the time the light is set to blink measured in milliseconds. williamr@2: * After the duration expires, the light state for target will be changed williamr@2: * to whatever state was caused by the last infinite time duration call, or williamr@2: * default state determined by inactivity timer, in case there has not williamr@2: * been a previous infinite time duration call in this session. williamr@2: * If the aTotalDuration time is KHWRMInfiniteDuration then it williamr@2: * means an infinite value that has to be williamr@2: * stopped by calling of any of the other light control methods. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * williamr@2: * @leave KErrArgument Parameter aDuration is out of range. williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@2: virtual void LightBlinkL(TInt aTarget, williamr@4: TInt aDuration); williamr@2: williamr@2: /** williamr@2: * The LightBlinkL method blinks the target light(s) of the device for specified duration williamr@2: * using specified intensity. On- and Off-cycle times of the blinking can also be controlled. williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aDuration Duration of the time the light is set to blink measured in milliseconds. williamr@2: * After the duration expires, the light state for target will be changed williamr@2: * to whatever state was caused by the last infinite time duration call, or williamr@2: * default state determined by inactivity timer, in case there has not williamr@2: * been a previous infinite time duration call in this session. williamr@2: * If the aTotalDuration time is KHWRMInfiniteDuration then it williamr@2: * means an infinite value that has to be williamr@2: * stopped by calling of any of the other light control methods. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * @param aOnDuration Duration time, measured in milliseconds, of how long the Light is williamr@2: * switched on in every Blink cycle. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * For device default cycle duration, use value KHWRMDefaultCycleTime. williamr@2: * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, williamr@2: * both must be KHWRMDefaultCycleTime. williamr@2: * Some devices might not support variable blink cycle times, in which williamr@2: * case default value will be substituted. williamr@2: * @param aOffDuration Duration time, measured in milliseconds, of how long the Light williamr@2: * is switched off in every Blink cycle. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * For device default cycle duration, use value KHWRMDefaultCycleTime. williamr@2: * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, williamr@2: * both must be KHWRMDefaultCycleTime. williamr@2: * Some devices might not support variable blink cycle times, in which williamr@2: * case default value will be substituted. williamr@2: * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default williamr@2: * intensity will be used. williamr@2: * Note: All devices might not support user defined intensity, in which case williamr@2: * device will behave in its default fashion. williamr@2: * williamr@2: * @leave KErrArgument One of the parameters is out of range or otherwise invalid. williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@2: virtual void LightBlinkL(TInt aTarget, williamr@2: TInt aDuration, williamr@2: TInt aOnDuration, williamr@2: TInt aOffDuration, williamr@4: TInt aIntensity); williamr@2: williamr@2: /** williamr@2: * The LightOffL method switches the device light off for the specified target for williamr@2: * infinite duration. Lights will be switched off with fade-out. williamr@2: * williamr@2: * Calling this method is equal to call williamr@2: * LightOffL(aTarget, KHWRMInfiniteDuration, ETrue). williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual void LightOffL(TInt aTarget); williamr@2: williamr@2: /** williamr@2: * The LightOffL method switches the device light off for the specified target for williamr@2: * the specified duration time. Lights will be switched off with fade-out. williamr@2: * williamr@2: * Calling this method is equal to call LightOffL(aTarget, aDuration, ETrue). williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aDuration Duration of the time the light is switched off measured in milliseconds. williamr@2: * After the duration expires, the light state for target will be changed williamr@2: * to whatever state was caused by the last infinite time duration call, or williamr@2: * default state determined by inactivity timer, in case there has not williamr@2: * been a previous infinite time duration call in this session. williamr@2: * If the aDuration time is KHWRMInfiniteDuration then it williamr@2: * means an infinite value that has to be williamr@2: * stopped by calling of any of the other light control methods. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * williamr@2: * @leave KErrArgument Parameter aDuration is out of range. williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@2: virtual void LightOffL(TInt aTarget, williamr@4: TInt aDuration); williamr@2: williamr@2: /** williamr@2: * The LightOffL method switches the device light off for the specified target for williamr@2: * the specified duration time. Lights fade-out can also be controlled. williamr@2: * williamr@2: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@2: * be specified with using bitwise-or. williamr@2: * @param aDuration Duration of the time the light is switched off measured in milliseconds. williamr@2: * After the duration expires, the light state for target will be changed williamr@2: * to whatever state was caused by the last infinite time duration call, or williamr@2: * default state determined by inactivity timer, in case there has not williamr@2: * been a previous infinite time duration call in this session. williamr@2: * If the aDuration time is KHWRMInfiniteDuration then it williamr@2: * means an infinite value that has to be williamr@2: * stopped by calling of any of the other light control methods. williamr@2: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@2: * @param aFadeOut If ETrue, lights will not turn off instantly but instead smoothly fade-out williamr@2: * Note: All devices will not support fade-out, in which case device will williamr@2: * behave in its default fashion. williamr@2: * williamr@2: * @leave KErrArgument aDuration is out of range. williamr@2: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@2: * @leave KErrBadHandle Light session has been invalidated. williamr@2: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@2: * @leave KErrInUse One or more of specified targets are not reserved for williamr@2: * this client but are reserved for others. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: * @leave KErrGeneral There is a hardware error. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@2: virtual void LightOffL(TInt aTarget, williamr@2: TInt aDuration, williamr@4: TBool aFadeOut); williamr@2: williamr@2: /** williamr@2: * This method retrieves the current light status. williamr@2: * williamr@2: * @param aTarget Defines which light status is returned. williamr@2: * This method only supports single target, as different williamr@2: * targets might have different statuses. williamr@2: * @return TLightStatus indicating the current light status. If there is a problem or williamr@2: * multiple targets were specified, CHWRMLight::ELightStatusUnknown is returned. williamr@2: * williamr@2: * @see MHWRMLightObserver williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual TLightStatus LightStatus(TInt aTarget) const; williamr@2: williamr@2: /** williamr@2: * This method retrieves the supported light targets of the device. williamr@2: * Any attempt to use or reserve unsupported targets will fail with williamr@2: * KErrNotSupported. williamr@2: * williamr@2: * @return Bitmask containing supported light targets. williamr@2: * williamr@2: * @see TLightTarget williamr@2: */ williamr@4: virtual TInt SupportedTargets() const; williamr@4: williamr@4: williamr@4: /* williamr@4: * Used for setting color of Light Target(s). williamr@4: * williamr@4: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@4: * be specified with using bitwise-or. williamr@4: * williamr@4: * @param aRGB RGB Values to be set for the target(s). williamr@4: * williamr@4: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@4: * @leave KErrBadHandle Light session has been invalidated. williamr@4: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@4: * @leave KErrInUse One or more of specified targets are not reserved for williamr@4: * this client but are reserved for others. williamr@4: * @leave KErrNoMemory There is a memory allocation failure. williamr@4: williamr@4: * @see THWRMLightColor williamr@4: */ williamr@4: IMPORT_C void SetLightColorL(TInt aTarget, THWRMLightColor& aRGB); williamr@4: williamr@4: /* williamr@4: * Used for setting default color of Light Target(s). williamr@4: * williamr@4: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@4: * be specified with using bitwise-or. williamr@4: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@4: * @leave KErrBadHandle Light session has been invalidated. williamr@4: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@4: * @leave KErrInUse One or more of specified targets are not reserved for williamr@4: * this client but are reserved for others. williamr@4: * @leave KErrNoMemory There is a memory allocation failure. williamr@4: williamr@4: */ williamr@4: williamr@4: IMPORT_C void SetLightDefaultColorL(TInt aTarget); williamr@4: williamr@4: /** williamr@4: * The LightOnL method switches the specified target light on williamr@4: * for the specified duration and specified color. williamr@4: * williamr@4: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@4: * be specified with using bitwise-or. williamr@4: * @param aDuration Duration of the time the light is switched on measured in milliseconds. williamr@4: * After the duration expires, the light state for target will be changed williamr@4: * to whatever state was caused by the last infinite time duration call, or williamr@4: * default state determined by inactivity timer, in case there has not williamr@4: * been a previous infinite time duration call in this session. williamr@4: * If the aDuration time is KHWRMInfiniteDuration then it means williamr@4: * an infinite value that has to be stopped by calling of any of williamr@4: * the other light control methods. williamr@4: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@4: * @param aRGBParam RGB Values to be set for the target(s). williamr@4: * williamr@4: * @leave KErrArgument One of the parameters is out of range. williamr@4: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@4: * @leave KErrBadHandle Light session has been invalidated. williamr@4: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@4: * @leave KErrInUse One or more of specified targets are not reserved for williamr@4: * this client but are reserved for others. williamr@4: * @leave KErrNoMemory There is a memory allocation failure. williamr@4: * @leave KErrGeneral There is a hardware error. williamr@4: * williamr@4: * @see TLightTarget williamr@4: * @see THWRMLightColor williamr@4: */ williamr@4: IMPORT_C void LightOnL(TInt aTarget, TInt aDuration, const THWRMLightColor& aRGBParam); williamr@4: williamr@4: /** williamr@4: * The LightOnL method switches the specified target light on williamr@4: * for the specified duration using specified intensity and color. Fade-in can also be controlled. williamr@4: * williamr@4: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@4: * be specified with using bitwise-or. williamr@4: * @param aDuration Duration of the time the light is switched on measured in milliseconds. williamr@4: * After the duration expires, the light state for target will be changed williamr@4: * to whatever state was caused by the last infinite time duration call, or williamr@4: * default state determined by inactivity timer, in case there has not williamr@4: * been a previous infinite time duration call in this session. williamr@4: * If the aDuration time is KHWRMInfiniteDuration then it means williamr@4: * an infinite value that has to be stopped by calling of any of williamr@4: * the other light control methods. williamr@4: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@4: * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default williamr@4: * intensity will be used. williamr@4: * Note: All devices might not support user defined intensity, in which case williamr@4: * device will behave in its default fashion. williamr@4: * @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in. williamr@4: * Note: All devices will not support fade-in, in which case device will williamr@4: * behave in its default fashion. williamr@4: * @param aRGBParam RGB Values to be set for the target(s). williamr@4: * williamr@4: * @leave KErrArgument One of the parameters is out of range. williamr@4: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@4: * @leave KErrBadHandle Light session has been invalidated. williamr@4: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@4: * @leave KErrInUse One or more of specified targets are not reserved for williamr@4: * this client but are reserved for others. williamr@4: * @leave KErrNoMemory There is a memory allocation failure. williamr@4: * @leave KErrGeneral There is a hardware error. williamr@4: * williamr@4: * @see TLightTarget williamr@4: * @see THWRMLightColor williamr@4: */ williamr@4: williamr@4: IMPORT_C void LightOnL(TInt aTarget, TInt aDuration, TInt aIntensity, TBool aFadeIn, williamr@4: const THWRMLightColor& aRGBParam); williamr@4: williamr@4: /** williamr@4: * The LightBlinkL method blinks the target light(s) of the device for specified duration and color williamr@4: * using default intensity. williamr@4: * williamr@4: * williamr@4: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@4: * be specified with using bitwise-or. williamr@4: * @param aDuration Duration of the time the light is set to blink measured in milliseconds. williamr@4: * After the duration expires, the light state for target will be changed williamr@4: * to whatever state was caused by the last infinite time duration call, or williamr@4: * default state determined by inactivity timer, in case there has not williamr@4: * been a previous infinite time duration call in this session. williamr@4: * If the aTotalDuration time is KHWRMInfiniteDuration then it williamr@4: * means an infinite value that has to be williamr@4: * stopped by calling of any of the other light control methods. williamr@4: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@4: * williamr@4: * @param aRGBParam RGB Values to be set for the target(s). williamr@4: * williamr@4: * @leave KErrArgument Parameter aDuration is out of range. williamr@4: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@4: * @leave KErrBadHandle Light session has been invalidated. williamr@4: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@4: * @leave KErrInUse One or more of specified targets are not reserved for williamr@4: * this client but are reserved for others. williamr@4: * @leave KErrNoMemory There is a memory allocation failure. williamr@4: * @leave KErrGeneral There is a hardware error. williamr@4: * williamr@4: * @see TLightTarget williamr@4: * @see THWRMLightColor williamr@4: */ williamr@4: williamr@4: IMPORT_C void LightBlinkL(TInt aTarget, TInt aDuration, const THWRMLightColor& aRGBParam); williamr@4: williamr@4: /** williamr@4: * The LightBlinkL method blinks the target light(s) of the device for specified duration williamr@4: * using specified intensity and color. On- and Off-cycle times of the blinking can also be controlled. williamr@4: * williamr@4: * @param aTarget Defines which light should be controlled. Multiple lights can williamr@4: * be specified with using bitwise-or. williamr@4: * @param aDuration Duration of the time the light is set to blink measured in milliseconds. williamr@4: * After the duration expires, the light state for target will be changed williamr@4: * to whatever state was caused by the last infinite time duration call, or williamr@4: * default state determined by inactivity timer, in case there has not williamr@4: * been a previous infinite time duration call in this session. williamr@4: * If the aTotalDuration time is KHWRMInfiniteDuration then it williamr@4: * means an infinite value that has to be williamr@4: * stopped by calling of any of the other light control methods. williamr@4: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@4: * @param aOnDuration Duration time, measured in milliseconds, of how long the Light is williamr@4: * switched on in every Blink cycle. williamr@4: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@4: * For device default cycle duration, use value KHWRMDefaultCycleTime. williamr@4: * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, williamr@4: * both must be KHWRMDefaultCycleTime. williamr@4: * Some devices might not support variable blink cycle times, in which williamr@4: * case default value will be substituted. williamr@4: * @param aOffDuration Duration time, measured in milliseconds, of how long the Light williamr@4: * is switched off in every Blink cycle. williamr@4: * Duration can have maximum value of KHWRMLightMaxDuration. williamr@4: * For device default cycle duration, use value KHWRMDefaultCycleTime. williamr@4: * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, williamr@4: * both must be KHWRMDefaultCycleTime. williamr@4: * Some devices might not support variable blink cycle times, in which williamr@4: * case default value will be substituted. williamr@4: * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default williamr@4: * intensity will be used. williamr@4: * Note: All devices might not support user defined intensity, in which case williamr@4: * device will behave in its default fashion. williamr@4: * williamr@4: * @param aRGBParam RGB Values to be set for the target(s). williamr@4: * williamr@4: * @leave KErrArgument One of the parameters is out of range or otherwise invalid. williamr@4: * @leave KErrNotSupported One or more of specified targets are not supported. williamr@4: * @leave KErrBadHandle Light session has been invalidated. williamr@4: * @leave KErrTimedOut Timeout occurred in controlling light. williamr@4: * @leave KErrInUse One or more of specified targets are not reserved for williamr@4: * this client but are reserved for others. williamr@4: * @leave KErrNoMemory There is a memory allocation failure. williamr@4: * @leave KErrGeneral There is a hardware error. williamr@4: * williamr@4: * @see TLightTarget williamr@4: * @see THWRMLightColor williamr@4: */ williamr@4: williamr@4: IMPORT_C void LightBlinkL(TInt aTarget, TInt aDuration, TInt aOnDuration, TInt aOffDuration, williamr@4: TInt aIntensity, const THWRMLightColor& aRGBParam); williamr@4: williamr@4: williamr@4: williamr@4: williamr@4: private: williamr@4: CHWRMLight(); williamr@4: void ConstructL(MHWRMLightObserver* aCallback); williamr@4: williamr@4: private: williamr@4: CHWRMEnhancedLight* iEnhanced; williamr@4: williamr@2: }; williamr@2: williamr@2: /** williamr@2: * A callback interface for light status reporting. williamr@2: * williamr@2: * If the client requires up-to-date status information, the client needs williamr@2: * to derive a class from the MHWRMlightObserver interface and implement williamr@2: * the LightStatusChanged() method. williamr@2: * williamr@2: * A callback object header example: williamr@2: * williamr@2: * @code williamr@2: * // INCLUDES williamr@4: * #include // Link against HWRMLightClient.lib. williamr@2: * williamr@2: * class CTests : public CBase, williamr@2: * public MHWRMLightObserver williamr@2: * { williamr@2: * public: williamr@2: * CTests(); williamr@2: * ~CTests(); williamr@2: * williamr@2: * void ConstructL(); williamr@2: * static CTests* NewL(); williamr@2: * williamr@2: * // from MHWRMLightObserver williamr@2: * virtual void LightStatusChanged(TInt aTarget, williamr@2: * CHWRMLight::TLightStatus aStatus); williamr@2: * williamr@2: * private: williamr@2: * CHWRMLight* iLight; williamr@2: * }; williamr@2: * williamr@2: * @endcode williamr@2: * williamr@2: * A callback method implementation example: williamr@2: * williamr@2: * @code williamr@2: * void CTests::LightStatusChanged(TInt aTarget, williamr@2: * CHWRMLight::TLightStatus aStatus) williamr@2: * { williamr@2: * RDebug::Print(_L("### Light state changed for target: 0x%x"), aTarget); williamr@2: * switch ( aStatus ) williamr@2: * { williamr@2: * case CHWRMLight::ELightOn: williamr@2: * RDebug::Print(_L("### Light state changed: ELightOn")); williamr@2: * break; williamr@2: * case CHWRMLight::ELightOff: williamr@2: * RDebug::Print(_L("### Light state changed: ELightOff")); williamr@2: * break; williamr@2: * case CHWRMLight::ELightBlink: williamr@2: * RDebug::Print(_L("### Light state changed: ELightBlink")); williamr@2: * break; williamr@2: * case CHWRMLight::ELightStatusUnknown: williamr@2: * RDebug::Print(_L("### Light state changed: ELightStatusUnknown")); williamr@2: * break; williamr@2: * default: williamr@2: * RDebug::Print(_L("### Light state changed: UNDEFINED !")); williamr@2: * break; williamr@2: * } williamr@2: * } williamr@2: * williamr@2: * @endcode williamr@2: * williamr@4: * @publishedAll williamr@4: * @released williamr@2: */ williamr@2: class MHWRMLightObserver williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Called when the device light status changes. williamr@2: * Note that if the light status for certain target changes williamr@2: * very rapidly, some state transitions might be missed. williamr@2: * It is however guaranteed that latest state is always obtained. williamr@2: * williamr@2: * @param aTarget Indicates target(s) the new status applies to. williamr@2: * @param aStatus Indicates light request status. williamr@2: * williamr@2: * @see CHWRMLight::TLightTarget williamr@2: * @see CHWRMLight::TLightStatus williamr@2: */ williamr@2: virtual void LightStatusChanged(TInt aTarget, williamr@2: CHWRMLight::TLightStatus aStatus) = 0; williamr@2: }; williamr@2: williamr@2: williamr@2: #endif // HWRMLIGHT_H williamr@2: williamr@2: // End of File