src/app/MessageDef/AttributeDataElement.h

   1 /**
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2016-2017 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18 /**
  19  *    @file
  20  *      This file defines AttributeDataElement parser and builder in CHIP interaction model
  21  *
  22  */
  23
  24 #pragma once
  25
  26 #ifndef _CHIP_INTERACTION_MODEL_MESSAGE_DEF_ATTRIBUTE_DATA_ELEMENT_H
  27 #define _CHIP_INTERACTION_MODEL_MESSAGE_DEF_ATTRIBUTE_DATA_ELEMENT_H
  28
  29 #include "AttributePath.h"
  30 #include "Builder.h"
  31 #include "Parser.h"
  32 #include <core/CHIPCore.h>
  33 #include <core/CHIPTLV.h>
  34 #include <support/CodeUtils.h>
  35 #include <support/logging/CHIPLogging.h>
  36 #include <util/basic-types.h>
  37
  38 namespace chip {
  39 namespace app {
  40 namespace AttributeDataElement {
  41 enum
  42 {
  43     kCsTag_AttributePath       = 0,
  44     kCsTag_DataVersion         = 1,
  45     kCsTag_Data                = 2,
  46     kCsTag_MoreClusterDataFlag = 3,
  47 };
  48
  49 class Parser : public chip::app::Parser
  50 {
  51 public:
  52     /**
  53      *  @brief Initialize the parser object with TLVReader
  54      *
  55      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this AttributeDataElement
  56      *
  57      *  @return #CHIP_NO_ERROR on success
  58      */
  59     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
  60
  61     /**
  62      *  @brief Roughly verify the message is correctly formed
  63      *   1) all mandatory tags are present
  64      *   2) all elements have expected data type
  65      *   3) any tag can only appear once
  66      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
  67      *  @note The main use of this function is to print out what we're
  68      *    receiving during protocol development and debugging.
  69      *    The encoding rule has changed in IM encoding spec so this
  70      *    check is only "roughly" conformant now.
  71      *
  72      *  @return #CHIP_NO_ERROR on success
  73      */
  74     CHIP_ERROR CheckSchemaValidity() const;
  75
  76     /**
  77      *  @brief Get a TLVReader for the AttributePath. Next() must be called before accessing them.
  78      *
  79      *  @param [in] apAttributePath    A pointer to apAttributePath
  80      *
  81      *  @return #CHIP_NO_ERROR on success
  82      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Path
  83      *          #CHIP_END_OF_TLV if there is no such element
  84      */
  85     CHIP_ERROR GetAttributePath(AttributePath::Parser * const apAttributePath) const;
  86
  87     /**
  88      *  @brief Get a TLVReader for the DataVersion. Next() must be called before accessing them.
  89      *
  90      *  @param [in] apVersion    A pointer to apVersion
  91      *
  92      *  @return #CHIP_NO_ERROR on success
  93      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
  94      *          #CHIP_END_OF_TLV if there is no such element
  95      */
  96     CHIP_ERROR GetDataVersion(chip::DataVersion * const apVersion) const;
  97
  98     /**
  99      *  @brief Get a TLVReader for the Data. Next() must be called before accessing them.
 100      *
 101      *  @param [in] apReader    A pointer to apReader
 102      *
 103      *  @return #CHIP_NO_ERROR on success
 104      *          #CHIP_END_OF_TLV if there is no such element
 105      */
 106     CHIP_ERROR GetData(chip::TLV::TLVReader * const apReader) const;
 107
 108     /**
 109      *  @brief Check whether it need more cluster data Next() must be called before accessing them.
 110      *
 111      *  @param [in] apMoreClusterDataFlag    A pointer to apMoreClusterDataFlag
 112      *
 113      *  @return #CHIP_NO_ERROR on success
 114      *          #CHIP_END_OF_TLV if there is no such element
 115      */
 116     CHIP_ERROR GetMoreClusterDataFlag(bool * const apMoreClusterDataFlag) const;
 117
 118 protected:
 119     // A recursively callable function to parse a data element and pretty-print it.
 120     CHIP_ERROR ParseData(chip::TLV::TLVReader & aReader, int aDepth) const;
 121 };
 122
 123 class Builder : public chip::app::Builder
 124 {
 125 public:
 126     /**
 127      *  @brief Initialize a AttributeDataElement::Builder for writing into a TLV stream
 128      *
 129      *  @param [in] apWriter    A pointer to TLVWriter
 130      *
 131      *  @return #CHIP_NO_ERROR on success
 132      */
 133     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 134
 135     /**
 136      *  @brief Initialize a AttributePath::Builder for writing into the TLV stream
 137      *
 138      *  @return A reference to AttributePath::Builder
 139      */
 140     AttributePath::Builder & CreateAttributePathBuilder();
 141
 142     /**
 143      *  @brief Inject DataVersion into the TLV stream to indicate the numerical data version associated with
 144      *  the cluster that is referenced by the path.
 145      *
 146      *  @param [in] aDataVersion The boolean variable to indicate if AttributeDataElement has version
 147      *
 148      *  @return A reference to *this
 149      */
 150     AttributeDataElement::Builder & DataVersion(const chip::DataVersion aDataVersion);
 151
 152     /**
 153      *  @brief Inject aMoreClusterData into the TLV stream to indicate whether there is more cluster data.
 154      *  This is present when there is more than one AttributeDataElement as part of a logical Changeset,
 155      *  and the entire set needs to be applied ‘atomically’ on the receiver.
 156      *
 157      *  @param [in] aMoreClusterData The boolean variable to indicate if more cluster data is needed.
 158      *
 159      *  @return A reference to *this
 160      */
 161     AttributeDataElement::Builder & MoreClusterData(const bool aMoreClusterData);
 162
 163     /**
 164      *  @brief Mark the end of this AttributeDataElement
 165      *
 166      *  @return A reference to *this
 167      */
 168     AttributeDataElement::Builder & EndOfAttributeDataElement();
 169
 170 private:
 171     AttributePath::Builder mAttributePathBuilder;
 172 };
 173 }; // namespace AttributeDataElement
 174
 175 }; // namespace app
 176 }; // namespace chip
 177
 178 #endif // _CHIP_INTERACTION_MODEL_MESSAGE_DEF_ATTRIBUTE_DATA_ELEMENT_H