1 sensrvchannelcondition.h

     1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Channel condition object

    15 *

    16 */

    17 

    18 

    19 #ifndef SENSRVCHANNELCONDITION_H

    20 #define SENSRVCHANNELCONDITION_H

    21 

    22 //  INCLUDES

    23 #include <e32base.h>

    24 

    25 // FORWARD DECLARATIONS

    26 

    27 class CSensrvChannelCondition;

    28 

    29 // DATA TYPES

    30 

    31 /**

    32 * RPointerArray based channel condition list

    33 */

    34 typedef RPointerArray<CSensrvChannelCondition> RSensrvChannelConditionList;

    35 

    36 /**

    37 * Defines condition type.

    38 * 

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

    40 * 

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

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

    43 *   operator used in the condition.

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

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

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

    47 *   the range.

    48 *   A condition set that contains ESensrvRangeConditionLowerLimit condition must also contain

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

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

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

    52 *   is not valid for range condition.

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

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

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

    56 * 

    57 * @see CSensrvChannelCondition

    58 * @see TSensrvConditionOperator

    59 */

    60 enum TSensrvConditionType

    61     {

    62     /** Standalone condition which has a limit */

    63     ESensrvSingleLimitCondition = 0,

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

    65     ESensrvRangeConditionLowerLimit,

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

    67     ESensrvRangeConditionUpperLimit,

    68     /** Standalone condition for binary operations */

    69     ESensrvBinaryCondition

    70     };

    71 

    72 /*

    73 * Defines condition operator

    74 * 

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

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

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

    78 * 

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

    80 *   not a valid operator for a range condition.

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

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

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

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

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

    86 *   not a valid operator for a binary condition.

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

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

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

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

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

    92 * 

    93 *   Example: 

    94 *   Condition value: 01101101

    95 *   Data value:      10001010

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

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

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

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

   100 *   or range conditions.

   101 *   Example: 

   102 *   Condition value: 01101101

   103 *   Data value:      10001010

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

   105 * 

   106 * @see CSensrvChannelCondition

   107 * @see TSensrvConditionType

   108 */

   109 enum TSensrvConditionOperator

   110     {

   111     ESensrvOperatorEquals = 0,

   112     ESensrvOperatorGreaterThan,

   113     ESensrvOperatorGreaterThanOrEquals,

   114     ESensrvOperatorLessThan,

   115     ESensrvOperatorLessThanOrEquals,

   116     ESensrvOperatorBinaryAnd,

   117     ESensrvOperatorBinaryAll    

   118     };

   119 

   120 // CLASS DECLARATION

   121 

   122 /**

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

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

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

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

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

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

   129 * condition. 

   130 * 

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

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

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

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

   135 * CSensrvChannelConditionSet::AddChannelConditionL() leaves with KErrArgument.  

   136 * 

   137 * @see CSensrvChannelConditionSet

   138 * @see TSensrvConditionType

   139 * @see TSensrvConditionOperator

   140 * @lib sensrvutil.lib

   141 * @since S60 5.0

   142 */

   143 NONSHARABLE_CLASS( CSensrvChannelCondition ): public CBase

   144     {

   145 public:

   146     /**

   147     * Two-phase constructor

   148     * 

   149     * @param   aConditionType Defines the type of the condition

   150     * @param   aConditionOperator Defines the operator used in the condition

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

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

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

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

   155     *        the channel specific header defining the channel.

   156     * @return Pointer to created object

   157     * @leave  KErrNoMemory

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

   159     * @leave  One of the system-wide error codes

   160     */  

   161     IMPORT_C static CSensrvChannelCondition* NewL

   162                 ( TInt aConditionType, 

   163                   TInt aConditionOperator,

   164                   TInt aItemIndex,

   165                   TDesC8& aValue );

   166                   

   167     /**

   168     * Two-phase constructor

   169     * 

   170     * @param   aConditionType Defines the type of the condition

   171     * @param   aConditionOperator Defines the operator used in the condition

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

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

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

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

   176     *         the channel specific header defining the channel.

   177     * @return Pointer to created object

   178     * @leave  KErrNoMemory

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

   180     * @leave  One of the system-wide error codes

   181     */  

   182     IMPORT_C static CSensrvChannelCondition* NewLC

   183                 ( TInt aConditionType, 

   184                   TInt aConditionOperator,

   185                   TInt aItemIndex,

   186                   TDesC8& aValue );

   187 public:  

   188     

   189     /**

   190     * Get condition type

   191     *  

   192     * @return Condition Type

   193     */    

   194     virtual TInt ConditionType() const = 0;

   195 

   196     /**

   197     * Get condition operator

   198     *

   199     * @return TInt Condition operator

   200     */      

   201     virtual TInt ConditionOperator() const = 0;

   202   

   203     /**

   204     * Get condition item index

   205     *

   206     * @return TInt Condition item index

   207     */      

   208     virtual TInt ConditionItemIndex() const = 0;

   209 

   210     /**

   211     * Get condition value.

   212     *

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

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

   215     */      

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

   217 

   218     /**

   219     * Get condition value as reference.

   220     * 

   221     * @return Reference to condition value descriptor.

   222     */      

   223     virtual const TDesC8& ConditionValue() const = 0;        

   224 

   225 public:

   226     /**

   227     * Default constructor. 

   228     */

   229     CSensrvChannelCondition();

   230     };

   231 

   232 #endif //SENSRVCHANNELCONDITION_H

   233 

   234 // End of File

   235 

   236