Line data    Source code

       1             : /**
       2             :  *
       3             :  *    Copyright (c) 2020 Project CHIP Authors
       4             :  *
       5             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6             :  *    you may not use this file except in compliance with the License.
       7             :  *    You may obtain a copy of the License at
       8             :  *
       9             :  *        http://www.apache.org/licenses/LICENSE-2.0
      10             :  *
      11             :  *    Unless required by applicable law or agreed to in writing, software
      12             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14             :  *    See the License for the specific language governing permissions and
      15             :  *    limitations under the License.
      16             :  */
      17             : 
      18             : #pragma once
      19             : 
      20             : #include <app/util/basic-types.h>
      21             : 
      22             : #include <cstdint>
      23             : 
      24             : /**
      25             :  * @brief Type for referring to ZCL attribute type
      26             :  */
      27             : typedef uint8_t EmberAfAttributeType;
      28             : 
      29             : /**
      30             :  * @brief Type for the attribute mask
      31             :  */
      32             : typedef uint8_t EmberAfAttributeMask;
      33             : 
      34             : /**
      35             :  * @brief Type for default values.
      36             :  *
      37             :  * Default value is either a value itself, if it is 2 bytes or less,
      38             :  * or a pointer to the value itself, if attribute type is longer than
      39             :  * 2 bytes.
      40             :  */
      41             : union EmberAfDefaultAttributeValue
      42             : {
      43             :     constexpr EmberAfDefaultAttributeValue(const uint8_t * ptr) : ptrToDefaultValue(ptr) {}
      44             :     constexpr EmberAfDefaultAttributeValue(uint16_t val) : defaultValue(val) {}
      45             : 
      46             :     /**
      47             :      * Points to data if size is more than 2 bytes.
      48             :      * If size is more than 2 bytes, and this value is NULL,
      49             :      * then the default value is all zeroes.
      50             :      */
      51             :     const uint8_t * ptrToDefaultValue;
      52             : 
      53             :     /**
      54             :      * Actual default value if the attribute size is 2 bytes or less.
      55             :      */
      56             :     uint16_t defaultValue;
      57             : };
      58             : 
      59             : /**
      60             :  * @brief Type describing the attribute default, min and max values.
      61             :  *
      62             :  * This struct is required if the attribute mask specifies that this
      63             :  * attribute has a known min and max values.
      64             :  */
      65             : typedef struct
      66             : {
      67             :     /**
      68             :      * Default value of the attribute.
      69             :      */
      70             :     EmberAfDefaultAttributeValue defaultValue;
      71             :     /**
      72             :      * Minimum allowed value
      73             :      */
      74             :     EmberAfDefaultAttributeValue minValue;
      75             :     /**
      76             :      * Maximum allowed value.
      77             :      */
      78             :     EmberAfDefaultAttributeValue maxValue;
      79             : } EmberAfAttributeMinMaxValue;
      80             : 
      81             : /**
      82             :  * @brief Union describing the attribute default/min/max values.
      83             :  */
      84             : union EmberAfDefaultOrMinMaxAttributeValue
      85             : {
      86             :     constexpr EmberAfDefaultOrMinMaxAttributeValue(const uint8_t * ptr) : ptrToDefaultValue(ptr) {}
      87             :     constexpr EmberAfDefaultOrMinMaxAttributeValue(uint32_t val) : defaultValue(val) {}
      88             :     constexpr EmberAfDefaultOrMinMaxAttributeValue(const EmberAfAttributeMinMaxValue * ptr) : ptrToMinMaxValue(ptr) {}
      89             : 
      90             :     /**
      91             :      * Points to data if the attribute type is a string or the size of the data is more than 4 bytes.
      92             :      * If the attribute type is a string or the data size is more than 4 bytes, and this value is NULL,
      93             :      * then the default value is all zeroes.
      94             :      */
      95             :     const uint8_t * ptrToDefaultValue;
      96             :     /**
      97             :      * Actual default value if the attribute is non string and size
      98             :      * is 4 bytes or less.
      99             :      */
     100             :     uint32_t defaultValue;
     101             :     /**
     102             :      * Points to the min max attribute value structure, if min/max is
     103             :      * supported for this attribute.
     104             :      */
     105             :     const EmberAfAttributeMinMaxValue * ptrToMinMaxValue;
     106             : };
     107             : 
     108             : // Attribute masks modify how attributes are used by the framework
     109             : //
     110             : // Attribute that has this mask is NOT read-only
     111             : #define ATTRIBUTE_MASK_WRITABLE (0x01)
     112             : // Attribute that has this mask is saved in non-volatile memory
     113             : #define ATTRIBUTE_MASK_NONVOLATILE (0x02)
     114             : // Alias until ZAP gets updated to output ATTRIBUTE_MASK_NONVOLATILE
     115             : #define ATTRIBUTE_MASK_TOKENIZE ATTRIBUTE_MASK_NONVOLATILE
     116             : // Attribute that has this mask has a min/max values
     117             : #define ATTRIBUTE_MASK_MIN_MAX (0x04)
     118             : // Attribute requires a timed interaction to write
     119             : #define ATTRIBUTE_MASK_MUST_USE_TIMED_WRITE (0x08)
     120             : // Attribute deferred to external storage
     121             : #define ATTRIBUTE_MASK_EXTERNAL_STORAGE (0x10)
     122             : // Attribute is singleton
     123             : #define ATTRIBUTE_MASK_SINGLETON (0x20)
     124             : // Attribute is nullable
     125             : #define ATTRIBUTE_MASK_NULLABLE (0x40)
     126             : 
     127             : /**
     128             :  * @brief Each attribute has it's metadata stored in such struct.
     129             :  *
     130             :  * There is only one of these per attribute across all endpoints.
     131             :  */
     132             : struct EmberAfAttributeMetadata
     133             : {
     134             :     /**
     135             :      * Pointer to the default value union. Actual value stored
     136             :      * depends on the mask.
     137             :      */
     138             :     EmberAfDefaultOrMinMaxAttributeValue defaultValue;
     139             : 
     140             :     /**
     141             :      * Attribute ID, according to ZCL specs.
     142             :      */
     143             :     chip::AttributeId attributeId;
     144             : 
     145             :     /**
     146             :      * Size of this attribute in bytes.
     147             :      */
     148             :     uint16_t size;
     149             : 
     150             :     /**
     151             :      * Attribute type, according to ZCL specs.
     152             :      */
     153             :     EmberAfAttributeType attributeType;
     154             : 
     155             :     /**
     156             :      * Attribute mask, tagging attribute with specific
     157             :      * functionality.
     158             :      */
     159             :     EmberAfAttributeMask mask;
     160             : 
     161             :     /**
     162             :      * Check whether this attribute is nullable.
     163             :      */
     164           0 :     bool IsNullable() const { return mask & ATTRIBUTE_MASK_NULLABLE; }
     165             : 
     166             :     /**
     167             :      * Check whether this attribute is readonly.
     168             :      */
     169        2434 :     bool IsReadOnly() const { return !(mask & ATTRIBUTE_MASK_WRITABLE); }
     170             : 
     171             :     /**
     172             :      * Check whether this attribute requires a timed write.
     173             :      */
     174        2434 :     bool MustUseTimedWrite() const { return mask & ATTRIBUTE_MASK_MUST_USE_TIMED_WRITE; }
     175             : 
     176             :     /**
     177             :      * Check whether this attibute's storage is managed outside the built-in
     178             :      * attribute store.
     179             :      */
     180           0 :     bool IsExternal() const { return mask & ATTRIBUTE_MASK_EXTERNAL_STORAGE; }
     181             : 
     182             :     /**
     183             :      * Check whether this is a "singleton" attribute, in the sense that it has a
     184             :      * single value across multiple instances of the cluster.  This is not
     185             :      * mutually exclusive with the attribute being external.
     186             :      */
     187           0 :     bool IsSingleton() const { return mask & ATTRIBUTE_MASK_SINGLETON; }
     188             : 
     189             :     /**
     190             :      * Check whether this attribute is automatically stored in non-volatile
     191             :      * memory.
     192             :      */
     193           0 :     bool IsAutomaticallyPersisted() const { return (mask & ATTRIBUTE_MASK_NONVOLATILE) && !IsExternal(); }
     194             : };
     195             : 
     196             : /** @brief Returns true if the given attribute type is a string. */
     197             : bool emberAfIsStringAttributeType(EmberAfAttributeType attributeType);
     198             : 
     199             : /** @brief Returns true if the given attribute type is a long string. */
     200             : bool emberAfIsLongStringAttributeType(EmberAfAttributeType attributeType);
     201             : 
     202             : /*
     203             :  * @brief Function that determines the length of a zigbee Cluster Library string
     204             :  *   (where the first byte is assumed to be the length).
     205             :  */
     206             : uint8_t emberAfStringLength(const uint8_t * buffer);
     207             : /*
     208             :  * @brief Function that determines the length of a zigbee Cluster Library long string.
     209             :  *   (where the first two bytes are assumed to be the length).
     210             :  */
     211             : uint16_t emberAfLongStringLength(const uint8_t * buffer);