/*

 * Copyright (c) 2008 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:  Channel condition object

 *

 */

 #ifndef SENSRVCHANNELCONDITION_H

 #define SENSRVCHANNELCONDITION_H

 //  INCLUDES

 #include <e32base.h>

 // FORWARD DECLARATIONS

 class CSensrvChannelCondition;

 // DATA TYPES

 /**

 * RPointerArray based channel condition list

 */

 typedef RPointerArray<CSensrvChannelCondition> RSensrvChannelConditionList;

 /**

 * Defines condition type.

 * 

 * Conditions can be standalone conditions or a part of a two-part condition.

 * 

 * - ESensrvLimitCondition is a standalone condition which has a limit. This kind of condition

 *   is met when the observed value exceeds or equals the condition value, depending on the

 *   operator used in the condition.

 * - ESensrvRangeConditionLowerLimit is the first part of a two-part range condition. This kind

 *   of condition is met when the observed value is between specified lower and upper limits or

 *   beyond specified range, depending on the operators used in the two conditions that make up

 *   the range.

 *   A condition set that contains ESensrvRangeConditionLowerLimit condition must also contain

 *   ESensrvRangeConditionUpperLimit condition using the same index. Both lower and upper limit

 *   operators must have different direction, i.e. if lower limit has "less than" operator, then

 *   upper limit must have "greater than" operator, and vice versa. ESensrvOperatorEquals operator

 *   is not valid for range condition.

 * - ESensrvRangeConditionUpperLimit is the second part of a two-part range condition.

 * - ESensrvBinaryCondition is used for channels that provide bitmask values (typically event

 *   channels). ESensrvOperatorBinaryXxx operations can only be used with this condition type.

 * 

 * @see CSensrvChannelCondition

 * @see TSensrvConditionOperator

 */

 enum TSensrvConditionType

     {

     /** Standalone condition which has a limit */

     ESensrvSingleLimitCondition = 0,

     /** 1st part of a two-part range condition. 2nd part is ESensrvRangeConditionUpperLimit */

     ESensrvRangeConditionLowerLimit,

     /** 2nd part of a two-part range condition. 1st part is ESensrvRangeConditionLowerLimit */

     ESensrvRangeConditionUpperLimit,

     /** Standalone condition for binary operations */

     ESensrvBinaryCondition

     };

 /*

 * Defines condition operator

 * 

 * For a range condition a ConditionSet must contain 2 Conditions each with an operator in a

 * different direction. i.e. There must be matching greater than and less than pair. Also the pair

 * of conditions must have the same index in the ConditionSet.

 * 

 * - ESensrvOperatorEquals checks if the value got from the sensor is equal to the set value. This is

 *   not a valid operator for a range condition.

 * - ESensrvOperatorGreaterThan checks if the value got from the sensor is greater than the set limit. 

 *   This is not a valid operator for a binary condition.

 * - ESensrvOperatorGreaterThanOrEquals checks if the value got from the sensor is greater than or equal

 *   to the set limit. This is not a valid operator for a binary condition.

 * - ESensrvOperatorLessThan checks if the value got from the sensor is less than the set limit. This is

 *   not a valid operator for a binary condition.

 * - ESensrvOperatorLessThanOrEquals checks if the value got from the sensor is less than or equal to the

 *   set limit. This is not a valid operator for a binary condition.

 * - ESensrvOperatorBinaryAnd checks if a bitmask data value got from the sensor has set at least one of

 *   the bits set in the condition value. In other words, if result of datavalue & conditionvalue != 0,

 *   there is a match. This is not a valid operator for a single limit or range conditions.

 * 

 *   Example: 

 *   Condition value: 01101101

 *   Data value:      10001010

 *   Resulting value: 00001000 -> Non-zero, which indicates a match.

 * - ESensrvOperatorBinaryAll checks if a bitmask data value got from the sensor has set all of the bits

 *   set in the condition value. The rest of the data value bits are ignored. In other words, if

 *   datavalue & conditionvalue == conditionvalue, there is a match. Not a valid operator for a single limit

 *   or range conditions.

 *   Example: 

 *   Condition value: 01101101

 *   Data value:      10001010

 *   Resulting value: 00001000 -> Not equal to condition value -> Not a match.

 * 

 * @see CSensrvChannelCondition

 * @see TSensrvConditionType

 */

 enum TSensrvConditionOperator

     {

     ESensrvOperatorEquals = 0,

     ESensrvOperatorGreaterThan,

     ESensrvOperatorGreaterThanOrEquals,

     ESensrvOperatorLessThan,

     ESensrvOperatorLessThanOrEquals,

     ESensrvOperatorBinaryAnd,

     ESensrvOperatorBinaryAll    

     };

 // CLASS DECLARATION

 /**

 * CSensrvChannelCondition represents a channel condition item. Channel conditions are added to a channel

 * condition set. A channel condition set is met when all channel conditions are met at the same time, if it

 * is AND-type set, or when single condition is met if it is OR-type set. Only one channel condition can be

 * set for each data item in single channel condition set. Certain condition types (range conditions) require

 * two condition objects (upper and lower limit) in a condition set for the set to be valid. The pair of

 * conditions must both have the same index in the condition set and they are considered a single channel

 * condition. 

 * 

 * Each Condition has an ItemIndex associated with it. When a Condition is added to a Condition Set using

 * CSensrvChannelConditionSet::AddChannelConditionL() this index must be different to all other conditions

 * added to the set with the exception of range conditions as described above. If the index supplied already

 * exists and the condition is not part of a range condition then

 * CSensrvChannelConditionSet::AddChannelConditionL() leaves with KErrArgument.  

 * 

 * @see CSensrvChannelConditionSet

 * @see TSensrvConditionType

 * @see TSensrvConditionOperator

 * @lib sensrvutil.lib

 * @since S60 5.0

 */

 NONSHARABLE_CLASS( CSensrvChannelCondition ): public CBase

     {

 public:

     /**

     * Two-phase constructor

     * 

     * @param   aConditionType Defines the type of the condition

     * @param   aConditionOperator Defines the operator used in the condition

     * @param   aItemIndex Item index to be used in the condition evaluation

     * @param   aValue Value to be used in condition evaluation. By default this should be a packaged data

     *         object of the channel. See the channel specific headers in \epoc32\include\sensors\channels.

     *         If the channel type requires a different type of value, that must be indicated clearly in

     *        the channel specific header defining the channel.

     * @return Pointer to created object

     * @leave  KErrNoMemory

     * @leave  KErrArgument if parameters are invalid or are less than 0

     * @leave  One of the system-wide error codes

     */  

     IMPORT_C static CSensrvChannelCondition* NewL

                 ( TInt aConditionType, 

                   TInt aConditionOperator,

                   TInt aItemIndex,

                   TDesC8& aValue );

     /**

     * Two-phase constructor

     * 

     * @param   aConditionType Defines the type of the condition

     * @param   aConditionOperator Defines the operator used in the condition

     * @param   aItemIndex Item index to be used in the condition evaluation

     * @param   aValue Value to be used in condition evaluation. By default this should be a packaged data

     *         object of the channel. See the channel specific headers in \epoc32\include\sensors\channels.

     *         If the channel type requires a different type of value, that must be indicated clearly in

     *         the channel specific header defining the channel.

     * @return Pointer to created object

     * @leave  KErrNoMemory

     * @leave  KErrArgument if parameters are invalid or are less than 0

     * @leave  One of the system-wide error codes

     */  

     IMPORT_C static CSensrvChannelCondition* NewLC

                 ( TInt aConditionType, 

                   TInt aConditionOperator,

                   TInt aItemIndex,

                   TDesC8& aValue );

 public:  

     /**

     * Get condition type

     *  

     * @return Condition Type

     */    

     virtual TInt ConditionType() const = 0;

     /**

     * Get condition operator

     *

     * @return TInt Condition operator

     */      

     virtual TInt ConditionOperator() const = 0;

     /**

     * Get condition item index

     *

     * @return TInt Condition item index

     */      

     virtual TInt ConditionItemIndex() const = 0;

     /**

     * Get condition value.

     *

     * @param  aValue Value of the condition is copied to the supplied descriptor

     * @return KErrOverflow if aData is the wrong size for data item or one of the system-wide error codes

     */      

     virtual TInt GetConditionValue( TDes8& aValue ) const = 0;        

     /**

     * Get condition value as reference.

     * 

     * @return Reference to condition value descriptor.

     */      

     virtual const TDesC8& ConditionValue() const = 0;        

 public:

     /**

     * Default constructor. 

     */

     CSensrvChannelCondition();

     };

 #endif //SENSRVCHANNELCONDITION_H

 // End of File