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 <algorithm>
20 : #include <stdint.h>
21 : #include <sys/types.h>
22 :
23 : #include <app-common/zap-generated/cluster-objects.h>
24 : #include <app/util/basic-types.h>
25 : #include <lib/core/CHIPError.h>
26 : #include <lib/core/CHIPPersistentStorageDelegate.h>
27 : #include <lib/support/Span.h>
28 :
29 : namespace chip {
30 : namespace DeviceLayer {
31 :
32 : static constexpr size_t kMaxUserLabelListLength = 4;
33 : static constexpr size_t kMaxLabelNameLength = 16;
34 : static constexpr size_t kMaxLabelValueLength = 16;
35 : static constexpr size_t kMaxActiveLocaleLength = 35;
36 :
37 : class DeviceInfoProvider
38 : {
39 : public:
40 : /**
41 : * Template used to iterate the stored group data
42 : */
43 : template <typename T>
44 : class Iterator
45 : {
46 : public:
47 6 : virtual ~Iterator() = default;
48 : /**
49 : * @retval The number of entries in total that will be iterated.
50 : */
51 : virtual size_t Count() = 0;
52 : /**
53 : * @param[out] item Value associated with the next element in the iteration.
54 : * @retval true if the next entry is successfully retrieved.
55 : * @retval false if no more entries can be found.
56 : */
57 : virtual bool Next(T & item) = 0;
58 : /**
59 : * Release the memory allocated by this iterator.
60 : * Must be called before the pointer goes out of scope.
61 : */
62 : virtual void Release() = 0;
63 :
64 : protected:
65 6 : Iterator() = default;
66 : };
67 :
68 : using FixedLabelType = app::Clusters::FixedLabel::Structs::LabelStruct::Type;
69 : using UserLabelType = app::Clusters::UserLabel::Structs::LabelStruct::Type;
70 : using CalendarType = app::Clusters::TimeFormatLocalization::CalendarTypeEnum;
71 :
72 : using FixedLabelIterator = Iterator<FixedLabelType>;
73 : using UserLabelIterator = Iterator<UserLabelType>;
74 : using SupportedLocalesIterator = Iterator<CharSpan>;
75 : using SupportedCalendarTypesIterator = Iterator<CalendarType>;
76 :
77 9 : DeviceInfoProvider() = default;
78 :
79 9 : virtual ~DeviceInfoProvider() = default;
80 :
81 : // Not copyable
82 : DeviceInfoProvider(const DeviceInfoProvider &) = delete;
83 : DeviceInfoProvider & operator=(const DeviceInfoProvider &) = delete;
84 :
85 : /**
86 : * @brief Set the storage implementation used for non-volatile storage of device information data.
87 : *
88 : * @param storage Pointer to storage instance to set. Cannot be nullptr, will assert.
89 : */
90 : void SetStorageDelegate(PersistentStorageDelegate * storage);
91 :
92 : /**
93 : * @brief Sets the user label list for a specified endpoint.
94 : *
95 : * Replaces the current user label list with a new list. If the new list is smaller
96 : * than the existing one, excess labels are deleted to free up space.
97 : *
98 : * @param[in] endpoint The endpoint ID associated with the user label list.
99 : * @param[in] labelList The new list of user labels to store.
100 : *
101 : * @return CHIP_NO_ERROR on success.
102 : * @return CHIP_ERROR if an error occurs.
103 : */
104 : CHIP_ERROR SetUserLabelList(EndpointId endpoint, Span<const UserLabelType> labelList);
105 :
106 : /**
107 : * @brief Clears the user label list for a specified endpoint.
108 : *
109 : * Deletes all user labels associated with the given endpoint, resetting the list length to zero.
110 : * If no previous list exists, this function has no effect.
111 : *
112 : * @param[in] endpoint The endpoint ID whose user label list will be cleared.
113 : *
114 : * @return CHIP_NO_ERROR on success or if no previous value exists.
115 : * @return CHIP_ERROR if an error occurs during deletion.
116 : */
117 : CHIP_ERROR ClearUserLabelList(EndpointId endpoint);
118 :
119 : /**
120 : * @brief Appends a user label to the user label list for a specified endpoint.
121 : *
122 : * Adds a new label to the end of the existing user label list. The list size must not
123 : * exceed `kMaxUserLabelListLength`. If the list is full, the function returns an error.
124 : *
125 : * @param[in] endpoint The endpoint ID to which the user label will be added.
126 : * @param[in] label The user label to append to the list.
127 : *
128 : * @return CHIP_NO_ERROR on success.
129 : * @return CHIP_ERROR_NO_MEMORY if the list is already at its maximum size.
130 : * @return CHIP_ERROR if an error occurs during storage.
131 : */
132 : CHIP_ERROR AppendUserLabel(EndpointId endpoint, const UserLabelType & label);
133 :
134 : // Iterators
135 : /**
136 : * Creates an iterator that may be used to obtain the list of labels associated with the given endpoint.
137 : * In order to release the allocated memory, the Release() method must be called after the iteration is finished.
138 : * Modifying the label during the iteration is currently not supported, and may yield unexpected behaviour.
139 : * @retval An instance of EndpointIterator on success
140 : * @retval nullptr if no iterator instances are available.
141 : */
142 : virtual FixedLabelIterator * IterateFixedLabel(EndpointId endpoint) = 0;
143 : virtual UserLabelIterator * IterateUserLabel(EndpointId endpoint) = 0;
144 :
145 : /**
146 : * Creates an iterator that may be used to obtain the list of supported locales of the device.
147 : * In order to release the allocated memory, the Release() method must be called after the iteration is finished.
148 : * @retval An instance of EndpointIterator on success
149 : * @retval nullptr if no iterator instances are available.
150 : */
151 : virtual SupportedLocalesIterator * IterateSupportedLocales() = 0;
152 :
153 : /**
154 : * Creates an iterator that may be used to obtain the list of supported calendar types of the device.
155 : * In order to release the allocated memory, the Release() method must be called after the iteration is finished.
156 : * @retval An instance of EndpointIterator on success
157 : * @retval nullptr if no iterator instances are available.
158 : */
159 : virtual SupportedCalendarTypesIterator * IterateSupportedCalendarTypes() = 0;
160 :
161 : protected:
162 : PersistentStorageDelegate * mStorage = nullptr;
163 :
164 : /**
165 : * @brief Set the UserLabel at the specified index of the UserLabelList on a given endpoint
166 : *
167 : * @param endpoint - id to UserLabelList on which to set the UserLabel.
168 : * @param index - index within the UserLabelList for which to set the UserLabel.
169 : * @param userLabel - user label to set.
170 : * @return CHIP_NO_ERROR on success, CHIP_ERROR_INVALID_KEY_ID if index exceed the range (Total length - 1),
171 : * or other CHIP_ERROR values from implementation on other errors.
172 : */
173 : virtual CHIP_ERROR SetUserLabelAt(EndpointId endpoint, size_t index, const UserLabelType & userLabel) = 0;
174 :
175 : /**
176 : * @brief Delete the UserLabel at the specified index of the UserLabelList on a given endpoint
177 : *
178 : * @param endpoint - id to UserLabelList on which to delete the UserLabel.
179 : * @param index - index within the UserLabelList for which to remove the UserLabel.
180 : * @return CHIP_NO_ERROR on success, CHIP_ERROR_INVALID_KEY_ID if index exceed the range (Total length - 1),
181 : * or other CHIP_ERROR values from implementation on other errors.
182 : */
183 : virtual CHIP_ERROR DeleteUserLabelAt(EndpointId endpoint, size_t index) = 0;
184 :
185 : /**
186 : * @brief Set the total length of the UserLabelList on a given endpoint
187 : *
188 : * @param endpoint - id of the UserLabelList.
189 : * @param val - total count of the UserLabelList.
190 : * @return CHIP_NO_ERROR on success, other CHIP_ERROR values from implementation on other errors.
191 : */
192 : virtual CHIP_ERROR SetUserLabelLength(EndpointId endpoint, size_t val) = 0;
193 :
194 : /**
195 : * @brief Get the total length of the UserLabelList on a given endpoint
196 : *
197 : * @param endpoint - id of the UserLabelList.
198 : * @param val - output of the total count of the UserLabelList.
199 : * @return CHIP_NO_ERROR on success, other CHIP_ERROR values from implementation on other errors.
200 : */
201 : virtual CHIP_ERROR GetUserLabelLength(EndpointId endpoint, size_t & val) = 0;
202 : };
203 :
204 : /**
205 : * Instance getter for the global DeviceInfoProvider.
206 : *
207 : * Callers have to externally synchronize usage of this function.
208 : *
209 : * @return The global Device Info Provider.
210 : */
211 : DeviceInfoProvider * GetDeviceInfoProvider();
212 :
213 : /**
214 : * Instance setter for the global DeviceInfoProvider.
215 : *
216 : * Callers have to externally synchronize usage of this function.
217 : *
218 : * @param[in] provider the Device Info Provider
219 : */
220 : void SetDeviceInfoProvider(DeviceInfoProvider * provider);
221 :
222 : } // namespace DeviceLayer
223 : } // namespace chip
|
