src/app/MessageDef.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 CHIP interaction model message parsers and encoders
  21  *      Interaction model profile.
  22  *
  23  */
  24
  25 #pragma once
  26
  27 #ifndef _CHIP_INTERACTION_MODEL_MESSAGE_DEF_H
  28 #define _CHIP_INTERACTION_MODEL_MESSAGE_DEF_H
  29
  30 #include <core/CHIPCore.h>
  31 #include <core/CHIPTLV.h>
  32 #include <support/CodeUtils.h>
  33 #include <support/logging/CHIPLogging.h>
  34 #include <util/basic-types.h>
  35
  36 namespace chip {
  37 namespace app {
  38 /**
  39  *  @brief
  40  *    The CHIP interaction model message types.
  41  *
  42  *  These values are called out in CHIP Interaction Model: Encoding Specification
  43  *
  44  */
  45 enum
  46 {
  47     kMsgType_SubscribeRequest      = 0x01,
  48     kMsgType_ReadRequest           = 0x02,
  49     kMsgType_ReportData            = 0x03,
  50     kMsgType_WriteRequest          = 0x04,
  51     kMsgType_WriteResponse         = 0x05,
  52     kMsgType_InvokeCommandRequest  = 0x06,
  53     kMsgType_InvokeCommandResponse = 0x07,
  54 };
  55
  56 class Parser
  57 {
  58 public:
  59     /**
  60      *  @brief Initialize the Builder object with TLVReader and ContainerType
  61      *
  62      *  @param [in] aReader TLVReader
  63      *  @param [in] aOuterContainerType outer container type
  64      *
  65      */
  66     void Init(const chip::TLV::TLVReader & aReader, chip::TLV::TLVType aOuterContainerType);
  67
  68     /**
  69      *  @brief Initialize a TLVReader to point to the beginning of any tagged element in this request
  70      *
  71      *  @param [in]  aTagToFind Tag to find in the request
  72      *  @param [out] apReader   A pointer to TLVReader, which will be initialized at the specified TLV element
  73      *                          on success
  74      *
  75      *  @return #CHIP_NO_ERROR on success
  76      */
  77     CHIP_ERROR GetReaderOnTag(const uint64_t aTagToFind, chip::TLV::TLVReader * const apReader) const;
  78
  79     /**
  80      *  @brief Get the TLV Reader
  81      *
  82      *  @param [in] aReader A pointer to a TLVReader
  83      *
  84      */
  85     void GetReader(chip::TLV::TLVReader * const apReader);
  86
  87 protected:
  88     chip::TLV::TLVReader mReader;
  89     chip::TLV::TLVType mOuterContainerType;
  90     Parser();
  91
  92     template <typename T>
  93     CHIP_ERROR GetUnsignedInteger(const uint8_t aContextTag, T * const apLValue) const;
  94
  95     template <typename T>
  96     CHIP_ERROR GetSimpleValue(const uint8_t aContextTag, const chip::TLV::TLVType aTLVType, T * const apLValue) const;
  97 };
  98
  99 class ListParser : public chip::app::Parser
 100 {
 101 protected:
 102     ListParser();
 103
 104 public:
 105     /**
 106      *  @brief Initialize the parser object with TLVReader
 107      *
 108      *  @param [in] aReader A pointer to a TLVReader, which should be on the element of the array element
 109      *
 110      *  @return #CHIP_NO_ERROR on success
 111      */
 112     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
 113
 114     /**
 115      *  @brief Initialize the parser object with TLVReader if context tag exists
 116      *
 117      *  @param [in] aReader A pointer to a TLVReader, which should be on the element of the array element
 118      *  @param [in] aContextTagToFind A context tag it tries to find
 119      *
 120      *  @return #CHIP_NO_ERROR on success
 121      */
 122     CHIP_ERROR InitIfPresent(const chip::TLV::TLVReader & aReader, const uint8_t aContextTagToFind);
 123
 124     /**
 125      *  @brief Iterate to next element
 126      *
 127      *  @return #CHIP_NO_ERROR on success
 128      */
 129     CHIP_ERROR Next();
 130 };
 131
 132 class Builder
 133 {
 134 public:
 135     /**
 136      *  @brief Initialize the Builder object with TLVWriter and ContainerType
 137      *
 138      *  @param [in] apWriter A pointer to a TLVWriter
 139      *  @param [in] aOuterContainerType outer container type
 140      *
 141      */
 142     void Init(chip::TLV::TLVWriter * const apWriter, chip::TLV::TLVType aOuterContainerType);
 143
 144     /**
 145      *  @brief Reset the Error
 146      *
 147      */
 148     void ResetError();
 149
 150     /**
 151      *  @brief Reset the Error with particular aErr.
 152      *  @param [in] aErr the Error it would be reset with
 153      *
 154      */
 155     void ResetError(CHIP_ERROR aErr);
 156
 157     /**
 158      *  @brief Get current error
 159      *
 160      *  @return #CHIP_NO_ERROR on success
 161      */
 162     CHIP_ERROR GetError() const { return mError; };
 163
 164     /**
 165      *  @brief Get TLV Writer
 166      *
 167      *  @return #Pointer to the TLVWriter
 168      */
 169     chip::TLV::TLVWriter * GetWriter() { return mpWriter; };
 170
 171 protected:
 172     CHIP_ERROR mError;
 173     chip::TLV::TLVWriter * mpWriter;
 174     chip::TLV::TLVType mOuterContainerType;
 175
 176     Builder();
 177     void EndOfContainer();
 178
 179     CHIP_ERROR InitAnonymousStructure(chip::TLV::TLVWriter * const apWriter);
 180 };
 181
 182 class ListBuilder : public chip::app::Builder
 183 {
 184 protected:
 185     ListBuilder();
 186
 187 public:
 188     /**
 189      * Init the TLV array container with an particular context tag.
 190      * Required to implement arrays of arrays, and to test ListBuilder.
 191      *
 192      * @param[in]   apWriter    Pointer to the TLVWriter that is encoding the message.
 193      * @param[in]   aContextTagToUse    A contextTag to use.
 194      *
 195      * @return                  CHIP_ERROR codes returned by Chip::TLV objects.
 196      */
 197
 198     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter, const uint8_t aContextTagToUse);
 199     /**
 200      * Init the TLV array container with an anonymous tag.
 201      * Required to implement arrays of arrays, and to test ListBuilder.
 202      *
 203      * @param[in]   apWriter    Pointer to the TLVWriter that is encoding the message.
 204      *
 205      * @return                  CHIP_ERROR codes returned by Chip::TLV objects.
 206      */
 207     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 208 };
 209
 210 namespace AttributePath {
 211 enum
 212 {
 213     kCsTag_NodeId              = 0,
 214     kCsTag_EndpointId          = 1,
 215     kCsTag_NamespacedClusterId = 2,
 216     kCsTag_FieldId             = 3,
 217     kCsTag_ListIndex           = 4,
 218 };
 219
 220 class Parser : public chip::app::Parser
 221 {
 222 public:
 223     /**
 224      *  @brief Initialize the parser object with TLVReader
 225      *
 226      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this AttributePath
 227      *
 228      *  @return #CHIP_NO_ERROR on success
 229      */
 230     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
 231
 232     /**
 233      *  @brief Roughly verify the message is correctly formed
 234      *   1) all mandatory tags are present
 235      *   2) all elements have expected data type
 236      *   3) any tag can only appear once
 237      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
 238      *  @note The main use of this function is to print out what we're
 239      *    receiving during protocol development and debugging.
 240      *    The encoding rule has changed in IM encoding spec so this
 241      *    check is only "roughly" conformant now.
 242      *
 243      *  @return #CHIP_NO_ERROR on success
 244      */
 245     CHIP_ERROR CheckSchemaValidity() const;
 246
 247     /**
 248      *  @brief Get a TLVReader for the NodeId. Next() must be called before accessing them.
 249      *
 250      *  @param [in] apNodeId    A pointer to apNodeId
 251      *
 252      *  @return #CHIP_NO_ERROR on success
 253      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 254      *          #CHIP_END_OF_TLV if there is no such element
 255      */
 256     CHIP_ERROR GetNodeId(chip::NodeId * const apNodeId) const;
 257
 258     /**
 259      *  @brief Get a TLVReader for the EndpointId. Next() must be called before accessing them.
 260      *
 261      *  @param [in] apEndpointId    A pointer to apEndpointId
 262      *
 263      *  @return #CHIP_NO_ERROR on success
 264      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 265      *          #CHIP_END_OF_TLV if there is no such element
 266      */
 267     CHIP_ERROR GetEndpointId(chip::EndpointId * const apEndpointId) const;
 268
 269     /**
 270      *  @brief Get a TLVReader for the ClusterId. Next() must be called before accessing them.
 271      *
 272      *  @param [in] apClusterId    A pointer to apClusterId
 273      *
 274      *  @return #CHIP_NO_ERROR on success
 275      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 276      *          #CHIP_END_OF_TLV if there is no such element
 277      */
 278     CHIP_ERROR GetNamespacedClusterId(chip::ClusterId * const apClusterId) const;
 279
 280     /**
 281      *  @brief Get a TLVReader for the FieldId. Next() must be called before accessing them.
 282      *
 283      *  @param [in] apFieldId    A pointer to apFieldId
 284      *
 285      *  @return #CHIP_NO_ERROR on success
 286      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 287      *          #CHIP_END_OF_TLV if there is no such element
 288      */
 289     CHIP_ERROR GetFieldId(uint8_t * const apFieldId) const;
 290
 291     /**
 292      *  @brief Get a TLVReader for the ListIndex. Next() must be called before accessing them.
 293      *
 294      *  @param [in] apListIndex    A pointer to apListIndex
 295      *
 296      *  @return #CHIP_NO_ERROR on success
 297      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 298      *          #CHIP_END_OF_TLV if there is no such element
 299      */
 300     CHIP_ERROR GetListIndex(uint16_t * const apListIndex) const;
 301 };
 302
 303 class Builder : public chip::app::Builder
 304 {
 305 public:
 306     /**
 307      *  @brief Initialize a AttributePath::Builder for writing into a TLV stream
 308      *
 309      *  @param [in] apWriter    A pointer to TLVWriter
 310      *
 311      *  @return #CHIP_NO_ERROR on success
 312      */
 313     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 314
 315     /**
 316      * Init the AttributePath container with an particular context tag.
 317      * Required to implement arrays of arrays, and to test ListBuilder.
 318      *
 319      * @param[in]   apWriter    Pointer to the TLVWriter that is encoding the message.
 320      * @param[in]   aContextTagToUse    A contextTag to use.
 321      *
 322      * @return                  CHIP_ERROR codes returned by Chip::TLV objects.
 323      */
 324     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter, const uint8_t aContextTagToUse);
 325
 326     /**
 327      *  @brief Inject NodeId into the TLV stream.
 328      *
 329      *  @param [in] aNodeId NodeId for this attribute path
 330      *
 331      *  @return A reference to *this
 332      */
 333     AttributePath::Builder & NodeId(const chip::NodeId aNodeId);
 334
 335     /**
 336      *  @brief Inject EndpointId into the TLV stream.
 337      *
 338      *  @param [in] aEndpointId NodeId for this attribute path
 339      *
 340      *  @return A reference to *this
 341      */
 342     AttributePath::Builder & EndpointId(const chip::EndpointId aEndpointId);
 343
 344     /**
 345      *  @brief Inject NamespacedClusterId into the TLV stream.
 346      *
 347      *  @param [in] aNamespacedClusterId NamespacedClusterId for this attribute path
 348      *
 349      *  @return A reference to *this
 350      */
 351     AttributePath::Builder & NamespacedClusterId(const chip::ClusterId aNamespacedClusterId);
 352
 353     /**
 354      *  @brief Inject FieldId into the TLV stream.
 355      *
 356      *  @param [in] aFieldId FieldId for this attribute path
 357      *
 358      *  @return A reference to *this
 359      */
 360     AttributePath::Builder & FieldId(const uint8_t aFieldId);
 361
 362     /**
 363      *  @brief Inject NodeId into the TLV stream.
 364      *
 365      *  @param [in] aListIndex NodeId for this attribute path
 366      *
 367      *  @return A reference to *this
 368      */
 369     AttributePath::Builder & ListIndex(const uint16_t aListIndex);
 370
 371     /**
 372      *  @brief Mark the end of this AttributePath
 373      *
 374      *  @return A reference to *this
 375      */
 376     AttributePath::Builder & EndOfAttributePath();
 377
 378 private:
 379     CHIP_ERROR _Init(chip::TLV::TLVWriter * const apWriter, const uint64_t aTag);
 380 };
 381
 382 }; // namespace AttributePath
 383
 384 namespace AttributePathList {
 385 class Parser : public ListParser
 386 {
 387 public:
 388     /**
 389      *  @brief Roughly verify the message is correctly formed
 390      *   1) all mandatory tags are present
 391      *   2) all elements have expected data type
 392      *   3) any tag can only appear once
 393      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
 394      *  @note The main use of this function is to print out what we're
 395      *    receiving during protocol development and debugging.
 396      *    The encoding rule has changed in IM encoding spec so this
 397      *    check is only "roughly" conformant now.
 398      *
 399      *  @return #CHIP_NO_ERROR on success
 400      */
 401     CHIP_ERROR CheckSchemaValidity() const;
 402 };
 403
 404 class Builder : public ListBuilder
 405 {
 406 public:
 407     /**
 408      *  @brief Initialize a AttributePath::Builder for writing into the TLV stream
 409      *
 410      *  @return A reference to AttributePath::Builder
 411      */
 412     AttributePath::Builder & CreateAttributePathBuilder();
 413
 414     /**
 415      *  @brief Mark the end of this AttributePath
 416      *
 417      *  @return A reference to *this
 418      */
 419     AttributePathList::Builder & EndOfAttributePathList();
 420
 421 private:
 422     AttributePath::Builder mAttributePathBuilder;
 423 };
 424 }; // namespace AttributePathList
 425
 426 namespace EventPath {
 427 enum
 428 {
 429     kCsTag_NodeId              = 0,
 430     kCsTag_EndpointId          = 1,
 431     kCsTag_NamespacedClusterId = 2,
 432     kCsTag_EventId             = 3,
 433 };
 434
 435 class Parser : public chip::app::Parser
 436 {
 437 public:
 438     /**
 439      *  @brief Initialize the parser object with TLVReader
 440      *
 441      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this EventPath
 442      *
 443      *  @return #CHIP_NO_ERROR on success
 444      */
 445     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
 446
 447     /**
 448      *  @brief Roughly verify the message is correctly formed
 449      *   1) all mandatory tags are present
 450      *   2) all elements have expected data type
 451      *   3) any tag can only appear once
 452      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
 453      *  @note The main use of this function is to print out what we're
 454      *    receiving during protocol development and debugging.
 455      *    The encoding rule has changed in IM encoding spec so this
 456      *    check is only "roughly" conformant now.
 457      *
 458      *  @return #CHIP_NO_ERROR on success
 459      */
 460     CHIP_ERROR CheckSchemaValidity() const;
 461
 462     /**
 463      *  @brief Get a TLVReader for the NodeId. Next() must be called before accessing them.
 464      *
 465      *  @param [in] apNodeId    A pointer to apNodeId
 466      *
 467      *  @return #CHIP_NO_ERROR on success
 468      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 469      *          #CHIP_END_OF_TLV if there is no such element
 470      */
 471     CHIP_ERROR GetNodeId(chip::NodeId * const apNodeId) const;
 472
 473     /**
 474      *  @brief Get a TLVReader for the EndpointId. Next() must be called before accessing them.
 475      *
 476      *  @param [in] apEndpointId    A pointer to apEndpointId
 477      *
 478      *  @return #CHIP_NO_ERROR on success
 479      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 480      *          #CHIP_END_OF_TLV if there is no such element
 481      */
 482     CHIP_ERROR GetEndpointId(chip::EndpointId * const apEndpointId) const;
 483
 484     /**
 485      *  @brief Get a TLVReader for the NamespacedClusterId. Next() must be called before accessing them.
 486      *
 487      *  @param [in] apNamespacedClusterId    A pointer to apNamespacedClusterId
 488      *
 489      *  @return #CHIP_NO_ERROR on success
 490      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 491      *          #CHIP_END_OF_TLV if there is no such element
 492      */
 493     CHIP_ERROR GetNamespacedClusterId(chip::ClusterId * const apNamespacedClusterId) const;
 494
 495     /**
 496      *  @brief Get a TLVReader for the EventId. Next() must be called before accessing them.
 497      *
 498      *  @param [in] apEventId    A pointer to apEventId
 499      *
 500      *  @return #CHIP_NO_ERROR on success
 501      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 502      *          #CHIP_END_OF_TLV if there is no such element
 503      */
 504     CHIP_ERROR GetEventId(chip::EventId * const apEventId) const;
 505 };
 506
 507 class Builder : public chip::app::Builder
 508 {
 509 public:
 510     /**
 511      *  @brief Initialize a EventPath::Builder for writing into a TLV stream
 512      *
 513      *  @param [in] apWriter    A pointer to TLVWriter
 514      *
 515      *  @return #CHIP_NO_ERROR on success
 516      */
 517     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 518
 519     /**
 520      * Init the EventPath container with an particular context tag.
 521      * Required to implement arrays of arrays, and to test ListBuilder.
 522      *
 523      * @param[in]   apWriter    Pointer to the TLVWriter that is encoding the message.
 524      * @param[in]   aContextTagToUse    A contextTag to use.
 525      *
 526      * @return                  CHIP_ERROR codes returned by Chip::TLV objects.
 527      */
 528     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter, const uint8_t aContextTagToUse);
 529
 530     /**
 531      *  @brief Inject NodeId into the TLV stream.
 532      *
 533      *  @param [in] aNodeId NodeId for this event path
 534      *
 535      *  @return A reference to *this
 536      */
 537     EventPath::Builder & NodeId(const chip::NodeId aNodeId);
 538
 539     /**
 540      *  @brief Inject EndpointId into the TLV stream.
 541      *
 542      *  @param [in] aEndpointId EndpointId for this eevent path
 543      *
 544      *  @return A reference to *this
 545      */
 546     EventPath::Builder & EndpointId(const chip::EndpointId aEndpointId);
 547
 548     /**
 549      *  @brief Inject NamespacedClusterId into the TLV stream.
 550      *
 551      *  @param [in] aNamespacedClusterId NamespacedClusterId for this event path
 552      *
 553      *  @return A reference to *this
 554      */
 555     EventPath::Builder & NamespacedClusterId(const chip::ClusterId aNamespacedClusterId);
 556
 557     /**
 558      *  @brief Inject EventId into the TLV stream.
 559      *
 560      *  @param [in] aEventId NamespacedClusterId for this event path
 561      *
 562      *  @return A reference to *this
 563      */
 564     EventPath::Builder & EventId(const chip::EventId aEventId);
 565
 566     /**
 567      *  @brief Mark the end of this EventPath
 568      *
 569      *  @return A reference to *this
 570      */
 571     EventPath::Builder & EndOfEventPath();
 572
 573 private:
 574     CHIP_ERROR _Init(chip::TLV::TLVWriter * const apWriter, const uint64_t aTag);
 575 };
 576 }; // namespace EventPath
 577
 578 namespace EventPathList {
 579 class Parser : public ListParser
 580 {
 581 public:
 582     /**
 583      *  @brief Roughly verify the message is correctly formed
 584      *   1) all mandatory tags are present
 585      *   2) all elements have expected data type
 586      *   3) any tag can only appear once
 587      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
 588      *  @note The main use of this function is to print out what we're
 589      *    receiving during protocol development and debugging.
 590      *    The encoding rule has changed in IM encoding spec so this
 591      *    check is only "roughly" conformant now.
 592      *
 593      *  @return #CHIP_NO_ERROR on success
 594      */
 595     CHIP_ERROR CheckSchemaValidity() const;
 596 };
 597
 598 class Builder : public ListBuilder
 599 {
 600 public:
 601     /**
 602      *  @brief Initialize a EventPath::Builder for writing into the TLV stream
 603      *
 604      *  @return A reference to EventPath::Builder
 605      */
 606     EventPath::Builder & CreateEventPathBuilder();
 607
 608     /**
 609      *  @brief Mark the end of this EventPathList
 610      *
 611      *  @return A reference to *this
 612      */
 613     EventPathList::Builder & EndOfEventPathList();
 614
 615 private:
 616     EventPath::Builder mEventPathBuilder;
 617 };
 618 }; // namespace EventPathList
 619
 620 namespace CommandPath {
 621 enum
 622 {
 623     kCsTag_EndpointId          = 0,
 624     kCsTag_GroupId             = 1,
 625     kCsTag_NamespacedClusterId = 2,
 626     kCsTag_CommandId           = 3,
 627 };
 628
 629 class Parser : public chip::app::Parser
 630 {
 631 public:
 632     /**
 633      *  @brief Initialize the parser object with TLVReader
 634      *
 635      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this CommandPath
 636      *
 637      *  @return #CHIP_NO_ERROR on success
 638      */
 639     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
 640
 641     /**
 642      *  @brief Roughly verify the message is correctly formed
 643      *   1) all mandatory tags are present
 644      *   2) all elements have expected data type
 645      *   3) any tag can only appear once
 646      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
 647      *  @note The main use of this function is to print out what we're
 648      *    receiving during protocol development and debugging.
 649      *    The encoding rule has changed in IM encoding spec so this
 650      *    check is only "roughly" conformant now.
 651      *
 652      *  @return #CHIP_NO_ERROR on success
 653      */
 654     CHIP_ERROR CheckSchemaValidity() const;
 655
 656     /**
 657      *  @brief Get a TLVReader for the EndpointId. Next() must be called before accessing them.
 658      *
 659      *  @param [in] apEndpointId    A pointer to apEndpointId
 660      *
 661      *  @return #CHIP_NO_ERROR on success
 662      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 663      *          #CHIP_END_OF_TLV if there is no such element
 664      */
 665     CHIP_ERROR GetEndpointId(chip::EndpointId * const apEndpointId) const;
 666
 667     /**
 668      *  @brief Get a TLVReader for the GroupId. Next() must be called before accessing them.
 669      *
 670      *  @param [in] apGroupId    A pointer to apGroupId
 671      *
 672      *  @return #CHIP_NO_ERROR on success
 673      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 674      *          #CHIP_END_OF_TLV if there is no such element
 675      */
 676     CHIP_ERROR GetGroupId(chip::GroupId * const apGroupId) const;
 677
 678     /**
 679      *  @brief Get a TLVReader for the NamespacedClusterId. Next() must be called before accessing them.
 680      *
 681      *  @param [in] apEndpointId    A pointer to NamespacedClusterId
 682      *
 683      *  @return #CHIP_NO_ERROR on success
 684      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 685      *          #CHIP_END_OF_TLV if there is no such element
 686      */
 687     CHIP_ERROR GetNamespacedClusterId(chip::ClusterId * const apNamespacedClusterId) const;
 688
 689     /**
 690      *  @brief Get a TLVReader for the CommandId. Next() must be called before accessing them.
 691      *
 692      *  @param [in] apEndpointId    A pointer to CommandId
 693      *
 694      *  @return #CHIP_NO_ERROR on success
 695      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 696      *          #CHIP_END_OF_TLV if there is no such element
 697      */
 698     CHIP_ERROR GetCommandId(chip::CommandId * const apCommandId) const;
 699 };
 700
 701 class Builder : public chip::app::Builder
 702 {
 703 public:
 704     /**
 705      *  @brief Initialize a CommandPath::Builder for writing into a TLV stream
 706      *
 707      *  @param [in] apWriter    A pointer to TLVWriter
 708      *
 709      *  @return #CHIP_NO_ERROR on success
 710      */
 711     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 712
 713     /**
 714      * Init the CommandPath container with an particular context tag.
 715      * Required to implement arrays of arrays, and to test ListBuilder.
 716      *
 717      * @param[in]   apWriter    Pointer to the TLVWriter that is encoding the message.
 718      * @param[in]   aContextTagToUse    A contextTag to use.
 719      *
 720      * @return                  CHIP_ERROR codes returned by Chip::TLV objects.
 721      */
 722     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter, const uint8_t aContextTagToUse);
 723
 724     /**
 725      *  @brief Inject EndpointId into the TLV stream to indicate the endpointId referenced by the path.
 726      *
 727      *  @param [in] aEndpointId refer to the ID of the endpoint as described in the descriptor cluster.
 728      *
 729      *  @return A reference to *this
 730      */
 731     CommandPath::Builder & EndpointId(const chip::EndpointId aEndpointId);
 732
 733     /**
 734      *  @brief Inject GroupId into the TLV stream to indicate the GroupId referenced by the path.
 735      *
 736      *  @param [in] aGroupId  Group Id for this Command path
 737      *
 738      *  @return A reference to *this
 739      */
 740     CommandPath::Builder & GroupId(const chip::GroupId aGroupId);
 741
 742     /**
 743      *  @brief Inject NamespacedClusterId into the TLV stream.
 744      *
 745      *  @param [in] aNamespacedClusterId NamespacedClusterId for this command path
 746      *
 747      *  @return A reference to *this
 748      */
 749     CommandPath::Builder & NamespacedClusterId(const chip::ClusterId aNamespacedClusterId);
 750
 751     /**
 752      *  @brief Inject CommandId into the TLV stream
 753      *
 754      *  @param [in] aCommandId Command Id for NamespacedClusterId for this command path
 755      *
 756      *  @return A reference to *this
 757      */
 758     CommandPath::Builder & CommandId(const chip::CommandId aCommandId);
 759
 760     /**
 761      *  @brief Mark the end of this CommandPath
 762      *
 763      *  @return A reference to *this
 764      */
 765     CommandPath::Builder & EndOfCommandPath();
 766
 767 private:
 768     CHIP_ERROR _Init(chip::TLV::TLVWriter * const apWriter, const uint64_t aTag);
 769 };
 770 }; // namespace CommandPath
 771
 772 namespace EventDataElement {
 773 enum
 774 {
 775     kCsTag_EventPath            = 0,
 776     kCsTag_ImportanceLevel      = 1,
 777     kCsTag_Number               = 2,
 778     kCsTag_UTCTimestamp         = 3,
 779     kCsTag_SystemTimestamp      = 4,
 780     kCsTag_DeltaUTCTimestamp    = 5,
 781     kCsTag_DeltaSystemTimestamp = 6,
 782     kCsTag_Data                 = 7,
 783 };
 784
 785 class Parser : public chip::app::Parser
 786 {
 787 public:
 788     /**
 789      *  @brief Initialize the parser object with TLVReader
 790      *
 791      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this EventDataElement
 792      *
 793      *  @return #CHIP_NO_ERROR on success
 794      */
 795     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
 796
 797     /**
 798      *  @brief Roughly verify the message is correctly formed
 799      *   1) all mandatory tags are present
 800      *   2) all elements have expected data type
 801      *   3) any tag can only appear once
 802      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
 803      *  @note The main use of this function is to print out what we're
 804      *    receiving during protocol development and debugging.
 805      *    The encoding rule has changed in IM encoding spec so this
 806      *    check is only "roughly" conformant now.
 807      *
 808      *  @return #CHIP_NO_ERROR on success
 809      */
 810     CHIP_ERROR CheckSchemaValidity() const;
 811
 812     /**
 813      *  @brief Get a TLVReader for the EventPath. Next() must be called before accessing them.
 814      *
 815      *  @param [in] apEventPath    A pointer to apEventPath
 816      *
 817      *  @return #CHIP_NO_ERROR on success
 818      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Path
 819      *          #CHIP_END_OF_TLV if there is no such element
 820      */
 821     CHIP_ERROR GetEventPath(EventPath::Parser * const apEventPath);
 822
 823     /**
 824      *  @brief Get a TLVReader for the Number. Next() must be called before accessing them.
 825      *
 826      *  @param [in] apImportanceLevel    A pointer to apImportanceLevel
 827      *
 828      *  @return #CHIP_NO_ERROR on success
 829      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 830      *          #CHIP_END_OF_TLV if there is no such element
 831      */
 832     CHIP_ERROR GetImportanceLevel(uint8_t * const apImportanceLevel);
 833
 834     /**
 835      *  @brief Get a TLVReader for the Number. Next() must be called before accessing them.
 836      *
 837      *  @param [in] apNumber    A pointer to apNumber
 838      *
 839      *  @return #CHIP_NO_ERROR on success
 840      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 841      *          #CHIP_END_OF_TLV if there is no such element
 842      */
 843     CHIP_ERROR GetNumber(uint64_t * const apNumber);
 844
 845     /**
 846      *  @brief Get a TLVReader for the UTCTimestamp. Next() must be called before accessing them.
 847      *
 848      *  @param [in] apUTCTimestamp    A pointer to apUTCTimestamp
 849      *
 850      *  @return #CHIP_NO_ERROR on success
 851      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 852      *          #CHIP_END_OF_TLV if there is no such element
 853      */
 854     CHIP_ERROR GetUTCTimestamp(uint64_t * const apUTCTimestamp);
 855
 856     /**
 857      *  @brief Get a TLVReader for the SystemTimestamp. Next() must be called before accessing them.
 858      *
 859      *  @param [in] apSystemTimestamp    A pointer to apSystemTimestamp
 860      *
 861      *  @return #CHIP_NO_ERROR on success
 862      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 863      *          #CHIP_END_OF_TLV if there is no such element
 864      */
 865     CHIP_ERROR GetSystemTimestamp(uint64_t * const apSystemTimestamp);
 866
 867     /**
 868      *  @brief Get a TLVReader for the DeltaUTCTime. Next() must be called before accessing them.
 869      *
 870      *  @param [in] apDeltaUTCTimestamp   A pointer to apDeltaUTCTime
 871      *
 872      *  @return #CHIP_NO_ERROR on success
 873      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 874      *          #CHIP_END_OF_TLV if there is no such element
 875      */
 876     CHIP_ERROR GetDeltaUTCTime(uint64_t * const apDeltaUTCTime);
 877
 878     /**
 879      *  @brief Get a TLVReader for the DeltaSystemTime. Next() must be called before accessing them.
 880      *
 881      *  @param [in] apDeltaSystemTimestamp   A pointer to apDeltaSystemTime
 882      *
 883      *  @return #CHIP_NO_ERROR on success
 884      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
 885      *          #CHIP_END_OF_TLV if there is no such element
 886      */
 887     CHIP_ERROR GetDeltaSystemTime(uint64_t * const apDeltaSystemTime);
 888
 889     /**
 890      *  @brief Get a TLVReader for the Data. Next() must be called before accessing them.
 891      *
 892      *  @param [in] apReader    A pointer to apReader
 893      *
 894      *  @return #CHIP_NO_ERROR on success
 895      *          #CHIP_END_OF_TLV if there is no such element
 896      */
 897     CHIP_ERROR GetData(chip::TLV::TLVReader * const apReader) const;
 898
 899 protected:
 900     // A recursively callable function to parse a data element and pretty-print it.
 901     CHIP_ERROR ParseData(chip::TLV::TLVReader & aReader, int aDepth) const;
 902 };
 903
 904 class Builder : public chip::app::Builder
 905 {
 906 public:
 907     /**
 908      *  @brief Initialize a EventDataElement::Builder for writing into a TLV stream
 909      *
 910      *  @param [in] apWriter    A pointer to TLVWriter
 911      *
 912      *  @return #CHIP_NO_ERROR on success
 913      */
 914     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 915
 916     /**
 917      *  @brief Initialize a EventPath::Builder for writing into the TLV stream
 918      *
 919      *  @return A reference to EventPath::Builder
 920      */
 921     EventPath::Builder & CreateEventPathBuilder();
 922
 923     /**
 924      *  @brief Inject ImportanceLevel into the TLV stream to indicate the importance level associated with
 925      *  the cluster that is referenced by the path.
 926      *
 927      *  @param [in] aImportanceLevel This is an integer representation of the importance level.
 928      *
 929      *  @return A reference to *this
 930      */
 931     EventDataElement::Builder ImportanceLevel(const uint8_t aImportanceLevel);
 932
 933     /**
 934      *  @brief Inject Number into the TLV stream to indicate the number associated with
 935      *  the cluster that is referenced by the path. The event number is a monotonically increasing number that
 936      *  uniquely identifies each emitted event. This number is scoped to the ImportanceLevel.
 937      *
 938      *  @param [in] aNumber The uint64_t variable to reflectt the event number
 939      *
 940      *  @return A reference to *this
 941      */
 942     EventDataElement::Builder Number(const uint64_t aNumber);
 943
 944     /**
 945      *  @brief Inject UTCTimestamp into the TLV stream.
 946      *  This is encoded as a 64-bit millisecond number since UNIX epoch (Jan 1 1970 00:00:00 GMT).
 947      *
 948      *  @param [in] aUTCTimestamp The uint64_t variable to reflect the UTC timestamp of the Event.
 949      *
 950      *  @return A reference to *this
 951      */
 952     EventDataElement::Builder UTCTimestamp(const uint64_t aUTCTimestamp);
 953
 954     /**
 955      *  @brief Inject SystemTimestamp into the TLV stream. If UTC time is not available, time since boot
 956      *  SHALL be encoded in this field as 64-bit, milliseconds.
 957      *
 958      *  @param [in] aSystemTimestamp The uint64_t variable to reflect system time
 959      *
 960      *  @return A reference to *this
 961      */
 962     EventDataElement::Builder SystemTimestamp(const uint64_t aSystemTimestamp);
 963
 964     /**
 965      *  @brief Inject DataVersion into the TLV stream to indicate the numerical data version associated with
 966      *  the cluster that is referenced by the path. When this field is present, the UTC Timestamp field SHALL be omitted.
 967      *
 968      *  @param [in] aDataVersion The uint64_t variable to reflect DeltaUTCTime
 969      *
 970      *  @return A reference to *this
 971      */
 972     EventDataElement::Builder DeltaUTCTime(const uint64_t aDeltaUTCTime);
 973
 974     /**
 975      *  @brief Inject DeltaSystemTimestamp into the TLV stream.
 976      *  This field is present if delta encoding of the System timestamp relative to a prior event is desired for compression
 977      * reasons. When this field is present, the System Timestamp field SHALL be omitted.
 978      *
 979      *  @param [in] DeltaSystemTimestamp The uint64_t variable to reflect DeltaSystemTime
 980      *
 981      *  @return A reference to *this
 982      */
 983     EventDataElement::Builder DeltaSystemTime(const uint64_t aDeltaSystemTime);
 984
 985     /**
 986      *  @brief Mark the end of this EventDataElement
 987      *
 988      *  @return A reference to *this
 989      */
 990     EventDataElement::Builder & EndOfEventDataElement();
 991
 992 private:
 993     EventPath::Builder mEventPathBuilder;
 994 };
 995 }; // namespace EventDataElement
 996
 997 namespace EventList {
 998 class Parser : public ListParser
 999 {
1000 public:
1001     /**
1002      *  @brief Roughly verify the message is correctly formed
1003      *   1) all mandatory tags are present
1004      *   2) all elements have expected data type
1005      *   3) any tag can only appear once
1006      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1007      *  @note The main use of this function is to print out what we're
1008      *    receiving during protocol development and debugging.
1009      *    The encoding rule has changed in IM encoding spec so this
1010      *    check is only "roughly" conformant now.
1011      *
1012      *  @return #CHIP_NO_ERROR on success
1013      */
1014     CHIP_ERROR CheckSchemaValidity() const;
1015 };
1016
1017 class Builder : public ListBuilder
1018 {
1019 public:
1020     /**
1021      *  @brief Initialize a EventDataElement::Builder for writing into the TLV stream
1022      *
1023      *  @return A reference to EventDataElement::Builder
1024      */
1025     EventDataElement::Builder & CreateEventBuilder();
1026
1027     /**
1028      *  @brief Mark the end of this EventList
1029      *
1030      *  @return A reference to *this
1031      */
1032     EventList::Builder & EndOfEventList();
1033
1034 private:
1035     EventDataElement::Builder mEventDataElementBuilder;
1036 };
1037 }; // namespace EventList
1038
1039 namespace StatusElement {
1040 enum
1041 {
1042     kCsTag_GeneralCode         = 1,
1043     kCsTag_ProtocolId          = 2,
1044     kCsTag_ProtocolCode        = 3,
1045     kCsTag_NamespacedClusterId = 4
1046 };
1047
1048 class Parser : public ListParser
1049 {
1050 public:
1051     /**
1052      *  @brief Initialize the parser object with TLVReader
1053      *
1054      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this StatusElement
1055      *
1056      *  @return #CHIP_NO_ERROR on success
1057      */
1058     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
1059
1060     /**
1061      *  @brief Roughly verify the message is correctly formed
1062      *   1) all mandatory tags are present
1063      *   2) all elements have expected data type
1064      *   3) any tag can only appear once
1065      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1066      *  @note The main use of this function is to print out what we're
1067      *    receiving during protocol development and debugging.
1068      *    The encoding rule has changed in IM encoding spec so this
1069      *    check is only "roughly" conformant now.
1070      *
1071      *  @return #CHIP_NO_ERROR on success
1072      */
1073     CHIP_ERROR CheckSchemaValidity() const;
1074
1075     /**
1076     `* Read the GeneralCode, ProtocolId, ProtocolCode, NamespacedClusterId
1077      *
1078      * @param[out]   apGeneralCode     Pointer to the storage for the GeneralCode
1079      * @param[out]   apProtocolId     Pointer to the storage for the ProtocolId
1080      * @param[out]   apProtocolCode   Pointer to the storage for the ProtocolCode
1081      * @param[out]   apNamespacedClusterId     Pointer to the storage for the NamespacedClusterId
1082      *
1083      * @return       CHIP_ERROR codes returned by Chip::TLV objects. CHIP_END_OF_TLV if either
1084      *               element is missing. CHIP_ERROR_WRONG_TLV_TYPE if the elements are of the wrong
1085      *               type.
1086      */
1087     CHIP_ERROR DecodeStatusElement(uint16_t * apGeneralCode, uint32_t * apProtocolId, uint16_t * apProtocolCode,
1088                                    chip::ClusterId * apNamespacedClusterId) const;
1089 };
1090
1091 class Builder : public ListBuilder
1092 {
1093 public:
1094     /**
1095      *  @brief Initialize a StatusElement::Builder for writing into a TLV stream
1096      *
1097      *  @param [in] apWriter    A pointer to TLVWriter
1098      *
1099      *  @return #CHIP_NO_ERROR on success
1100      */
1101     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
1102
1103     /**
1104      * Init the StatusElement container with an particular context tag.
1105      * Required to implement arrays of arrays, and to test ListBuilder.
1106      *
1107      * @param[in]   apWriter    Pointer to the TLVWriter that is encoding the message.
1108      * @param[in]   aContextTagToUse    A contextTag to use.
1109      *
1110      * @return                  CHIP_ERROR codes returned by Chip::TLV objects.
1111      */
1112     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter, const uint8_t aContextTagToUse);
1113
1114     /**
1115     `* Read the GeneralCode, ProtocolId, ProtocolCode, NamespacedClusterId
1116      *
1117      * @param[in]   aGeneralCode    General status code
1118      * @param[in]   aProtocolId     A protocol ID (32-bit integer composed of a 16-bit vendor id and 16-bit Scoped id)
1119      * @param[in]   aProtocolCode   16-bit protocol-specific error code
1120      * @param[in]   aNamespacedClusterId      Cluster Id for ZCL
1121      *
1122      * @return       CHIP_ERROR codes returned by Chip::TLV objects. CHIP_END_OF_TLV if either
1123      *               element is missing. CHIP_ERROR_WRONG_TLV_TYPE if the elements are of the wrong
1124      *               type.
1125      */
1126     StatusElement::Builder & EncodeStatusElement(const uint16_t aGeneralCode, const uint32_t aProtocolId,
1127                                                  const uint16_t aProtocolCode, const chip::ClusterId aNamespacedClusterId);
1128
1129     /**
1130      *  @brief Mark the end of this StatusElement
1131      *
1132      *  @return A reference to *this
1133      */
1134     StatusElement::Builder & EndOfStatusElement();
1135 };
1136 }; // namespace StatusElement
1137
1138 namespace AttributeStatusElement {
1139 enum
1140 {
1141     kCsTag_AttributePath = 0,
1142     kCsTag_StatusElement = 1,
1143 };
1144
1145 class Builder : public chip::app::Builder
1146 {
1147 public:
1148     /**
1149      *  @brief Initialize a AttributeStatusElement::Builder for writing into a TLV stream
1150      *
1151      *  @param [in] apWriter    A pointer to TLVWriter
1152      *
1153      *  @return #CHIP_NO_ERROR on success
1154      */
1155     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
1156
1157     /**
1158      *  @brief Initialize a AttributePath::Builder for writing into the TLV stream
1159      *
1160      *  @return A reference to AttributePath::Builder
1161      */
1162     AttributePath::Builder & CreateAttributePathBuilder();
1163
1164     /**
1165      *  @brief Initialize a StatusElement::Builder for writing into the TLV stream
1166      *
1167      *  @return A reference to StatusElement::Builder
1168      */
1169     StatusElement::Builder & CreateStatusElementBuilder();
1170
1171     /**
1172      *  @brief Mark the end of this AttributeStatusElement
1173      *
1174      *  @return A reference to *this
1175      */
1176     AttributeStatusElement::Builder & EndOfAttributeStatusElement();
1177
1178 private:
1179     AttributePath::Builder mAttributePathBuilder;
1180     StatusElement::Builder mStatusElementBuilder;
1181 };
1182
1183 class Parser : public chip::app::Parser
1184 {
1185 public:
1186     /**
1187      *  @brief Initialize the parser object with TLVReader
1188      *
1189      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this AttributeStatusElement
1190      *
1191      *  @return #CHIP_NO_ERROR on success
1192      */
1193     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
1194
1195     /**
1196      *  @brief Roughly verify the message is correctly formed
1197      *   1) all mandatory tags are present
1198      *   2) all elements have expected data type
1199      *   3) any tag can only appear once
1200      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1201      *  @note The main use of this function is to print out what we're
1202      *    receiving during protocol development and debugging.
1203      *    The encoding rule has changed in IM encoding spec so this
1204      *    check is only "roughly" conformant now.
1205      *
1206      *  @return #CHIP_NO_ERROR on success
1207      */
1208     CHIP_ERROR CheckSchemaValidity() const;
1209
1210     /**
1211      *  @brief Get a TLVReader for the AttributePath. Next() must be called before accessing them.
1212      *
1213      *  @param [in] apAttributePath    A pointer to apAttributePath
1214      *
1215      *  @return #CHIP_NO_ERROR on success
1216      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Path
1217      *          #CHIP_END_OF_TLV if there is no such element
1218      */
1219     CHIP_ERROR GetAttributePath(AttributePath::Parser * const apAttributePath) const;
1220
1221     /**
1222      *  @brief Get a TLVReader for the StatusElement. Next() must be called before accessing them.
1223      *
1224      *  @param [in] apStatusElement    A pointer to apStatusElement
1225      *
1226      *  @return #CHIP_NO_ERROR on success
1227      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Path
1228      *          #CHIP_END_OF_TLV if there is no such element
1229      */
1230     CHIP_ERROR GetStatusElement(StatusElement::Parser * const apStatusElement) const;
1231 };
1232 }; // namespace AttributeStatusElement
1233
1234 namespace AttributeStatusList {
1235 class Builder : public ListBuilder
1236 {
1237 public:
1238     /**
1239      *  @brief Initialize a AttributeStatus::Builder for writing into the TLV stream
1240      *
1241      *  @return A reference to AttributeStatus::Builder
1242      */
1243     AttributeStatusElement::Builder & CreateAttributeStatusBuilder();
1244
1245     /**
1246      *  @brief Mark the end of this AttributeStatusList
1247      *
1248      *  @return A reference to *this
1249      */
1250     AttributeStatusList::Builder & EndOfAttributeStatusList();
1251
1252 private:
1253     AttributeStatusElement::Builder mAttributeStatusBuilder;
1254 };
1255
1256 class Parser : public ListParser
1257 {
1258 public:
1259     /**
1260      *  @brief Roughly verify the message is correctly formed
1261      *   1) all mandatory tags are present
1262      *   2) all elements have expected data type
1263      *   3) any tag can only appear once
1264      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1265      *  @note The main use of this function is to print out what we're
1266      *    receiving during protocol development and debugging.
1267      *    The encoding rule has changed in IM encoding spec so this
1268      *    check is only "roughly" conformant now.
1269      *
1270      *  @return #CHIP_NO_ERROR on success
1271      */
1272     CHIP_ERROR CheckSchemaValidity() const;
1273 };
1274 }; // namespace AttributeStatusList
1275
1276 namespace AttributeDataElement {
1277 enum
1278 {
1279     kCsTag_AttributePath       = 0,
1280     kCsTag_DataVersion         = 1,
1281     kCsTag_Data                = 2,
1282     kCsTag_MoreClusterDataFlag = 3,
1283 };
1284
1285 class Parser : public chip::app::Parser
1286 {
1287 public:
1288     /**
1289      *  @brief Initialize the parser object with TLVReader
1290      *
1291      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this AttributeDataElement
1292      *
1293      *  @return #CHIP_NO_ERROR on success
1294      */
1295     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
1296
1297     /**
1298      *  @brief Roughly verify the message is correctly formed
1299      *   1) all mandatory tags are present
1300      *   2) all elements have expected data type
1301      *   3) any tag can only appear once
1302      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1303      *  @note The main use of this function is to print out what we're
1304      *    receiving during protocol development and debugging.
1305      *    The encoding rule has changed in IM encoding spec so this
1306      *    check is only "roughly" conformant now.
1307      *
1308      *  @return #CHIP_NO_ERROR on success
1309      */
1310     CHIP_ERROR CheckSchemaValidity() const;
1311
1312     /**
1313      *  @brief Get a TLVReader for the AttributePath. Next() must be called before accessing them.
1314      *
1315      *  @param [in] apAttributePath    A pointer to apAttributePath
1316      *
1317      *  @return #CHIP_NO_ERROR on success
1318      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Path
1319      *          #CHIP_END_OF_TLV if there is no such element
1320      */
1321     CHIP_ERROR GetAttributePath(AttributePath::Parser * const apAttributePath) const;
1322
1323     /**
1324      *  @brief Get a TLVReader for the DataVersion. Next() must be called before accessing them.
1325      *
1326      *  @param [in] apVersion    A pointer to apVersion
1327      *
1328      *  @return #CHIP_NO_ERROR on success
1329      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not any of the defined unsigned integer types
1330      *          #CHIP_END_OF_TLV if there is no such element
1331      */
1332     CHIP_ERROR GetDataVersion(chip::DataVersion * const apVersion) const;
1333
1334     /**
1335      *  @brief Get a TLVReader for the Data. Next() must be called before accessing them.
1336      *
1337      *  @param [in] apReader    A pointer to apReader
1338      *
1339      *  @return #CHIP_NO_ERROR on success
1340      *          #CHIP_END_OF_TLV if there is no such element
1341      */
1342     CHIP_ERROR GetData(chip::TLV::TLVReader * const apReader) const;
1343
1344     /**
1345      *  @brief Check whether it need more cluster data Next() must be called before accessing them.
1346      *
1347      *  @param [in] apMoreClusterDataFlag    A pointer to apMoreClusterDataFlag
1348      *
1349      *  @return #CHIP_NO_ERROR on success
1350      *          #CHIP_END_OF_TLV if there is no such element
1351      */
1352     CHIP_ERROR GetMoreClusterDataFlag(bool * const apMoreClusterDataFlag) const;
1353
1354 protected:
1355     // A recursively callable function to parse a data element and pretty-print it.
1356     CHIP_ERROR ParseData(chip::TLV::TLVReader & aReader, int aDepth) const;
1357 };
1358
1359 class Builder : public chip::app::Builder
1360 {
1361 public:
1362     /**
1363      *  @brief Initialize a AttributeDataElement::Builder for writing into a TLV stream
1364      *
1365      *  @param [in] apWriter    A pointer to TLVWriter
1366      *
1367      *  @return #CHIP_NO_ERROR on success
1368      */
1369     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
1370
1371     /**
1372      *  @brief Initialize a AttributePath::Builder for writing into the TLV stream
1373      *
1374      *  @return A reference to AttributePath::Builder
1375      */
1376     AttributePath::Builder & CreateAttributePathBuilder();
1377
1378     /**
1379      *  @brief Inject DataVersion into the TLV stream to indicate the numerical data version associated with
1380      *  the cluster that is referenced by the path.
1381      *
1382      *  @param [in] aDataVersion The boolean variable to indicate if AttributeDataElement has version
1383      *
1384      *  @return A reference to *this
1385      */
1386     AttributeDataElement::Builder & DataVersion(const chip::DataVersion aDataVersion);
1387
1388     /**
1389      *  @brief Inject aMoreClusterData into the TLV stream to indicate whether there is more cluster data.
1390      *  This is present when there is more than one AttributeDataElement as part of a logical Changeset,
1391      *  and the entire set needs to be applied ‘atomically’ on the receiver.
1392      *
1393      *  @param [in] aMoreClusterData The boolean variable to indicate if more cluster data is needed.
1394      *
1395      *  @return A reference to *this
1396      */
1397     AttributeDataElement::Builder & MoreClusterData(const bool aMoreClusterData);
1398
1399     /**
1400      *  @brief Mark the end of this AttributeDataElement
1401      *
1402      *  @return A reference to *this
1403      */
1404     AttributeDataElement::Builder & EndOfAttributeDataElement();
1405
1406 private:
1407     AttributePath::Builder mAttributePathBuilder;
1408 };
1409 }; // namespace AttributeDataElement
1410
1411 namespace AttributeDataList {
1412 class Parser : public ListParser
1413 {
1414 public:
1415     /**
1416      *  @brief Roughly verify the message is correctly formed
1417      *   1) all mandatory tags are present
1418      *   2) all elements have expected data type
1419      *   3) any tag can only appear once
1420      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1421      *  @note The main use of this function is to print out what we're
1422      *    receiving during protocol development and debugging.
1423      *    The encoding rule has changed in IM encoding spec so this
1424      *    check is only "roughly" conformant now.
1425      *
1426      *  @return #CHIP_NO_ERROR on success
1427      */
1428     CHIP_ERROR CheckSchemaValidity() const;
1429 };
1430
1431 class Builder : public ListBuilder
1432 {
1433 public:
1434     /**
1435      *  @brief Initialize a AttributeDataElement::Builder for writing into the TLV stream
1436      *
1437      *  @return A reference to AttributeDataElement::Builder
1438      */
1439     AttributeDataElement::Builder & CreateAttributeDataElementBuilder();
1440
1441     /**
1442      *  @brief Mark the end of this AttributeDataList
1443      *
1444      *  @return A reference to *this
1445      */
1446     AttributeDataList::Builder & EndOfAttributeDataList();
1447
1448 private:
1449     AttributeDataElement::Builder mAttributeDataElementBuilder;
1450 };
1451 }; // namespace AttributeDataList
1452
1453 namespace CommandDataElement {
1454 enum
1455 {
1456     kCsTag_CommandPath   = 0,
1457     kCsTag_Data          = 1,
1458     kCsTag_StatusElement = 2,
1459 };
1460
1461 class Parser : public chip::app::Parser
1462 {
1463 public:
1464     /**
1465      *  @brief Initialize the parser object with TLVReader
1466      *
1467      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this CommandDataElement
1468      *
1469      *  @return #CHIP_NO_ERROR on success
1470      */
1471     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
1472
1473     /**
1474      *  @brief Roughly verify the message is correctly formed
1475      *   1) all mandatory tags are present
1476      *   2) all elements have expected data type
1477      *   3) any tag can only appear once
1478      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1479      *  @note The main use of this function is to print out what we're
1480      *    receiving during protocol development and debugging.
1481      *    The encoding rule has changed in IM encoding spec so this
1482      *    check is only "roughly" conformant now.
1483      *
1484      *  @return #CHIP_NO_ERROR on success
1485      */
1486     CHIP_ERROR CheckSchemaValidity() const;
1487
1488     /**
1489      *  @brief Get a TLVReader for the CommandPath. Next() must be called before accessing them.
1490      *
1491      *  @param [in] apCommandPath    A pointer to apCommandPath
1492      *
1493      *  @return #CHIP_NO_ERROR on success
1494      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Path
1495      *          #CHIP_END_OF_TLV if there is no such element
1496      */
1497     CHIP_ERROR GetCommandPath(CommandPath::Parser * const apCommandPath) const;
1498
1499     /**
1500      *  @brief Get a TLVReader for the Data. Next() must be called before accessing them.
1501      *
1502      *  @param [in] apReader    A pointer to apReader
1503      *
1504      *  @return #CHIP_NO_ERROR on success
1505      *          #CHIP_END_OF_TLV if there is no such element
1506      */
1507     CHIP_ERROR GetData(chip::TLV::TLVReader * const apReader) const;
1508
1509     /**
1510      *  @brief Get a TLVReader for the Data. Next() must be called before accessing them.
1511      *
1512      *  @param [in] apStatusElement    A pointer to apStatusElement
1513      *
1514      *  @return #CHIP_NO_ERROR on success
1515      *          # CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a structure
1516      *          #CHIP_END_OF_TLV if there is no such element
1517      */
1518     CHIP_ERROR GetStatusElement(StatusElement::Parser * const apStatusElement) const;
1519
1520 protected:
1521     // A recursively callable function to parse a data element and pretty-print it.
1522     CHIP_ERROR ParseData(chip::TLV::TLVReader & aReader, int aDepth) const;
1523 };
1524
1525 class Builder : public chip::app::Builder
1526 {
1527 public:
1528     /**
1529      *  @brief Initialize a AttributeDataList::Builder for writing into a TLV stream
1530      *
1531      *  @param [in] apWriter    A pointer to TLVWriter
1532      *
1533      *  @return #CHIP_NO_ERROR on success
1534      */
1535     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
1536
1537     /**
1538      *  @brief Initialize a CommandPath::Builder for writing into the TLV stream
1539      *
1540      *  @return A reference to CommandPath::Builder
1541      */
1542     CommandPath::Builder & CreateCommandPathBuilder();
1543
1544     /**
1545      *  @brief Initialize a StatusElement::Builder for writing into the TLV stream
1546      *
1547      *  @return A reference to StatusElement::Builder
1548      */
1549     StatusElement::Builder & CreateStatusElementBuilder();
1550
1551     /**
1552      *  @brief Mark the end of this CommandDataElement
1553      *
1554      *  @return A reference to *this
1555      */
1556     CommandDataElement::Builder & EndOfCommandDataElement();
1557
1558 private:
1559     CommandPath::Builder mCommandPathBuilder;
1560     StatusElement::Builder mStatusElementBuilder;
1561 };
1562 }; // namespace CommandDataElement
1563
1564 namespace CommandList {
1565 class Parser : public ListParser
1566 {
1567 public:
1568     /**
1569      *  @brief Roughly verify the message is correctly formed
1570      *   1) all mandatory tags are present
1571      *   2) all elements have expected data type
1572      *   3) any tag can only appear once
1573      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1574      *  @note The main use of this function is to print out what we're
1575      *    receiving during protocol development and debugging.
1576      *    The encoding rule has changed in IM encoding spec so this
1577      *    check is only "roughly" conformant now.
1578      *
1579      *  @return #CHIP_NO_ERROR on success
1580      */
1581     CHIP_ERROR CheckSchemaValidity() const;
1582 };
1583
1584 class Builder : public ListBuilder
1585 {
1586 public:
1587     /**
1588      *  @brief Initialize a CommandDataElement::Builder for writing into the TLV stream
1589      *
1590      *  @return A reference to AttributeDataList::Builder
1591      */
1592     CommandDataElement::Builder & CreateCommandDataElementBuilder();
1593
1594     /**
1595      *  @brief Mark the end of this CommandList
1596      *
1597      *  @return A reference to *this
1598      */
1599     CommandList::Builder & EndOfCommandList();
1600
1601 private:
1602     CommandDataElement::Builder mCommandDataElementBuilder;
1603 };
1604 }; // namespace CommandList
1605
1606 namespace ReportData {
1607 enum
1608 {
1609     kCsTag_RequestResponse     = 0,
1610     kCsTag_SubscriptionId      = 1,
1611     kCsTag_AttributeStatusList = 2,
1612     kCsTag_AttributeDataList   = 3,
1613     kCsTag_EventDataList       = 4,
1614     kCsTag_IsLastReport        = 5,
1615 };
1616
1617 class Parser : public chip::app::Parser
1618 {
1619 public:
1620     /**
1621      *  @brief Initialize the parser object with TLVReader
1622      *
1623      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this ReportData
1624      *
1625      *  @return #CHIP_NO_ERROR on success
1626      */
1627     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
1628
1629     /**
1630      *  @brief Roughly verify the message is correctly formed
1631      *   1) all mandatory tags are present
1632      *   2) all elements have expected data type
1633      *   3) any tag can only appear once
1634      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1635      *  @note The main use of this function is to print out what we're
1636      *    receiving during protocol development and debugging.
1637      *    The encoding rule has changed in IM encoding spec so this
1638      *    check is only "roughly" conformant now.
1639      *
1640      *  @return #CHIP_NO_ERROR on success
1641      */
1642     CHIP_ERROR CheckSchemaValidity() const;
1643
1644     /**
1645      *  @brief Check whether this message needs request response. Next() must be called before accessing them.
1646      *
1647      *  @param [in] apRequestResponse    A pointer to apRequestResponse
1648      *
1649      *  @return #CHIP_NO_ERROR on success
1650      *          #CHIP_END_OF_TLV if there is no such element
1651      */
1652     CHIP_ERROR GetRequestResponse(bool * const apRequestResponse) const;
1653
1654     /**
1655      *  @brief Get Subscription Id. Next() must be called before accessing them.
1656      *
1657      *  @param [in] apSubscriptionId    A pointer to apIsLastReport
1658      *
1659      *  @return #CHIP_NO_ERROR on success
1660      *          #CHIP_END_OF_TLV if there is no such element
1661      */
1662     CHIP_ERROR GetSubscriptionId(uint64_t * const apSubscriptionId) const;
1663
1664     /**
1665      *  @brief Get a TLVReader for the AttributesStatusList. Next() must be called before accessing them.
1666      *
1667      *  @param [in] apAttributeStatusList    A pointer to apAttributeStatusList
1668      *
1669      *  @return #CHIP_NO_ERROR on success
1670      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Array
1671      *          #CHIP_END_OF_TLV if there is no such element
1672      */
1673     CHIP_ERROR GetAttributeStatusList(AttributeStatusList::Parser * const apAttributeStatusList) const;
1674
1675     /**
1676      *  @brief Get a TLVReader for the AttributesDataList. Next() must be called before accessing them.
1677      *
1678      *  @param [in] apAttributeDataList    A pointer to apAttributeDataList
1679      *
1680      *  @return #CHIP_NO_ERROR on success
1681      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Array
1682      *          #CHIP_END_OF_TLV if there is no such element
1683      */
1684     CHIP_ERROR GetAttributeDataList(AttributeDataList::Parser * const apAttributeDataList) const;
1685
1686     /**
1687      *  @brief Get a TLVReader for the EventDataList. Next() must be called before accessing them.
1688      *
1689      *  @param [in] apEventDataList    A pointer to apEventDataList
1690      *
1691      *  @return #CHIP_NO_ERROR on success
1692      *          #CHIP_ERROR_WRONG_TLV_TYPE if there is such element but it's not a Array
1693      *          #CHIP_END_OF_TLV if there is no such element
1694      */
1695     CHIP_ERROR GetEventDataList(EventList::Parser * const apEventDataList) const;
1696
1697     /**
1698      *  @brief Check whether this message is last report. Next() must be called before accessing them.
1699      *
1700      *  @param [in] apIsLastReport    A pointer to apIsLastReport
1701      *
1702      *  @return #CHIP_NO_ERROR on success
1703      *          #CHIP_END_OF_TLV if there is no such element
1704      */
1705     CHIP_ERROR GetIsLastReport(bool * const apIsLastReport) const;
1706 };
1707
1708 class Builder : public chip::app::Builder
1709 {
1710 public:
1711     /**
1712      *  @brief Initialize a ReportData::Builder for writing into a TLV stream
1713      *
1714      *  @param [in] apWriter    A pointer to TLVWriter
1715      *
1716      *  @return #CHIP_NO_ERROR on success
1717      */
1718     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
1719
1720     /**
1721      *  @brief Inject RequestResponse into the TLV stream to indicate whether a response (a StatusReponse specifically)
1722      *  is to be sent back to the request.
1723      *
1724      *  @param [in] aRequestResponse The boolean variable to indicate if request response is needed.
1725      *
1726      *  @return A reference to *this
1727      */
1728     ReportData::Builder & RequestResponse(const bool aRequestResponse);
1729
1730     /**
1731      *  @brief Inject subscription id into the TLV stream, This field contains the Subscription ID
1732      *  to which the data is being sent against. This is not present when the ReportDataRequest is
1733      *  sent in response to a ReadRequest, but is present when sent in response to a SubscribeRequest.
1734      *  Attempts should be made to ensure the SubscriptionId does not collide with IDs from previous
1735      *  subscriptions to ensure disambiguation.
1736      *
1737      *  @param [in] aSubscriptionId  Subscription Id for this report data
1738      *
1739      *  @return A reference to *this
1740      */
1741     ReportData::Builder & SubscriptionId(const uint64_t aSubscriptionId);
1742
1743     /**
1744      *  @brief Initialize a AttributeStatusList::Builder for writing into the TLV stream
1745      *
1746      *  @return A reference to AttributeStatusList::Builder
1747      */
1748     AttributeStatusList::Builder & CreateAttributeStatusListBuilder();
1749
1750     /**
1751      *  @brief Initialize a AttributeDataList::Builder for writing into the TLV stream
1752      *
1753      *  @return A reference to AttributeDataList::Builder
1754      */
1755     AttributeDataList::Builder & CreateAttributeDataListBuilder();
1756
1757     /**
1758      *  @brief Initialize a EventList::Builder for writing into the TLV stream
1759      *
1760      *  @return A reference to EventList::Builder
1761      */
1762     EventList::Builder & CreateEventDataListBuilder();
1763
1764     /**
1765      *  @brief This flag is set to ‘true’ when this is the last ReportDataRequest message
1766      *  in a transaction and there are no more Changes to be conveyed.
1767      *  @param [in] aIsLastReport The boolean variable to indicate if it is LastReport
1768      *  @return A reference to *this
1769      */
1770     ReportData::Builder & IsLastReport(const bool aIsLastReport);
1771
1772     /**
1773      *  @brief Mark the end of this ReportData
1774      *
1775      *  @return A reference to *this
1776      */
1777     ReportData::Builder & EndOfReportData();
1778
1779 private:
1780     AttributeStatusList::Builder mAttributeStatusListBuilder;
1781     AttributeDataList::Builder mAttributeDataListBuilder;
1782     EventList::Builder mEventDataListBuilder;
1783 };
1784 }; // namespace ReportData
1785
1786 namespace InvokeCommand {
1787 enum
1788 {
1789     kCsTag_CommandList = 0,
1790 };
1791
1792 class Parser : public chip::app::Parser
1793 {
1794 public:
1795     /**
1796      *  @brief Initialize the parser object with TLVReader
1797      *
1798      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this request
1799      *
1800      *  @return #CHIP_NO_ERROR on success
1801      */
1802     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
1803
1804     /**
1805      *  @brief Roughly verify the message is correctly formed
1806      *   1) all mandatory tags are present
1807      *   2) all elements have expected data type
1808      *   3) any tag can only appear once
1809      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
1810      *  @note The main use of this function is to print out what we're
1811      *    receiving during protocol development and debugging.
1812      *    The encoding rule has changed in IM encoding spec so this
1813      *    check is only "roughly" conformant now.
1814      *
1815      *  @return #CHIP_NO_ERROR on success
1816      */
1817     CHIP_ERROR CheckSchemaValidity() const;
1818
1819     /**
1820      *  @brief Get a TLVReader for the CommandList. Next() must be called before accessing them.
1821      *
1822      *  @param [in] apWriter    A pointer to TLVWriter
1823      *
1824      *  @return #CHIP_NO_ERROR on success
1825      *          #CHIP_END_OF_TLV if there is no such element
1826      */
1827     CHIP_ERROR GetCommandList(CommandList::Parser * const apCommandList) const;
1828 };
1829
1830 class Builder : public chip::app::Builder
1831 {
1832 public:
1833     /**
1834      *  @brief Initialize a InvokeCommand::Builder for writing into a TLV stream
1835      *
1836      *  @param [in] apWriter    A pointer to TLVWriter
1837      *
1838      *  @return #CHIP_NO_ERROR on success
1839      */
1840     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
1841
1842     /**
1843      *  @brief Initialize a CommandList::Builder for writing into the TLV stream
1844      *
1845      *  @return A reference to Path::Builder
1846      */
1847     CommandList::Builder & CreateCommandListBuilder();
1848
1849     /**
1850      *  @brief Mark the end of this InvokeCommand
1851      *
1852      *  @return A reference to *this
1853      */
1854     InvokeCommand::Builder & EndOfInvokeCommand();
1855
1856 private:
1857     CommandList::Builder mCommandListBuilder;
1858 };
1859 }; // namespace InvokeCommand
1860
1861 }; // namespace app
1862 }; // namespace chip
1863
1864 #endif // _CHIP_INTERACTION_MODEL_MESSAGE_DEF_H