src/app/message-reader.h

   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 /**
  19  *    @file
  20  *          Contains the API definition for a message buffer reader for the data
  21  *          model.  This reader does the necessary bounds-checks before reading
  22  *          and updates its own state as the buffer is read.
  23  */
  24
  25 #pragma once
  26
  27 #include <app/util/basic-types.h>
  28 #include <lib/core/CHIPError.h>
  29 #include <lib/support/BufferReader.h>
  30 #include <lib/support/CodeUtils.h>
  31 #include <stdint.h>
  32
  33 namespace chip {
  34
  35 class DataModelReader
  36 {
  37 public:
  38     /**
  39      * Create a data model reader from a given buffer and length.
  40      *
  41      * @param buffer The octet buffer to read from.  The caller must ensure
  42      *               (most simply by allocating the reader on the stack) that
  43      *               the buffer outlives the reader.  The buffer is allowed to
  44      *               be null if buf_len is 0.
  45      * @param buf_len The number of octets in the buffer.
  46      */
  47     DataModelReader(const uint8_t * buffer, uint16_t buf_len) : mReader(buffer, buf_len) {}
  48
  49     /**
  50      * Number of octets we have read so far.  This might be able to go away once
  51      * we do less switching back and forth between DataModelReader and raw
  52      * buffers.
  53      */
  54     uint16_t OctetsRead() const { return mReader.OctetsRead(); }
  55
  56     /**
  57      * The reader status.
  58      */
  59     CHIP_ERROR StatusCode() const { return mReader.StatusCode(); }
  60
  61     /**
  62      * Read a cluster id.
  63      *
  64      * @param [out] cluster_id Where the cluster id goes.
  65      *
  66      * @return Whether the read succeeded.  The read can fail if there are not
  67      *         enough octets available.
  68      */
  69     CHECK_RETURN_VALUE DataModelReader & ReadClusterId(ClusterId * cluster_id)
  70     {
  71         mReader.RawRead(cluster_id);
  72         return *this;
  73     }
  74
  75     /**
  76      * Read an endpoint id.
  77      *
  78      * @param [out] endpoint_id Where the endpoint id goes.
  79      *
  80      * @return Whether the read succeeded.  The read can fail if there are not
  81      *         enough octets available.
  82      */
  83     CHECK_RETURN_VALUE DataModelReader & ReadEndpointId(EndpointId * endpoint_id)
  84     {
  85         mReader.RawRead(endpoint_id);
  86         return *this;
  87     }
  88
  89     /**
  90      * Read a group id.
  91      *
  92      * @param [out] group_id Where the group id goes.
  93      *
  94      * @return Whether the read succeeded.  The read can fail if there are not
  95      *         enough octets available.
  96      */
  97     CHECK_RETURN_VALUE DataModelReader & ReadGroupId(GroupId * group_id)
  98     {
  99         mReader.RawRead(group_id);
 100         return *this;
 101     }
 102
 103     /**
 104      * Read a single octet.
 105      *
 106      * @param [out] octet Where the octet goes.
 107      *
 108      * @return Whether the read succeeded.  The read can fail if there are not
 109      *         enough octets available.
 110      *
 111      * @note Use of APIs that read some semantically-meaningful type is preferred.
 112      */
 113     CHECK_RETURN_VALUE DataModelReader & ReadOctet(uint8_t * octet)
 114     {
 115         mReader.RawRead(octet);
 116         return *this;
 117     }
 118
 119     /**
 120      * Read a single 16-bit unsigned integer.
 121      *
 122      * @param [out] dest Where the 16-bit integer goes.
 123      *
 124      * @return Whether the read succeeded.  The read can fail if there are not
 125      *         enough octets available.
 126      *
 127      * @note Use of APIs that read some semantically-meaningful type is preferred.
 128      */
 129     CHECK_RETURN_VALUE DataModelReader & Read16(uint16_t * dest)
 130     {
 131         mReader.RawRead(dest);
 132         return *this;
 133     }
 134
 135 private:
 136     Encoding::LittleEndian::Reader mReader;
 137 };
 138
 139 } // namespace chip