src/app/MessageDef/ReadRequest.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 ReadRequest parser and builder in CHIP interaction model
  21  *
  22  */
  23
  24 #pragma once
  25
  26 #ifndef _CHIP_INTERACTION_MODEL_MESSAGE_DEF_READ_REQUEST_H
  27 #define _CHIP_INTERACTION_MODEL_MESSAGE_DEF_READ_REQUEST_H
  28
  29 #include "AttributeDataVersionList.h"
  30 #include "AttributePathList.h"
  31 #include "Builder.h"
  32 #include "EventPathList.h"
  33
  34 #include "Parser.h"
  35 #include <core/CHIPCore.h>
  36 #include <core/CHIPTLV.h>
  37 #include <support/CodeUtils.h>
  38 #include <support/logging/CHIPLogging.h>
  39 #include <util/basic-types.h>
  40
  41 namespace chip {
  42 namespace app {
  43 namespace ReadRequest {
  44 enum
  45 {
  46     kCsTag_AttributePathList        = 0,
  47     kCsTag_EventPathList            = 1,
  48     kCsTag_AttributeDataVersionList = 2,
  49     kCsTag_EventNumber              = 3,
  50 };
  51
  52 class Parser : public chip::app::Parser
  53 {
  54 public:
  55     /**
  56      *  @brief Initialize the parser object with TLVReader
  57      *
  58      *  @param [in] aReader A pointer to a TLVReader, which should point to the beginning of this request
  59      *
  60      *  @return #CHIP_NO_ERROR on success
  61      */
  62     CHIP_ERROR Init(const chip::TLV::TLVReader & aReader);
  63
  64     /**
  65      *  @brief Roughly verify the message is correctly formed
  66      *   1) all mandatory tags are present
  67      *   2) all elements have expected data type
  68      *   3) any tag can only appear once
  69      *   4) At the top level of the structure, unknown tags are ignored for forward compatibility
  70      *  @note The main use of this function is to print out what we're
  71      *    receiving during protocol development and debugging.
  72      *    The encoding rule has changed in IM encoding spec so this
  73      *    check is only "roughly" conformant now.
  74      *
  75      *  @return #CHIP_NO_ERROR on success
  76      */
  77     CHIP_ERROR CheckSchemaValidity() const;
  78
  79     /**
  80      *  @brief Get a TLVReader for the AttributePathList. Next() must be called before accessing them.
  81      *
  82      *  @param [in] apAttributePath    A pointer to apAttributePath
  83      *
  84      *  @return #CHIP_NO_ERROR on success
  85      *          #CHIP_END_OF_TLV if there is no such element
  86      */
  87     CHIP_ERROR GetAttributePathList(AttributePathList::Parser * const apAttributePathList) const;
  88
  89     /**
  90      *  @brief Get a TLVReader for the EventPathList. Next() must be called before accessing them.
  91      *
  92      *  @param [in] apEventPathList    A pointer to apEventPathList
  93      *
  94      *  @return #CHIP_NO_ERROR on success
  95      *          #CHIP_END_OF_TLV if there is no such element
  96      */
  97     CHIP_ERROR GetEventPathList(EventPathList::Parser * const apEventPathList) const;
  98
  99     /**
 100      *  @brief Get a parser for the AttributeDataVersionList. Next() must be called before accessing them.
 101      *
 102      *  @param [in] apAttributeDataVersionList    A pointer to apAttributeDataVersionList
 103      *
 104      *  @return #CHIP_NO_ERROR on success
 105      *          #CHIP_END_OF_TLV if there is no such element
 106      */
 107     CHIP_ERROR GetAttributeDataVersionList(AttributeDataVersionList::Parser * const apAttributeDataVersionList) const;
 108
 109     /**
 110      *  @brief Get Event Number. Next() must be called before accessing them.
 111      *
 112      *  @param [in] apEventNumber    A pointer to apEventNumber
 113      *
 114      *  @return #CHIP_NO_ERROR on success
 115      *          #CHIP_END_OF_TLV if there is no such element
 116      */
 117     CHIP_ERROR GetEventNumber(uint64_t * const apEventNumber) const;
 118 };
 119
 120 class Builder : public chip::app::Builder
 121 {
 122 public:
 123     /**
 124      *  @brief Initialize a ReadRequest::Builder for writing into a TLV stream
 125      *
 126      *  @param [in] apWriter    A pointer to TLVWriter
 127      *
 128      *  @return #CHIP_NO_ERROR on success
 129      */
 130     CHIP_ERROR Init(chip::TLV::TLVWriter * const apWriter);
 131
 132     /**
 133      *  @brief Initialize a AttributePathList::Builder for writing into the TLV stream
 134      *
 135      *  @return A reference to AttributePathList::Builder
 136      */
 137     AttributePathList::Builder & CreateAttributePathListBuilder();
 138
 139     /**
 140      *  @brief Initialize a EventPathList::Builder for writing into the TLV stream
 141      *
 142      *  @return A reference to EventPathList::Builder
 143      */
 144     EventPathList::Builder & CreateEventPathListBuilder();
 145
 146     /**
 147      *  @brief Initialize a AttributeDataVersionList::Builder for writing into the TLV stream
 148      *
 149      *  @return A reference to AttributeDataVersionList::Builder
 150      */
 151     AttributeDataVersionList::Builder & CreateAttributeDataVersionListBuilder();
 152
 153     /**
 154      *  @brief An initiator can optionally specify an EventNumber it has already to limit the
 155      *  set of retrieved events on the server for optimization purposes.
 156      *  @param [in] aEventNumber The event number
 157      *  @return A reference to *this
 158      */
 159     ReadRequest::Builder & EventNumber(const uint64_t aEventNumber);
 160     /**
 161      *  @brief Mark the end of this ReadRequest
 162      *
 163      *  @return A reference to *this
 164      */
 165     ReadRequest::Builder & EndOfReadRequest();
 166
 167 private:
 168     AttributePathList::Builder mAttributePathListBuilder;
 169     EventPathList::Builder mEventPathListBuilder;
 170     AttributeDataVersionList::Builder mAttributeDataVersionListBuilder;
 171 };
 172 }; // namespace ReadRequest
 173 }; // namespace app
 174 }; // namespace chip
 175
 176 #endif // _CHIP_INTERACTION_MODEL_MESSAGE_DEF_READ_REQUEST_H