Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2020-2023 Project CHIP Authors
4 : * Copyright (c) 2013-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 : /**
20 : * @file
21 : * This file contains definitions for working with data encoded in CHIP TLV format.
22 : *
23 : * CHIP TLV (Tag-Length-Value) is a generalized encoding method for simple structured data. It
24 : * shares many properties with the commonly used JSON serialization format while being considerably
25 : * more compact over the wire.
26 : */
27 :
28 : #pragma once
29 :
30 : #include "TLVCommon.h"
31 :
32 : #include "TLVReader.h"
33 : #include "TLVWriter.h"
34 :
35 : /**
36 : * @namespace chip::TLV
37 : *
38 : * Definitions for working with data encoded in CHIP TLV format.
39 : *
40 : * CHIP TLV is a generalized encoding method for simple structured data. It shares many properties
41 : * with the commonly used JSON serialization format while being considerably more compact over the wire.
42 : */
43 :
44 : namespace chip {
45 : namespace TLV {
46 :
47 : /**
48 : * Provides an interface for TLVReader or TLVWriter to use memory other than a simple contiguous buffer.
49 : */
50 : class DLL_EXPORT TLVBackingStore
51 : {
52 : public:
53 11872 : virtual ~TLVBackingStore() {}
54 : /**
55 : * A function to provide a backing store's initial start position and data length to a reader.
56 : *
57 : * @param[in] reader A reference to the TLVReader object that is requesting input data.
58 : * @param[out] bufStart A reference to a data pointer. On exit, bufStart is expected to point
59 : * to the first byte of TLV data to be parsed.
60 : * @param[out] bufLen A reference to an unsigned integer that the function must set to
61 : * the number of TLV data bytes being returned. If the end of the
62 : * input TLV data has been reached, the function should set this value
63 : * to 0.
64 : *
65 : * @retval #CHIP_NO_ERROR If the function successfully produced TLV data.
66 : * @retval other Other CHIP or platform-specific error codes indicating that an error
67 : * occurred preventing the function from producing the requested data.
68 : */
69 : virtual CHIP_ERROR OnInit(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) = 0;
70 :
71 : /**
72 : * A function that can be used to retrieve additional TLV data to be parsed.
73 : *
74 : * When called, the function is expected to produce additional data for the reader to parse or signal
75 : * the reader that no more data is available.
76 : *
77 : * @param[in] reader A reference to the TLVReader object that is requesting input data.
78 : * @param[in,out] bufStart A reference to a data pointer. On entry to the function, @p bufStart
79 : * points to one byte beyond the last TLV data byte consumed by the
80 : * reader. On exit, bufStart is expected to point to the first byte
81 : * of new TLV data to be parsed. The new pointer value can be within
82 : * the same buffer as the previously consumed data, or it can point
83 : * to an entirely new buffer.
84 : * @param[out] bufLen A reference to an unsigned integer that the function must set to
85 : * the number of TLV data bytes being returned. If the end of the
86 : * input TLV data has been reached, the function should set this value
87 : * to 0.
88 : *
89 : * @retval #CHIP_NO_ERROR If the function successfully produced more TLV data, or the end of
90 : * the input data was reached (@p bufLen should be set to 0 in this case).
91 : * @retval other Other CHIP or platform-specific error codes indicating that an error
92 : * occurred preventing the function from producing the requested data.
93 : */
94 : virtual CHIP_ERROR GetNextBuffer(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) = 0;
95 :
96 : /**
97 : * A function to provide a backing store's initial start position and data length to a writer.
98 : *
99 : * @param[in] writer A reference to the TLVWriter object that is requesting new buffer
100 : * space.
101 : * @param[out] bufStart A reference to a data pointer. On exit, @p bufStart is expected to
102 : * point to the beginning of the new output buffer.
103 : * @param[out] bufLen A reference to an unsigned integer. On exit, @p bufLen is expected
104 : * to contain the maximum number of bytes that can be written to the
105 : * new output buffer.
106 : *
107 : * @retval #CHIP_NO_ERROR If the function was able to supply buffer space for the writer.
108 : * @retval other Other CHIP or platform-specific error codes indicating that an error
109 : * occurred preventing the function from producing buffer space.
110 : */
111 : virtual CHIP_ERROR OnInit(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) = 0;
112 :
113 : /**
114 : * A function that supplies new output buffer space to a TLVWriter.
115 : *
116 : * The function is expected to return a pointer to a memory location where new data should be written,
117 : * along with an associated maximum length. The function can supply write space either by allocating
118 : * a new buffer to hold the data or by clearing out previously written data from an existing buffer.
119 : *
120 : * @param[in] writer A reference to the TLVWriter object that is requesting new buffer
121 : * space.
122 : * @param[in,out] bufStart A reference to a data pointer. On entry to the function, @p bufStart
123 : * points the beginning of the current output buffer. On exit, @p bufStart
124 : * is expected to point to the beginning of the new output buffer.
125 : * The new pointer value can be the same as the previous value (e.g.
126 : * if the function copied the existing data elsewhere), or it can point
127 : * to an entirely new location.
128 : * @param[in,out] bufLen A reference to an unsigned integer. On entry to the function,
129 : * @p bufLen contains the number of byte of @em unused space in the
130 : * current buffer. On exit, @p bufLen is expected to contain the maximum
131 : * number of bytes that can be written to the new output buffer.
132 : *
133 : * @retval #CHIP_NO_ERROR If the function was able to supply more buffer space for the writer.
134 : * @retval other Other CHIP or platform-specific error codes indicating that an error
135 : * occurred preventing the function from producing additional buffer
136 : * space.
137 : */
138 : virtual CHIP_ERROR GetNewBuffer(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) = 0;
139 :
140 : /**
141 : * A function used to perform finalization of the output from a TLVWriter object.
142 : *
143 : * Functions of this type are called when a TLVWriter's Finalize() method is called. The function is
144 : * expected to perform any necessary clean-up or finalization related to consuming the output of the
145 : * writer object. Examples of this include such things as recording the final length of the encoding,
146 : * or closing a file descriptor.
147 : *
148 : * @param[in] writer A reference to the TLVWriter object that is being finalized.
149 : * @param[in,out] bufStart A pointer to the beginning of the current (and final) output buffer.
150 : * @param[in,out] bufLen The number of bytes contained in the buffer pointed to by @p bufStart.
151 : *
152 : * @retval #CHIP_NO_ERROR If finalization was successful.
153 : * @retval other Other CHIP or platform-specific error codes indicating that an error
154 : * occurred during finalization.
155 : *
156 : */
157 : virtual CHIP_ERROR FinalizeBuffer(TLVWriter & writer, uint8_t * bufStart, uint32_t bufLen) = 0;
158 :
159 : /**
160 : * Returns whether call to GetNewBuffer will always fail.
161 : *
162 : * There are some implementations of TLVBackingStore that provide some level of utility, such as access to pool
163 : * of particular kind of buffer and/or reserving space for headers. Some implementation allow the caller to
164 : * specify that they only intend to use a single buffer. It is useful for TLVWriter to know if this is the case.
165 : *
166 : */
167 0 : virtual bool GetNewBufferWillAlwaysFail() { return false; }
168 : };
169 :
170 : } // namespace TLV
171 : } // namespace chip
|
