Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2024 Project CHIP Authors
4 : * All rights reserved.
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 : #pragma once
20 :
21 : #include <stdint.h>
22 :
23 : #include <lib/core/CHIPError.h>
24 : #include <lib/core/Optional.h>
25 :
26 : namespace chip {
27 : namespace app {
28 :
29 : /**
30 : * @brief Represents a pair of terms and conditions value and version.
31 : *
32 : * This class encapsulates terms and conditions with methods to validate a user's accepted value and version against required
33 : * criteria.
34 : */
35 : class TermsAndConditions
36 : {
37 : public:
38 24 : TermsAndConditions(uint16_t inValue, uint16_t inVersion) : value(inValue), version(inVersion) {}
39 :
40 : bool operator==(const TermsAndConditions & other) const { return value == other.value && version == other.version; }
41 : bool operator!=(const TermsAndConditions & other) const { return !(*this == other); }
42 :
43 : /**
44 : * @brief Retrieves the terms and conditions value (accepted bits).
45 : *
46 : * @return The value of the terms and conditions.
47 : */
48 19 : uint16_t GetValue() const { return value; }
49 :
50 : /**
51 : * @brief Retrieves the terms and conditions version.
52 : *
53 : * @return The version of the terms and conditions.
54 : */
55 19 : uint16_t GetVersion() const { return version; }
56 :
57 : /**
58 : * @brief Validates the terms and conditions value.
59 : *
60 : * Checks whether all required bits are set in the accepted terms and conditions.
61 : *
62 : * @param acceptedTermsAndConditions The user's accepted terms and conditions.
63 : * @return True if all required bits are set, false otherwise.
64 : */
65 0 : bool ValidateValue(const TermsAndConditions & acceptedTermsAndConditions) const
66 : {
67 : // Check if all required bits are set in the user-accepted value.
68 0 : return ((value & acceptedTermsAndConditions.GetValue()) == value);
69 : }
70 :
71 : /**
72 : * @brief Validates the terms and conditions version.
73 : *
74 : * Checks whether the accepted version is greater than or equal to the required version.
75 : *
76 : * @param acceptedTermsAndConditions The user's accepted terms and conditions.
77 : * @return True if the accepted version is valid, false otherwise.
78 : */
79 0 : bool ValidateVersion(const TermsAndConditions & acceptedTermsAndConditions) const
80 : {
81 : // Check if the version is below the minimum required version.
82 0 : return (acceptedTermsAndConditions.GetVersion() >= version);
83 : }
84 :
85 : /**
86 : * @brief Validates the terms and conditions.
87 : *
88 : * Combines validation of both value and version to ensure compliance with requirements.
89 : *
90 : * @param acceptedTermsAndConditions The user's accepted terms and conditions.
91 : * @return True if both value and version validations pass, false otherwise.
92 : */
93 0 : bool Validate(const TermsAndConditions & acceptedTermsAndConditions) const
94 : {
95 0 : return ValidateVersion(acceptedTermsAndConditions) && ValidateValue(acceptedTermsAndConditions);
96 : }
97 :
98 : private:
99 : const uint16_t value;
100 : const uint16_t version;
101 : };
102 :
103 : /**
104 : * @brief Data access layer for handling the required terms and conditions and managing user acceptance status.
105 : *
106 : * This class provides methods to manage the acceptance of terms and conditions, including storing, retrieving,
107 : * and verifying the acceptance status. It also supports temporary in-memory storage and persistent storage for
108 : * accepted terms and conditions.
109 : */
110 : class TermsAndConditionsProvider
111 : {
112 : public:
113 113 : virtual ~TermsAndConditionsProvider() = default;
114 :
115 : /**
116 : * @brief Persists the acceptance of the terms and conditions.
117 : *
118 : * This method commits the in-memory acceptance status to persistent storage. It stores the acceptance
119 : * status in a permanent location and clears the temporary in-memory acceptance state after committing.
120 : *
121 : * @retval CHIP_NO_ERROR if the terms were successfully persisted.
122 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
123 : * @retval CHIP_ERROR_* for other errors.
124 : */
125 : virtual CHIP_ERROR CommitAcceptance() = 0;
126 :
127 : /**
128 : * @brief Retrieves the current acceptance status of the terms and conditions.
129 : *
130 : * This method checks the temporary in-memory acceptance state first. If no in-memory state is found,
131 : * it attempts to retrieve the acceptance status from persistent storage. If no terms have been accepted,
132 : * it returns an empty `Optional`.
133 : *
134 : * @param[out] outTermsAndConditions The current accepted terms and conditions, if any.
135 : *
136 : * @retval CHIP_NO_ERROR if the terms were successfully retrieved or no terms were found.
137 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
138 : * @retval CHIP_ERROR_* for other errors.
139 : */
140 : virtual CHIP_ERROR GetAcceptance(Optional<TermsAndConditions> & outTermsAndConditions) const = 0;
141 :
142 : /**
143 : * @brief Determines if acknowledgments are required.
144 : *
145 : * @param[out] outAcknowledgementsRequired True if acknowledgments are required, false otherwise.
146 : *
147 : * @retval CHIP_NO_ERROR if successful.
148 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
149 : * @retval CHIP_ERROR_* for other errors.
150 : */
151 : virtual CHIP_ERROR GetAcknowledgementsRequired(bool & outAcknowledgementsRequired) const = 0;
152 :
153 : /**
154 : * @brief Retrieves the requirements for the terms and conditions.
155 : *
156 : * This method retrieves the required terms and conditions that must be accepted by the user. These
157 : * requirements are set by the provider and used to validate the acceptance.
158 : *
159 : * @param[out] outTermsAndConditions The required terms and conditions.
160 : *
161 : * @retval CHIP_NO_ERROR if the required terms were successfully retrieved.
162 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
163 : * @retval CHIP_ERROR_* for other errors.
164 : */
165 : virtual CHIP_ERROR GetRequirements(Optional<TermsAndConditions> & outTermsAndConditions) const = 0;
166 :
167 : /**
168 : * @brief Retrieves the deadline for accepting updated terms and conditions.
169 : *
170 : * This method retrieves the deadline by which the user must accept updated terms and conditions.
171 : * If no deadline is set, it returns an empty `Optional`.
172 : *
173 : * @param[out] outUpdateAcceptanceDeadline The deadline (in seconds) by which updated terms must be accepted.
174 : * Returns empty Optional if no deadline is set.
175 : *
176 : * @retval CHIP_NO_ERROR if the deadline was successfully retrieved or no deadline was found.
177 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
178 : * @retval CHIP_ERROR_* for other errors.
179 : */
180 : virtual CHIP_ERROR GetUpdateAcceptanceDeadline(Optional<uint32_t> & outUpdateAcceptanceDeadline) const = 0;
181 :
182 : /**
183 : * @brief Resets the persisted acceptance status.
184 : *
185 : * This method deletes the persisted acceptance of the terms and conditions from storage, effectively
186 : * resetting the stored acceptance status. Any in-memory temporary acceptance will also be cleared
187 : * through this method.
188 : *
189 : * @retval CHIP_NO_ERROR if the terms were successfully reset.
190 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
191 : * @retval CHIP_ERROR_* for other errors.
192 : */
193 : virtual CHIP_ERROR ResetAcceptance() = 0;
194 :
195 : /**
196 : * @brief Clears the in-memory temporary acceptance status.
197 : *
198 : * This method clears any temporary acceptance of the terms and conditions that is held in-memory. It does
199 : * not affect the persisted state stored in storage.
200 : *
201 : * @retval CHIP_NO_ERROR if the in-memory acceptance state was successfully cleared.
202 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
203 : * @retval CHIP_ERROR_* for other errors.
204 : */
205 : virtual CHIP_ERROR RevertAcceptance() = 0;
206 :
207 : /**
208 : * @brief Sets the temporary in-memory acceptance status of the terms and conditions.
209 : *
210 : * This method stores the provided terms and conditions acceptance status in-memory. It does not persist
211 : * the acceptance status to storage. To persist the acceptance, call `CommitAcceptance()` after this method.
212 : *
213 : * @param[in] inTermsAndConditions The terms and conditions to be accepted temporarily.
214 : *
215 : * @retval CHIP_NO_ERROR if the terms were successfully stored in-memory.
216 : * @retval CHIP_ERROR_INVALID_ARGUMENT if the provided terms and conditions are invalid.
217 : * @retval CHIP_ERROR_UNINITIALIZED if the module has not been initialized.
218 : * @retval CHIP_ERROR_* for other errors.
219 : */
220 : virtual CHIP_ERROR SetAcceptance(const Optional<TermsAndConditions> & inTermsAndConditions) = 0;
221 : };
222 :
223 : } // namespace app
224 : } // namespace chip
|
