1//
2// Copyright (C) 2012 The Android Open Source Project
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//      http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15//
16
17#ifndef SHILL_PROPERTY_STORE_H_
18#define SHILL_PROPERTY_STORE_H_
19
20#include <map>
21#include <string>
22#include <vector>
23
24#include <base/callback.h>
25#include <base/macros.h>
26#include <brillo/any.h>
27#include <brillo/variant_dictionary.h>
28
29#include "shill/accessor_interface.h"
30#include "shill/property_iterator.h"
31
32namespace shill {
33
34class Error;
35
36class PropertyStore {
37 public:
38  typedef base::Callback<void(const std::string&)> PropertyChangeCallback;
39  PropertyStore();
40  explicit PropertyStore(PropertyChangeCallback property_change_callback);
41  virtual ~PropertyStore();
42
43  virtual bool Contains(const std::string& property) const;
44
45  // Setting properties using brillo::Any variant type.
46  bool SetAnyProperty(const std::string& name,
47                      const brillo::Any& value,
48                      Error* error);
49  bool SetProperties(const brillo::VariantDictionary& in, Error* error);
50
51  // Retrieve all properties and store them in a brillo::VariantDictionary
52  // (std::map<std::string, brillo::Any>).
53  bool GetProperties(brillo::VariantDictionary* out, Error* error) const;
54
55  // Methods to allow the getting of properties stored in the referenced
56  // |store_| by name. Upon success, these methods return true and return the
57  // property value in |value|. Upon failure, they return false and
58  // leave |value| untouched.
59  bool GetBoolProperty(const std::string& name, bool* value,
60                       Error* error) const;
61  bool GetInt16Property(const std::string& name, int16_t* value,
62                        Error* error) const;
63  bool GetInt32Property(const std::string& name, int32_t* value,
64                        Error* error) const;
65  bool GetKeyValueStoreProperty(const std::string& name, KeyValueStore* value,
66                                Error* error) const;
67  bool GetStringProperty(const std::string& name, std::string* value,
68                         Error* error) const;
69  bool GetStringmapProperty(const std::string& name, Stringmap* values,
70                            Error* error) const;
71  bool GetStringmapsProperty(const std::string& name, Stringmaps* values,
72                             Error* error) const;
73  bool GetStringsProperty(const std::string& name, Strings* values,
74                          Error* error) const;
75  bool GetUint8Property(const std::string& name, uint8_t* value,
76                        Error* error) const;
77  bool GetByteArrayProperty(const std::string& name, ByteArray* value,
78                            Error *error) const;
79  bool GetUint16Property(const std::string& name, uint16_t* value,
80                         Error* error) const;
81  bool GetUint16sProperty(const std::string& name, Uint16s* value,
82                          Error* error) const;
83  bool GetUint32Property(const std::string& name, uint32_t* value,
84                         Error* error) const;
85  bool GetUint64Property(const std::string& name, uint64_t* value,
86                         Error* error) const;
87  bool GetRpcIdentifierProperty(const std::string& name, RpcIdentifier* value,
88                                Error* error) const;
89
90  // Methods to allow the setting, by name, of properties stored in this object.
91  // The property names are declared in chromeos/dbus/service_constants.h,
92  // so that they may be shared with libcros.
93  // If the property is successfully changed, these methods return true,
94  // and leave |error| untouched.
95  // If the property is unchanged because it already has the desired value,
96  // these methods return false, and leave |error| untouched.
97  // If the property change fails, these methods return false, and update
98  // |error|. However, updating |error| is skipped if |error| is NULL.
99  virtual bool SetBoolProperty(const std::string& name,
100                               bool value,
101                               Error* error);
102
103  virtual bool SetInt16Property(const std::string& name,
104                                int16_t value,
105                                Error* error);
106
107  virtual bool SetInt32Property(const std::string& name,
108                                int32_t value,
109                                Error* error);
110
111  virtual bool SetKeyValueStoreProperty(const std::string& name,
112                                        const KeyValueStore& value,
113                                        Error* error);
114
115  virtual bool SetStringProperty(const std::string& name,
116                                 const std::string& value,
117                                 Error* error);
118
119  virtual bool SetStringmapProperty(
120      const std::string& name,
121      const std::map<std::string, std::string>& values,
122      Error* error);
123
124  virtual bool SetStringmapsProperty(
125      const std::string& name,
126      const std::vector<std::map<std::string, std::string>>& values,
127      Error* error);
128
129  virtual bool SetStringsProperty(const std::string& name,
130                                  const std::vector<std::string>& values,
131                                  Error* error);
132
133  virtual bool SetUint8Property(const std::string& name,
134                                uint8_t value,
135                                Error* error);
136
137  virtual bool SetByteArrayProperty(const std::string &name,
138                                    const ByteArray& value,
139                                    Error *error);
140
141  virtual bool SetUint16Property(const std::string& name,
142                                 uint16_t value,
143                                 Error* error);
144
145  virtual bool SetUint16sProperty(const std::string& name,
146                                  const std::vector<uint16_t>& value,
147                                  Error* error);
148
149  virtual bool SetUint32Property(const std::string& name,
150                                 uint32_t value,
151                                 Error* error);
152
153  virtual bool SetUint64Property(const std::string& name,
154                                 uint64_t value,
155                                 Error* error);
156
157  virtual bool SetRpcIdentifierProperty(const std::string& name,
158                                        const RpcIdentifier& value,
159                                        Error* error);
160
161  // Clearing a property resets it to its "factory" value. This value
162  // is generally the value that it (the property) had when it was
163  // registered with PropertyStore.
164  //
165  // The exception to this rule is write-only derived properties. For
166  // such properties, the property owner explicitly provides a
167  // "factory" value at registration time. This is necessary because
168  // PropertyStore can't read the current value at registration time.
169  //
170  // |name| is the key used to access the property. If the property
171  // cannot be cleared, |error| is set, and the method returns false.
172  // Otherwise, |error| is unchanged, and the method returns true.
173  virtual bool ClearProperty(const std::string& name, Error* error);
174
175  // Accessors for iterators over property maps. Useful for dumping all
176  // properties.
177  ReadablePropertyConstIterator<bool> GetBoolPropertiesIter() const;
178  ReadablePropertyConstIterator<int16_t> GetInt16PropertiesIter() const;
179  ReadablePropertyConstIterator<int32_t> GetInt32PropertiesIter() const;
180  ReadablePropertyConstIterator<KeyValueStore>
181      GetKeyValueStorePropertiesIter() const;
182  ReadablePropertyConstIterator<RpcIdentifier>
183    GetRpcIdentifierPropertiesIter() const;
184  ReadablePropertyConstIterator<RpcIdentifiers>
185    GetRpcIdentifiersPropertiesIter() const;
186  ReadablePropertyConstIterator<std::string> GetStringPropertiesIter() const;
187  ReadablePropertyConstIterator<Stringmap> GetStringmapPropertiesIter() const;
188  ReadablePropertyConstIterator<Stringmaps> GetStringmapsPropertiesIter() const;
189  ReadablePropertyConstIterator<Strings> GetStringsPropertiesIter() const;
190  ReadablePropertyConstIterator<uint8_t> GetUint8PropertiesIter() const;
191  ReadablePropertyConstIterator<ByteArray> GetByteArrayPropertiesIter() const;
192  ReadablePropertyConstIterator<uint16_t> GetUint16PropertiesIter() const;
193  ReadablePropertyConstIterator<Uint16s> GetUint16sPropertiesIter() const;
194  ReadablePropertyConstIterator<uint32_t> GetUint32PropertiesIter() const;
195  ReadablePropertyConstIterator<uint64_t> GetUint64PropertiesIter() const;
196
197  // Methods for registering a property.
198  //
199  // It is permitted to re-register a property (in which case the old
200  // binding is forgotten). However, the newly bound object must be of
201  // the same type.
202  //
203  // Note that types do not encode read-write permission.  Hence, it
204  // is possible to change permissions by rebinding a property to the
205  // same object.
206  //
207  // (Corollary of the rebinding-to-same-type restriction: a
208  // PropertyStore cannot hold two properties of the same name, but
209  // differing types.)
210  void RegisterBool(const std::string& name, bool* prop);
211  void RegisterConstBool(const std::string& name, const bool* prop);
212  void RegisterWriteOnlyBool(const std::string& name, bool* prop);
213  void RegisterInt16(const std::string& name, int16_t* prop);
214  void RegisterConstInt16(const std::string& name, const int16_t* prop);
215  void RegisterWriteOnlyInt16(const std::string& name, int16_t* prop);
216  void RegisterInt32(const std::string& name, int32_t* prop);
217  void RegisterConstInt32(const std::string& name, const int32_t* prop);
218  void RegisterWriteOnlyInt32(const std::string& name, int32_t* prop);
219  void RegisterUint32(const std::string& name, uint32_t* prop);
220  void RegisterConstUint32(const std::string& name, const uint32_t* prop);
221  void RegisterString(const std::string& name, std::string* prop);
222  void RegisterConstString(const std::string& name, const std::string* prop);
223  void RegisterWriteOnlyString(const std::string& name, std::string* prop);
224  void RegisterStringmap(const std::string& name, Stringmap* prop);
225  void RegisterConstStringmap(const std::string& name, const Stringmap* prop);
226  void RegisterWriteOnlyStringmap(const std::string& name, Stringmap* prop);
227  void RegisterStringmaps(const std::string& name, Stringmaps* prop);
228  void RegisterConstStringmaps(const std::string& name, const Stringmaps* prop);
229  void RegisterWriteOnlyStringmaps(const std::string& name, Stringmaps* prop);
230  void RegisterStrings(const std::string& name, Strings* prop);
231  void RegisterConstStrings(const std::string& name, const Strings* prop);
232  void RegisterWriteOnlyStrings(const std::string& name, Strings* prop);
233  void RegisterUint8(const std::string& name, uint8_t* prop);
234  void RegisterConstUint8(const std::string& name, const uint8_t* prop);
235  void RegisterWriteOnlyUint8(const std::string& name, uint8_t* prop);
236  void RegisterUint16(const std::string& name, uint16_t* prop);
237  void RegisterUint16s(const std::string& name, Uint16s* prop);
238  void RegisterConstUint16(const std::string& name, const uint16_t* prop);
239  void RegisterConstUint16s(const std::string& name, const Uint16s* prop);
240  void RegisterWriteOnlyUint16(const std::string& name, uint16_t* prop);
241  void RegisterByteArray(const std::string& name, ByteArray* prop);
242  void RegisterConstByteArray(const std::string& name, const ByteArray* prop);
243  void RegisterWriteOnlyByteArray(const std::string& name, ByteArray* prop);
244
245  void RegisterDerivedBool(const std::string& name,
246                           const BoolAccessor& accessor);
247  void RegisterDerivedInt32(const std::string& name,
248                            const Int32Accessor& accessor);
249  void RegisterDerivedKeyValueStore(const std::string& name,
250                                    const KeyValueStoreAccessor& accessor);
251  void RegisterDerivedRpcIdentifier(const std::string& name,
252                                    const RpcIdentifierAccessor& acc);
253  void RegisterDerivedRpcIdentifiers(const std::string& name,
254                                     const RpcIdentifiersAccessor& accessor);
255  void RegisterDerivedString(const std::string& name,
256                             const StringAccessor& accessor);
257  void RegisterDerivedStringmap(const std::string& name,
258                                const StringmapAccessor& accessor);
259  void RegisterDerivedStringmaps(const std::string& name,
260                                 const StringmapsAccessor& accessor);
261  void RegisterDerivedStrings(const std::string& name,
262                              const StringsAccessor& accessor);
263  void RegisterDerivedUint16(const std::string& name,
264                             const Uint16Accessor& accessor);
265  void RegisterDerivedUint64(const std::string& name,
266                             const Uint64Accessor& accessor);
267  void RegisterDerivedByteArray(const std::string& name,
268                                const ByteArrayAccessor& accessor);
269
270 private:
271  template <class V>
272  bool GetProperty(
273      const std::string& name,
274      V* value,
275      Error* error,
276      const std::map<std::string,
277                     std::shared_ptr<AccessorInterface<V>>>& collection,
278      const std::string& value_type_english) const;
279
280  template <class V>
281  bool SetProperty(
282      const std::string& name,
283      const V& value,
284      Error* error,
285      std::map<std::string, std::shared_ptr<AccessorInterface<V>>>* collection,
286      const std::string& value_type_english);
287
288  // These are std::maps instead of something cooler because the common
289  // operation is iterating through them and returning all properties.
290  std::map<std::string, BoolAccessor> bool_properties_;
291  std::map<std::string, Int16Accessor> int16_properties_;
292  std::map<std::string, Int32Accessor> int32_properties_;
293  std::map<std::string, KeyValueStoreAccessor> key_value_store_properties_;
294  std::map<std::string, RpcIdentifierAccessor> rpc_identifier_properties_;
295  std::map<std::string, RpcIdentifiersAccessor> rpc_identifiers_properties_;
296  std::map<std::string, StringAccessor> string_properties_;
297  std::map<std::string, StringmapAccessor> stringmap_properties_;
298  std::map<std::string, StringmapsAccessor> stringmaps_properties_;
299  std::map<std::string, StringsAccessor> strings_properties_;
300  std::map<std::string, Uint8Accessor> uint8_properties_;
301  std::map<std::string, ByteArrayAccessor> bytearray_properties_;
302  std::map<std::string, Uint16Accessor> uint16_properties_;
303  std::map<std::string, Uint16sAccessor> uint16s_properties_;
304  std::map<std::string, Uint32Accessor> uint32_properties_;
305  std::map<std::string, Uint64Accessor> uint64_properties_;
306
307  PropertyChangeCallback property_changed_callback_;
308
309  DISALLOW_COPY_AND_ASSIGN(PropertyStore);
310};
311
312}  // namespace shill
313
314#endif  // SHILL_PROPERTY_STORE_H_
315