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 82 : DeviceInstanceInfoProvider() = default;
30 82 : virtual ~DeviceInstanceInfoProvider() = default;
31 :
32 : /**
33 : * @brief Obtain the Vendor Name from the device's factory data.
34 : *
35 : * @param[out] buf Buffer to copy string.
36 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
37 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
38 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
39 : * This size should be +1 higher than maximum possible string.
40 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
41 : * if access fails.
42 : */
43 : virtual CHIP_ERROR GetVendorName(char * buf, size_t bufSize) = 0;
44 :
45 : /**
46 : * @brief Obtain the Vendor Id from the device's factory data.
47 : *
48 : * @param[out] vendorId Reference to location where the vendor id integer will be copied
49 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
50 : * if access fails.
51 : */
52 : virtual CHIP_ERROR GetVendorId(uint16_t & vendorId) = 0;
53 :
54 : /**
55 : * @brief Obtain the Product Name from the device's factory data.
56 : *
57 : * @param[in, out] buf Buffer to copy string.
58 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
59 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
60 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
61 : * This size should be +1 higher than maximum possible string.
62 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
63 : * if access fails.
64 : */
65 : virtual CHIP_ERROR GetProductName(char * buf, size_t bufSize) = 0;
66 :
67 : /**
68 : * @brief Obtain the Product Id from the device's factory data.
69 : *
70 : * @param[out] productId Reference to location where the product id integer will be copied
71 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
72 : * if access fails.
73 : */
74 : virtual CHIP_ERROR GetProductId(uint16_t & productId) = 0;
75 :
76 : /**
77 : * @brief Obtain Part Number from the device factory data.
78 : *
79 : * @param[out] buf Buffer to store the null-terminated result string.
80 : * @param[in] bufSize Size of the buffer. The buffer should allow for fitting in Part Number
81 : * (max 32 characters) and the null terminator.
82 : **/
83 : virtual CHIP_ERROR GetPartNumber(char * buf, size_t bufSize) = 0;
84 :
85 : /**
86 : * @brief Obtain Product URL from the device factory data.
87 : *
88 : * @param[out] buf Buffer to store the null-terminated result string.
89 : * @param[in] bufSize Size of the buffer. The buffer should allow for fitting in Product URL
90 : * (max 256 characters) and the null terminator.
91 : **/
92 : virtual CHIP_ERROR GetProductURL(char * buf, size_t bufSize) = 0;
93 :
94 : /**
95 : * @brief Obtain Product Label from the device factory data.
96 : *
97 : * @param[out] buf Buffer to store the null-terminated result string.
98 : * @param[in] bufSize Size of the buffer. The buffer should allow for fitting in Product Label
99 : * (max 64 characters) and the null terminator.
100 : **/
101 : virtual CHIP_ERROR GetProductLabel(char * buf, size_t bufSize) = 0;
102 :
103 : /**
104 : * @brief Obtain the Serial Number from the device's factory data.
105 : *
106 : * The SerialNumber attribute specifies a human readable serial number
107 : *
108 : * @param[in, out] buf Buffer to copy string.
109 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
110 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
111 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
112 : * This size should be +1 higher than maximum possible string.
113 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
114 : * if access fails.
115 : */
116 : virtual CHIP_ERROR GetSerialNumber(char * buf, size_t bufSize) = 0;
117 :
118 : /**
119 : * @brief Obtain a manufacturing date from the device's factory data.
120 : *
121 : * The ManufacturingDate attribute specifies the date that the Node was manufactured.
122 : * Output values are returned in ISO 8601, where:
123 : * The first month of the year is January and its returning value is equal to 1.
124 : * The first day of a month starts from 1.
125 : *
126 : * @param[out] year Reference to location where manufacturing year will be stored
127 : * @param[out] month 1-based value [range 1-12] Reference to location where manufacturing month will be stored
128 : * @param[out] day 1-based value [range 1-31] Reference to location where manufacturing day will be stored
129 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
130 : * if access fails.
131 : */
132 : virtual CHIP_ERROR GetManufacturingDate(uint16_t & year, uint8_t & month, uint8_t & day) = 0;
133 :
134 : /**
135 : * @brief Obtain a Hardware Version from the device's factory data.
136 : *
137 : * @param[out] hardwareVersion Reference to location where the hardware version integer will be copied
138 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
139 : * if access fails.
140 : */
141 : virtual CHIP_ERROR GetHardwareVersion(uint16_t & hardwareVersion) = 0;
142 :
143 : /**
144 : * @brief Obtain a Hardware Version String from the device's factory data.
145 : *
146 : * The HardwareVersionString can be used to provide a more user-friendly value than that
147 : * represented by the HardwareVersion attribute.
148 : *
149 : * @param[in, out] buf Buffer to copy string.
150 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
151 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
152 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
153 : * This size should be +1 higher than maximum possible string.
154 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_BUFFER_TOO_SMALL if the buffer was too small to fit string and null
155 : * terminating. or another CHIP_ERROR from the underlying implementation if access fails.
156 : */
157 : virtual CHIP_ERROR GetHardwareVersionString(char * buf, size_t bufSize) = 0;
158 :
159 : /**
160 : * @brief Obtain a Rotating Device ID Unique ID from the device's factory data.
161 : *
162 : * The unique identifier consists of a randomly-generated 128-bit or longer octet string which
163 : * was programmed during factory provisioning or delivered to the device by the vendor using
164 : * secure means after a software update.
165 : *
166 : * @param[out] uniqueIdSpan Reference to location where the Rotating Device ID Unique ID will be copied
167 : * According to specification input size of span buffer should be declared with at least 16 Bytes
168 : * length The size of uniqueIdSpan is reduced to actual value on success
169 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
170 : * if access fails.
171 : */
172 : virtual CHIP_ERROR GetRotatingDeviceIdUniqueId(MutableByteSpan & uniqueIdSpan) = 0;
173 :
174 : /**
175 : * @brief Obtain the product's finish from the device's factory data.
176 : *
177 : * If the product finish is not available, this should return
178 : * CHIP_ERROR_NOT_IMPLEMENTED, and the Basic Information ProductAppearance attribute should
179 : * not be implemented for the device.
180 : */
181 0 : virtual CHIP_ERROR GetProductFinish(app::Clusters::BasicInformation::ProductFinishEnum * finish)
182 : {
183 0 : return CHIP_ERROR_NOT_IMPLEMENTED;
184 : }
185 :
186 : /**
187 : * @brief Obtain the product's primary color from the device's factory data.
188 : *
189 : * If the primary color finish is not available or does not exist (e.g. the
190 : * device wants to return null for the color in the Basic Information
191 : * ProductAppearance attribute), this should return CHIP_ERROR_NOT_IMPLEMENTED.
192 : */
193 0 : virtual CHIP_ERROR GetProductPrimaryColor(app::Clusters::BasicInformation::ColorEnum * primaryColor)
194 : {
195 0 : return CHIP_ERROR_NOT_IMPLEMENTED;
196 : }
197 :
198 : /**
199 : * @brief Obtain a Software Version String from the device's factory data.
200 : *
201 : * The SoftwareVersionString can be used to provide a more user-friendly value than that
202 : * represented by the SoftwareVersion attribute.
203 : *
204 : * @param[in, out] buf Buffer to copy string.
205 : * On CHIP_NO_ERROR return from this function this buffer will be null-terminated.
206 : * On error CHIP_ERROR_BUFFER_TOO_SMALL there is no guarantee that buffer will be null-terminated.
207 : * @param[in] bufSize Size of data, including the null terminator, that can be written to buf.
208 : * This size should be +1 higher than maximum possible string.
209 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
210 : * if access fails.
211 : */
212 0 : virtual CHIP_ERROR GetSoftwareVersionString(char * buf, size_t bufSize) { return CHIP_ERROR_NOT_IMPLEMENTED; }
213 :
214 : /**
215 : * @brief Retrieves the current Joint Fabric mode.
216 : *
217 : * This method is intended to provide the current Joint Fabric Mode value when the node is capable of being a Joint Fabric
218 : * Administrator.
219 : * By default, it returns CHIP_ERROR_NOT_IMPLEMENTED and does not modify the output parameter.
220 : *
221 : * @param[out] jointFabricMode Reference to a uint8_t variable where the joint fabric mode will be stored.
222 : * @returns CHIP_NO_ERROR on success or CHIP_ERROR_NOT_IMPLEMENTED when device is not capable of being a Joint Fabric
223 : * Administrator.
224 : */
225 0 : virtual CHIP_ERROR GetJointFabricMode(uint8_t & jointFabricMode) { return CHIP_ERROR_NOT_IMPLEMENTED; }
226 : };
227 :
228 : /**
229 : * Instance getter for the global DeviceInstanceInfoProvider.
230 : *
231 : * Callers have to externally synchronize usage of this function.
232 : *
233 : * @return The pointer to global device instance info provider. Assume never null.
234 : */
235 : DeviceInstanceInfoProvider * GetDeviceInstanceInfoProvider();
236 :
237 : /**
238 : * Instance setter for the global DeviceInstanceInfoProvider.
239 : *
240 : * Callers have to externally synchronize usage of this function.
241 : *
242 : * If the `provider` is nullptr, no change is done.
243 : *
244 : * @param[in] provider the DeviceInstanceInfoProvider pointer to start returning with the getter
245 : */
246 : void SetDeviceInstanceInfoProvider(DeviceInstanceInfoProvider * provider);
247 :
248 : } // namespace DeviceLayer
249 : } // namespace chip
|
