williamr@2: /*
williamr@2: * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Channel condition object
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef SENSRVCHANNELCONDITION_H
williamr@2: #define SENSRVCHANNELCONDITION_H
williamr@2: 
williamr@2: //  INCLUDES
williamr@2: #include <e32base.h>
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: 
williamr@2: class CSensrvChannelCondition;
williamr@2: 
williamr@2: // DATA TYPES
williamr@2: 
williamr@2: /**
williamr@2: * RPointerArray based channel condition list
williamr@2: */
williamr@2: typedef RPointerArray<CSensrvChannelCondition> RSensrvChannelConditionList;
williamr@2: 
williamr@2: /**
williamr@2: * Defines condition type.
williamr@2: * 
williamr@2: * Conditions can be standalone conditions or a part of a two-part condition.
williamr@2: * 
williamr@2: * - ESensrvLimitCondition is a standalone condition which has a limit. This kind of condition
williamr@2: *   is met when the observed value exceeds or equals the condition value, depending on the
williamr@2: *   operator used in the condition.
williamr@2: * - ESensrvRangeConditionLowerLimit is the first part of a two-part range condition. This kind
williamr@2: *   of condition is met when the observed value is between specified lower and upper limits or
williamr@2: *   beyond specified range, depending on the operators used in the two conditions that make up
williamr@2: *   the range.
williamr@2: *   A condition set that contains ESensrvRangeConditionLowerLimit condition must also contain
williamr@2: *   ESensrvRangeConditionUpperLimit condition using the same index. Both lower and upper limit
williamr@2: *   operators must have different direction, i.e. if lower limit has "less than" operator, then
williamr@2: *   upper limit must have "greater than" operator, and vice versa. ESensrvOperatorEquals operator
williamr@2: *   is not valid for range condition.
williamr@2: * - ESensrvRangeConditionUpperLimit is the second part of a two-part range condition.
williamr@2: * - ESensrvBinaryCondition is used for channels that provide bitmask values (typically event
williamr@2: *   channels). ESensrvOperatorBinaryXxx operations can only be used with this condition type.
williamr@2: * 
williamr@2: * @see CSensrvChannelCondition
williamr@2: * @see TSensrvConditionOperator
williamr@2: */
williamr@2: enum TSensrvConditionType
williamr@2:     {
williamr@2:     /** Standalone condition which has a limit */
williamr@2:     ESensrvSingleLimitCondition = 0,
williamr@2:     /** 1st part of a two-part range condition. 2nd part is ESensrvRangeConditionUpperLimit */
williamr@2:     ESensrvRangeConditionLowerLimit,
williamr@2:     /** 2nd part of a two-part range condition. 1st part is ESensrvRangeConditionLowerLimit */
williamr@2:     ESensrvRangeConditionUpperLimit,
williamr@2:     /** Standalone condition for binary operations */
williamr@2:     ESensrvBinaryCondition
williamr@2:     };
williamr@2: 
williamr@2: /*
williamr@2: * Defines condition operator
williamr@2: * 
williamr@2: * For a range condition a ConditionSet must contain 2 Conditions each with an operator in a
williamr@2: * different direction. i.e. There must be matching greater than and less than pair. Also the pair
williamr@2: * of conditions must have the same index in the ConditionSet.
williamr@2: * 
williamr@2: * - ESensrvOperatorEquals checks if the value got from the sensor is equal to the set value. This is
williamr@2: *   not a valid operator for a range condition.
williamr@2: * - ESensrvOperatorGreaterThan checks if the value got from the sensor is greater than the set limit. 
williamr@2: *   This is not a valid operator for a binary condition.
williamr@2: * - ESensrvOperatorGreaterThanOrEquals checks if the value got from the sensor is greater than or equal
williamr@2: *   to the set limit. This is not a valid operator for a binary condition.
williamr@2: * - ESensrvOperatorLessThan checks if the value got from the sensor is less than the set limit. This is
williamr@2: *   not a valid operator for a binary condition.
williamr@2: * - ESensrvOperatorLessThanOrEquals checks if the value got from the sensor is less than or equal to the
williamr@2: *   set limit. This is not a valid operator for a binary condition.
williamr@2: * - ESensrvOperatorBinaryAnd checks if a bitmask data value got from the sensor has set at least one of
williamr@2: *   the bits set in the condition value. In other words, if result of datavalue & conditionvalue != 0,
williamr@2: *   there is a match. This is not a valid operator for a single limit or range conditions.
williamr@2: * 
williamr@2: *   Example: 
williamr@2: *   Condition value: 01101101
williamr@2: *   Data value:      10001010
williamr@2: *   Resulting value: 00001000 -> Non-zero, which indicates a match.
williamr@2: * - ESensrvOperatorBinaryAll checks if a bitmask data value got from the sensor has set all of the bits
williamr@2: *   set in the condition value. The rest of the data value bits are ignored. In other words, if
williamr@2: *   datavalue & conditionvalue == conditionvalue, there is a match. Not a valid operator for a single limit
williamr@2: *   or range conditions.
williamr@2: *   Example: 
williamr@2: *   Condition value: 01101101
williamr@2: *   Data value:      10001010
williamr@2: *   Resulting value: 00001000 -> Not equal to condition value -> Not a match.
williamr@2: * 
williamr@2: * @see CSensrvChannelCondition
williamr@2: * @see TSensrvConditionType
williamr@2: */
williamr@2: enum TSensrvConditionOperator
williamr@2:     {
williamr@2:     ESensrvOperatorEquals = 0,
williamr@2:     ESensrvOperatorGreaterThan,
williamr@2:     ESensrvOperatorGreaterThanOrEquals,
williamr@2:     ESensrvOperatorLessThan,
williamr@2:     ESensrvOperatorLessThanOrEquals,
williamr@2:     ESensrvOperatorBinaryAnd,
williamr@2:     ESensrvOperatorBinaryAll    
williamr@2:     };
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: * CSensrvChannelCondition represents a channel condition item. Channel conditions are added to a channel
williamr@2: * condition set. A channel condition set is met when all channel conditions are met at the same time, if it
williamr@2: * is AND-type set, or when single condition is met if it is OR-type set. Only one channel condition can be
williamr@2: * set for each data item in single channel condition set. Certain condition types (range conditions) require
williamr@2: * two condition objects (upper and lower limit) in a condition set for the set to be valid. The pair of
williamr@2: * conditions must both have the same index in the condition set and they are considered a single channel
williamr@2: * condition. 
williamr@2: * 
williamr@2: * Each Condition has an ItemIndex associated with it. When a Condition is added to a Condition Set using
williamr@2: * CSensrvChannelConditionSet::AddChannelConditionL() this index must be different to all other conditions
williamr@2: * added to the set with the exception of range conditions as described above. If the index supplied already
williamr@2: * exists and the condition is not part of a range condition then
williamr@2: * CSensrvChannelConditionSet::AddChannelConditionL() leaves with KErrArgument.  
williamr@2: * 
williamr@2: * @see CSensrvChannelConditionSet
williamr@2: * @see TSensrvConditionType
williamr@2: * @see TSensrvConditionOperator
williamr@2: * @lib sensrvutil.lib
williamr@2: * @since S60 5.0
williamr@2: */
williamr@2: NONSHARABLE_CLASS( CSensrvChannelCondition ): public CBase
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:     * Two-phase constructor
williamr@2:     * 
williamr@2:     * @param   aConditionType Defines the type of the condition
williamr@2:     * @param   aConditionOperator Defines the operator used in the condition
williamr@2:     * @param   aItemIndex Item index to be used in the condition evaluation
williamr@2:     * @param   aValue Value to be used in condition evaluation. By default this should be a packaged data
williamr@2:     *         object of the channel. See the channel specific headers in \epoc32\include\sensors\channels.
williamr@2:     *         If the channel type requires a different type of value, that must be indicated clearly in
williamr@2:     *        the channel specific header defining the channel.
williamr@2:     * @return Pointer to created object
williamr@2:     * @leave  KErrNoMemory
williamr@2:     * @leave  KErrArgument if parameters are invalid or are less than 0
williamr@2:     * @leave  One of the system-wide error codes
williamr@2:     */  
williamr@2:     IMPORT_C static CSensrvChannelCondition* NewL
williamr@2:                 ( TInt aConditionType, 
williamr@2:                   TInt aConditionOperator,
williamr@2:                   TInt aItemIndex,
williamr@2:                   TDesC8& aValue );
williamr@2:                   
williamr@2:     /**
williamr@2:     * Two-phase constructor
williamr@2:     * 
williamr@2:     * @param   aConditionType Defines the type of the condition
williamr@2:     * @param   aConditionOperator Defines the operator used in the condition
williamr@2:     * @param   aItemIndex Item index to be used in the condition evaluation
williamr@2:     * @param   aValue Value to be used in condition evaluation. By default this should be a packaged data
williamr@2:     *         object of the channel. See the channel specific headers in \epoc32\include\sensors\channels.
williamr@2:     *         If the channel type requires a different type of value, that must be indicated clearly in
williamr@2:     *         the channel specific header defining the channel.
williamr@2:     * @return Pointer to created object
williamr@2:     * @leave  KErrNoMemory
williamr@2:     * @leave  KErrArgument if parameters are invalid or are less than 0
williamr@2:     * @leave  One of the system-wide error codes
williamr@2:     */  
williamr@2:     IMPORT_C static CSensrvChannelCondition* NewLC
williamr@2:                 ( TInt aConditionType, 
williamr@2:                   TInt aConditionOperator,
williamr@2:                   TInt aItemIndex,
williamr@2:                   TDesC8& aValue );
williamr@2: public:  
williamr@2:     
williamr@2:     /**
williamr@2:     * Get condition type
williamr@2:     *  
williamr@2:     * @return Condition Type
williamr@2:     */    
williamr@2:     virtual TInt ConditionType() const = 0;
williamr@2: 
williamr@2:     /**
williamr@2:     * Get condition operator
williamr@2:     *
williamr@2:     * @return TInt Condition operator
williamr@2:     */      
williamr@2:     virtual TInt ConditionOperator() const = 0;
williamr@2:   
williamr@2:     /**
williamr@2:     * Get condition item index
williamr@2:     *
williamr@2:     * @return TInt Condition item index
williamr@2:     */      
williamr@2:     virtual TInt ConditionItemIndex() const = 0;
williamr@2: 
williamr@2:     /**
williamr@2:     * Get condition value.
williamr@2:     *
williamr@2:     * @param  aValue Value of the condition is copied to the supplied descriptor
williamr@2:     * @return KErrOverflow if aData is the wrong size for data item or one of the system-wide error codes
williamr@2:     */      
williamr@2:     virtual TInt GetConditionValue( TDes8& aValue ) const = 0;        
williamr@2: 
williamr@2:     /**
williamr@2:     * Get condition value as reference.
williamr@2:     * 
williamr@2:     * @return Reference to condition value descriptor.
williamr@2:     */      
williamr@2:     virtual const TDesC8& ConditionValue() const = 0;        
williamr@2: 
williamr@2: public:
williamr@2:     /**
williamr@2:     * Default constructor. 
williamr@2:     */
williamr@2:     CSensrvChannelCondition();
williamr@2:     };
williamr@2: 
williamr@2: #endif //SENSRVCHANNELCONDITION_H
williamr@2: 
williamr@2: // End of File
williamr@2: 
williamr@2: