Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2022 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 : #pragma once
18 :
19 : #include <lib/core/CHIPError.h>
20 : #include <lib/core/ClusterEnums.h>
21 : #include <lib/support/Span.h>
22 :
23 : namespace chip {
24 : namespace DeviceLayer {
25 :
26 : class DeviceInstanceInfoProvider
27 : {
28 : public:
29 97 : DeviceInstanceInfoProvider() = default;
30 98 : virtual ~DeviceInstanceInfoProvider() = default;
31 :
32 : /**
33 : * This struct contains some of the values that are a part of the
34 : * CapabilityMinimaStruct from the basic information cluster. These are
35 : * only the values that are retrieved from the device info provider, other
36 : * values of the CapabilityMinimaStruct are populated elsewhere.
37 : */
38 : struct DeviceInfoCapabilityMinimas
39 : {
40 : uint16_t simultaneousInvocationsSupported;
41 : uint16_t simultaneousWritesSupported;
42 : uint16_t readPathsSupported;
43 : uint16_t subscribePathsSupported;
44 : };
45 :
46 : /**
47 : * @brief Obtain the Vendor Name from the device's factory data.
48 : *
49 : * @param[out] buf Buffer to copy string.
50 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
51 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
52 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
53 : * This size should be +1 higher than maximum possible string.
54 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
55 : * if access fails.
56 : */
57 : virtual CHIP_ERROR GetVendorName(char * buf, size_t bufSize) = 0;
58 :
59 : /**
60 : * @brief Obtain the Vendor Id from the device's factory data.
61 : *
62 : * @param[out] vendorId Reference to location where the vendor id integer will be copied
63 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
64 : * if access fails.
65 : */
66 : virtual CHIP_ERROR GetVendorId(uint16_t & vendorId) = 0;
67 :
68 : /**
69 : * @brief Obtain the Product Name from the device's factory data.
70 : *
71 : * @param[in, out] buf Buffer to copy string.
72 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
73 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
74 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
75 : * This size should be +1 higher than maximum possible string.
76 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
77 : * if access fails.
78 : */
79 : virtual CHIP_ERROR GetProductName(char * buf, size_t bufSize) = 0;
80 :
81 : /**
82 : * @brief Obtain the Product Id from the device's factory data.
83 : *
84 : * @param[out] productId Reference to location where the product id integer will be copied
85 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
86 : * if access fails.
87 : */
88 : virtual CHIP_ERROR GetProductId(uint16_t & productId) = 0;
89 :
90 : /**
91 : * @brief Obtain Part Number from the device factory data.
92 : *
93 : * @param[out] buf Buffer to store the null-terminated result string.
94 : * @param[in] bufSize Size of the buffer. The buffer should allow for fitting in Part Number
95 : * (max 32 characters) and the null terminator.
96 : **/
97 : virtual CHIP_ERROR GetPartNumber(char * buf, size_t bufSize) = 0;
98 :
99 : /**
100 : * @brief Obtain Product URL from the device factory data.
101 : *
102 : * @param[out] buf Buffer to store the null-terminated result string.
103 : * @param[in] bufSize Size of the buffer. The buffer should allow for fitting in Product URL
104 : * (max 256 characters) and the null terminator.
105 : **/
106 : virtual CHIP_ERROR GetProductURL(char * buf, size_t bufSize) = 0;
107 :
108 : /**
109 : * @brief Obtain Product Label from the device factory data.
110 : *
111 : * @param[out] buf Buffer to store the null-terminated result string.
112 : * @param[in] bufSize Size of the buffer. The buffer should allow for fitting in Product Label
113 : * (max 64 characters) and the null terminator.
114 : **/
115 : virtual CHIP_ERROR GetProductLabel(char * buf, size_t bufSize) = 0;
116 :
117 : /**
118 : * @brief Obtain the Serial Number from the device's factory data.
119 : *
120 : * The SerialNumber attribute specifies a human readable serial number
121 : *
122 : * @param[in, out] buf Buffer to copy string.
123 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
124 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
125 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
126 : * This size should be +1 higher than maximum possible string.
127 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
128 : * if access fails.
129 : */
130 : virtual CHIP_ERROR GetSerialNumber(char * buf, size_t bufSize) = 0;
131 :
132 : /**
133 : * @brief Obtain a manufacturing date from the device's factory data.
134 : *
135 : * The ManufacturingDate attribute specifies the date that the Node was manufactured.
136 : * Output values are returned in ISO 8601, where:
137 : * The first month of the year is January and its returning value is equal to 1.
138 : * The first day of a month starts from 1.
139 : *
140 : * @param[out] year Reference to location where manufacturing year will be stored
141 : * @param[out] month 1-based value [range 1-12] Reference to location where manufacturing month will be stored
142 : * @param[out] day 1-based value [range 1-31] Reference to location where manufacturing day will be stored
143 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
144 : * if access fails.
145 : */
146 : virtual CHIP_ERROR GetManufacturingDate(uint16_t & year, uint8_t & month, uint8_t & day) = 0;
147 :
148 : /**
149 : * @brief Retrieve the optional vendor-specific suffix of the manufacturing date
150 : * from the device's factory data.
151 : *
152 : * Per Matter spec 11.1.5.12:
153 : * - The first 8 characters of the ManufacturingDate SHALL be the ISO 8601 date (YYYYMMDD).
154 : * - The final 8 characters MAY contain optional vendor-specific information.
155 : *
156 : * @param[in,out] suffixBuffer A buffer to receive the vendor-defined suffix (up to 8 characters).
157 : * On input, the span size indicates the available capacity.
158 : * On success, the span is reduced to the actual suffix length (0..8).
159 : *
160 : * @returns CHIP_NO_ERROR if the vendor suffix was retrieved successfully (or is empty / not supported),
161 : * CHIP_ERROR_BUFFER_TOO_SMALL if the provided span is too small, or another CHIP_ERROR from the underlying
162 : * implementation if access fails.
163 : */
164 0 : virtual CHIP_ERROR GetManufacturingDateSuffix(MutableCharSpan & suffixBuffer)
165 : {
166 0 : suffixBuffer.reduce_size(0);
167 0 : return CHIP_NO_ERROR;
168 : }
169 :
170 : /**
171 : * @brief Obtain a Hardware Version from the device's factory data.
172 : *
173 : * @param[out] hardwareVersion Reference to location where the hardware version integer will be copied
174 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
175 : * if access fails.
176 : */
177 : virtual CHIP_ERROR GetHardwareVersion(uint16_t & hardwareVersion) = 0;
178 :
179 : /**
180 : * @brief Obtain a Hardware Version String from the device's factory data.
181 : *
182 : * The HardwareVersionString can be used to provide a more user-friendly value than that
183 : * represented by the HardwareVersion attribute.
184 : *
185 : * @param[in, out] buf Buffer to copy string.
186 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
187 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
188 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
189 : * This size should be +1 higher than maximum possible string.
190 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_BUFFER_TOO_SMALL if the buffer was too small to fit string and null
191 : * terminating. or another CHIP_ERROR from the underlying implementation if access fails.
192 : */
193 : virtual CHIP_ERROR GetHardwareVersionString(char * buf, size_t bufSize) = 0;
194 :
195 : /**
196 : * @brief Obtain a Rotating Device ID Unique ID from the device's factory data.
197 : *
198 : * The unique identifier consists of a randomly-generated 128-bit or longer octet string which
199 : * was programmed during factory provisioning or delivered to the device by the vendor using
200 : * secure means after a software update.
201 : *
202 : * @param[out] uniqueIdSpan Reference to location where the Rotating Device ID Unique ID will be copied
203 : * According to specification input size of span buffer should be declared with at least 16 Bytes
204 : * length The size of uniqueIdSpan is reduced to actual value on success
205 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
206 : * if access fails.
207 : */
208 : virtual CHIP_ERROR GetRotatingDeviceIdUniqueId(MutableByteSpan & uniqueIdSpan) = 0;
209 :
210 : /**
211 : * @brief Obtain the product's finish from the device's factory data.
212 : *
213 : * If the product finish is not available, this should return
214 : * CHIP_ERROR_NOT_IMPLEMENTED, and the Basic Information ProductAppearance attribute should
215 : * not be implemented for the device.
216 : */
217 0 : virtual CHIP_ERROR GetProductFinish(app::Clusters::BasicInformation::ProductFinishEnum * finish)
218 : {
219 0 : return CHIP_ERROR_NOT_IMPLEMENTED;
220 : }
221 :
222 : /**
223 : * @brief Obtain the product's primary color from the device's factory data.
224 : *
225 : * If the primary color finish is not available or does not exist (e.g. the
226 : * device wants to return null for the color in the Basic Information
227 : * ProductAppearance attribute), this should return CHIP_ERROR_NOT_IMPLEMENTED.
228 : */
229 0 : virtual CHIP_ERROR GetProductPrimaryColor(app::Clusters::BasicInformation::ColorEnum * primaryColor)
230 : {
231 0 : return CHIP_ERROR_NOT_IMPLEMENTED;
232 : }
233 :
234 : /**
235 : * @brief Retrieves the current Joint Fabric mode.
236 : *
237 : * This method is intended to provide the current Joint Fabric Mode value when the node is capable of being a Joint Fabric
238 : * Administrator.
239 : * By default, it returns CHIP_ERROR_NOT_IMPLEMENTED and does not modify the output parameter.
240 : *
241 : * @param[out] jointFabricMode Reference to a uint8_t variable where the joint fabric mode will be stored.
242 : * @returns CHIP_NO_ERROR on success or CHIP_ERROR_NOT_IMPLEMENTED when device is not capable of being a Joint Fabric
243 : * Administrator.
244 : */
245 0 : virtual CHIP_ERROR GetJointFabricMode(uint8_t & jointFabricMode) { return CHIP_ERROR_NOT_IMPLEMENTED; }
246 :
247 : /**
248 : * @brief Obtain the current value of LocalConfigDisabled flag
249 : *
250 : * This method provides the value of the LocalConfigDisabled flag, whether it is implemented by the device or not.
251 : * This is so other system delegates can access this value without needing to access it from a global cluster instance
252 : * (which in this case would mean getting it from the basic information cluster).
253 : *
254 : * @returns CHIP_NO_ERROR on success (which is returned here by default).
255 : */
256 4 : virtual CHIP_ERROR GetLocalConfigDisabled(bool & localConfigDisabled)
257 : {
258 4 : localConfigDisabled = mLocalConfigDisabled;
259 4 : return CHIP_NO_ERROR;
260 : }
261 :
262 : /**
263 : * @brief Set the current value of LocalConfigDisabled flag
264 : *
265 : * @param[in] localConfigDisabled the new value of to set mLocalConfigDisabled to.
266 : * @returns CHIP_NO_ERROR on success (which is returned here by default).
267 : */
268 7 : virtual CHIP_ERROR SetLocalConfigDisabled(bool localConfigDisabled)
269 : {
270 7 : mLocalConfigDisabled = localConfigDisabled;
271 7 : return CHIP_NO_ERROR;
272 : }
273 :
274 : /**
275 : * Get information that is used to report capability minima values for the device.
276 : * @retval An instance of the DeviceInfoCapabilityMinimas struct
277 : */
278 1 : virtual DeviceInfoCapabilityMinimas GetSupportedCapabilityMinimaValues()
279 : {
280 : static_assert(CHIP_IM_MAX_NUM_COMMAND_HANDLER >= 1 && CHIP_IM_MAX_NUM_COMMAND_HANDLER <= 10000,
281 : "CHIP_IM_MAX_NUM_COMMAND_HANDLER must be greater than or equal to 1 and less than or equal to 10000");
282 : static_assert(CHIP_IM_MAX_NUM_WRITE_HANDLER >= 1 && CHIP_IM_MAX_NUM_WRITE_HANDLER <= 10000,
283 : "CHIP_IM_MAX_NUM_WRITE_HANDLER must be greater than or equal to 1 and less than or equal to 10000");
284 : static_assert(
285 : CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_READS >= 9 && CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_READS <= 10000,
286 : "CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_READS must be greater than or equal to 9 and less than or equal to 10000");
287 : static_assert(CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_SUBSCRIPTIONS >= 3 &&
288 : CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_SUBSCRIPTIONS <= 10000,
289 : "CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_SUBSCRIPTIONS must be greater than or equal to 3 and less than or "
290 : "equal to 10000");
291 :
292 : return DeviceInfoCapabilityMinimas{ .simultaneousInvocationsSupported = CHIP_IM_MAX_NUM_COMMAND_HANDLER,
293 : .simultaneousWritesSupported = CHIP_IM_MAX_NUM_WRITE_HANDLER,
294 : .readPathsSupported = CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_READS,
295 1 : .subscribePathsSupported = CHIP_IM_SERVER_MAX_NUM_PATH_GROUPS_FOR_SUBSCRIPTIONS };
296 : }
297 :
298 : protected:
299 : bool mLocalConfigDisabled = false;
300 : };
301 :
302 : /**
303 : * Instance getter for the global DeviceInstanceInfoProvider.
304 : *
305 : * Callers have to externally synchronize usage of this function.
306 : *
307 : * @return The pointer to global device instance info provider. Assume never null.
308 : */
309 : DeviceInstanceInfoProvider * GetDeviceInstanceInfoProvider();
310 :
311 : /**
312 : * Instance setter for the global DeviceInstanceInfoProvider.
313 : *
314 : * Callers have to externally synchronize usage of this function.
315 : *
316 : * If the `provider` is nullptr, no change is done.
317 : *
318 : * @param[in] provider the DeviceInstanceInfoProvider pointer to start returning with the getter
319 : */
320 : void SetDeviceInstanceInfoProvider(DeviceInstanceInfoProvider * provider);
321 :
322 : #if CONFIG_BUILD_FOR_HOST_UNIT_TEST
323 :
324 : DeviceInstanceInfoProvider * TestOnlyTryGetDeviceInstanceInfoProvider();
325 : #endif // CONFIG_BUILD_FOR_HOST_UNIT_TEST
326 :
327 : } // namespace DeviceLayer
328 : } // namespace chip
|
