1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef DBUS_PROPERTY_H_
6 #define DBUS_PROPERTY_H_
15 #include "base/bind.h"
16 #include "base/callback.h"
17 #include "base/macros.h"
18 #include "dbus/dbus_export.h"
19 #include "dbus/message.h"
20 #include "dbus/object_proxy.h"
22 // D-Bus objects frequently provide sets of properties accessed via a
23 // standard interface of method calls and signals to obtain the current value,
24 // set a new value and be notified of changes to the value. Unfortunately this
25 // interface makes heavy use of variants and dictionaries of variants. The
26 // classes defined here make dealing with properties in a type-safe manner
29 // Client implementation classes should define a Properties structure, deriving
30 // from the PropertySet class defined here. This structure should contain a
31 // member for each property defined as an instance of the Property<> class,
32 // specifying the type to the template. Finally the structure should chain up
33 // to the PropertySet constructor, and then call RegisterProperty() for each
34 // property defined to associate them with their string name.
37 // class ExampleClient {
39 // struct Properties : public dbus::PropertySet {
40 // dbus::Property<std::string> name;
41 // dbus::Property<uint16_t> version;
42 // dbus::Property<dbus::ObjectPath> parent;
43 // dbus::Property<std::vector<std::string>> children;
45 // Properties(dbus::ObjectProxy* object_proxy,
46 // const PropertyChangedCallback callback)
47 // : dbus::PropertySet(object_proxy, "com.example.DBus", callback) {
48 // RegisterProperty("Name", &name);
49 // RegisterProperty("Version", &version);
50 // RegisterProperty("Parent", &parent);
51 // RegisterProperty("Children", &children);
53 // virtual ~Properties() {}
56 // The Properties structure requires a pointer to the object proxy of the
57 // actual object to track, and after construction should have signals
58 // connected to that object and initial values set by calling ConnectSignals()
59 // and GetAll(). The structure should not outlive the object proxy, so it
60 // is recommended that the lifecycle of both be managed together.
62 // Example (continued):
64 // typedef std::map<std::pair<dbus::ObjectProxy*, Properties*>> Object;
65 // typedef std::map<dbus::ObjectPath, Object> ObjectMap;
66 // ObjectMap object_map_;
68 // dbus::ObjectProxy* GetObjectProxy(const dbus::ObjectPath& object_path) {
69 // return GetObject(object_path).first;
72 // Properties* GetProperties(const dbus::ObjectPath& object_path) {
73 // return GetObject(object_path).second;
76 // Object GetObject(const dbus::ObjectPath& object_path) {
77 // ObjectMap::iterator it = object_map_.find(object_path);
78 // if (it != object_map_.end())
81 // dbus::ObjectProxy* object_proxy = bus->GetObjectProxy(...);
82 // // connect signals, etc.
84 // Properties* properties = new Properties(
86 // base::Bind(&PropertyChanged,
87 // weak_ptr_factory_.GetWeakPtr(),
89 // properties->ConnectSignals();
90 // properties->GetAll();
92 // Object object = std::make_pair(object_proxy, properties);
93 // object_map_[object_path] = object;
98 // This now allows code using the client implementation to access properties
99 // in a type-safe manner, and assuming the PropertyChanged callback is
100 // propogated up to observers, be notified of changes. A typical access of
101 // the current value of the name property would be:
103 // ExampleClient::Properties* p = example_client->GetProperties(object_path);
104 // std::string name = p->name.value();
106 // Normally these values are updated from signals emitted by the remote object,
107 // in case an explicit round-trip is needed to obtain the current value, the
108 // Get() method can be used and indicates whether or not the value update was
109 // successful. The updated value can be obtained in the callback using the
112 // p->children.Get(base::Bind(&OnGetChildren));
114 // A new value can be set using the Set() method, the callback indicates
115 // success only; it is up to the remote object when (and indeed if) it updates
116 // the property value, and whether it emits a signal or a Get() call is
117 // required to obtain it.
119 // p->version.Set(20, base::Bind(&OnSetVersion))
123 // D-Bus Properties interface constants, declared here rather than
124 // in property.cc because template methods use them.
125 const char kPropertiesInterface[] = "org.freedesktop.DBus.Properties";
126 const char kPropertiesGetAll[] = "GetAll";
127 const char kPropertiesGet[] = "Get";
128 const char kPropertiesSet[] = "Set";
129 const char kPropertiesChanged[] = "PropertiesChanged";
133 // PropertyBase is an abstract base-class consisting of the parts of
134 // the Property<> template that are not type-specific, such as the
135 // associated PropertySet, property name, and the type-unsafe parts
136 // used by PropertySet.
137 class CHROME_DBUS_EXPORT PropertyBase {
140 virtual ~PropertyBase();
142 // Initializes the |property_set| and property |name| so that method
143 // calls may be made from this class. This method is called by
144 // PropertySet::RegisterProperty() passing |this| for |property_set| so
145 // there should be no need to call it directly. If you do beware that
146 // no ownership or reference to |property_set| is taken so that object
147 // must outlive this one.
148 void Init(PropertySet* property_set, const std::string& name);
150 // Retrieves the name of this property, this may be useful in observers
151 // to avoid specifying the name in more than once place, e.g.
153 // void Client::PropertyChanged(const dbus::ObjectPath& object_path,
154 // const std::string &property_name) {
155 // Properties& properties = GetProperties(object_path);
156 // if (property_name == properties.version.name()) {
157 // // Handle version property changing
160 const std::string& name() const { return name_; }
162 // Returns true if property is valid, false otherwise.
163 bool is_valid() const { return is_valid_; }
165 // Allows to mark Property as valid or invalid.
166 void set_valid(bool is_valid) { is_valid_ = is_valid; }
168 // Method used by PropertySet to retrieve the value from a MessageReader,
169 // no knowledge of the contained type is required, this method returns
170 // true if its expected type was found, false if not.
171 // Implementation provided by specialization.
172 virtual bool PopValueFromReader(MessageReader* reader) = 0;
174 // Method used by PropertySet to append the set value to a MessageWriter,
175 // no knowledge of the contained type is required.
176 // Implementation provided by specialization.
177 virtual void AppendSetValueToWriter(MessageWriter* writer) = 0;
179 // Method used by test and stub implementations of dbus::PropertySet::Set
180 // to replace the property value with the set value without using a
181 // dbus::MessageReader.
182 virtual void ReplaceValueWithSetValue() = 0;
185 // Retrieves the associated property set.
186 PropertySet* property_set() { return property_set_; }
189 // Pointer to the PropertySet instance that this instance is a member of,
190 // no ownership is taken and |property_set_| must outlive this class.
191 PropertySet* property_set_;
195 // Name of the property.
198 DISALLOW_COPY_AND_ASSIGN(PropertyBase);
201 // PropertySet groups a collection of properties for a remote object
202 // together into a single structure, fixing their types and name such
203 // that calls made through it are type-safe.
205 // Clients always sub-class this to add the properties, and should always
206 // provide a constructor that chains up to this and then calls
207 // RegisterProperty() for each property defined.
209 // After creation, client code should call ConnectSignals() and most likely
210 // GetAll() to seed initial values and update as changes occur.
211 class CHROME_DBUS_EXPORT PropertySet {
213 // Callback for changes to cached values of properties, either notified
214 // via signal, or as a result of calls to Get() and GetAll(). The |name|
215 // argument specifies the name of the property changed.
216 typedef base::Callback<void(const std::string& name)> PropertyChangedCallback;
218 // Constructs a property set, where |object_proxy| specifies the proxy for
219 // the/ remote object that these properties are for, care should be taken to
220 // ensure that this object does not outlive the lifetime of the proxy;
221 // |interface| specifies the D-Bus interface of these properties, and
222 // |property_changed_callback| specifies the callback for when properties
223 // are changed, this may be a NULL callback.
224 PropertySet(ObjectProxy* object_proxy, const std::string& interface,
225 const PropertyChangedCallback& property_changed_callback);
227 // Destructor; we don't hold on to any references or memory that needs
228 // explicit clean-up, but clang thinks we might.
229 virtual ~PropertySet();
231 // Registers a property, generally called from the subclass constructor;
232 // pass the |name| of the property as used in method calls and signals,
233 // and the pointer to the |property| member of the structure. This will
234 // call the PropertyBase::Init method.
235 void RegisterProperty(const std::string& name, PropertyBase* property);
237 // Connects property change notification signals to the object, generally
238 // called immediately after the object is created and before calls to other
239 // methods. Sub-classes may override to use different D-Bus signals.
240 virtual void ConnectSignals();
242 // Methods connected by ConnectSignals() and called by dbus:: when
243 // a property is changed. Sub-classes may override if the property
244 // changed signal provides different arguments.
245 virtual void ChangedReceived(Signal* signal);
246 virtual void ChangedConnected(const std::string& interface_name,
247 const std::string& signal_name,
250 // Callback for Get() method, |success| indicates whether or not the
251 // value could be retrived, if true the new value can be obtained by
252 // calling value() on the property.
253 using GetCallback = base::OnceCallback<void(bool success)>;
255 // Requests an updated value from the remote object for |property|
256 // incurring a round-trip. |callback| will be called when the new
257 // value is available. This may not be implemented by some interfaces,
258 // and may be overriden by sub-classes if interfaces use different
260 virtual void Get(PropertyBase* property, GetCallback callback);
261 virtual void OnGet(PropertyBase* property, GetCallback callback,
264 // The synchronous version of Get().
265 // This should never be used on an interactive thread.
266 virtual bool GetAndBlock(PropertyBase* property);
268 // Queries the remote object for values of all properties and updates
269 // initial values. Sub-classes may override to use a different D-Bus
270 // method, or if the remote object does not support retrieving all
271 // properties, either ignore or obtain each property value individually.
272 virtual void GetAll();
273 virtual void OnGetAll(Response* response);
275 // Callback for Set() method, |success| indicates whether or not the
276 // new property value was accepted by the remote object.
277 using SetCallback = base::OnceCallback<void(bool success)>;
279 // Requests that the remote object for |property| change the property to
280 // its new value. |callback| will be called to indicate the success or
281 // failure of the request, however the new value may not be available
282 // depending on the remote object. This method may be overridden by
283 // sub-classes if interfaces use different method calls.
284 virtual void Set(PropertyBase* property, SetCallback callback);
285 virtual void OnSet(PropertyBase* property, SetCallback callback,
288 // The synchronous version of Set().
289 // This should never be used on an interactive thread.
290 virtual bool SetAndBlock(PropertyBase* property);
292 // Update properties by reading an array of dictionary entries, each
293 // containing a string with the name and a variant with the value, from
294 // |message_reader|. Returns false if message is in incorrect format.
295 bool UpdatePropertiesFromReader(MessageReader* reader);
297 // Updates a single property by reading a string with the name and a
298 // variant with the value from |message_reader|. Returns false if message
299 // is in incorrect format, or property type doesn't match.
300 bool UpdatePropertyFromReader(MessageReader* reader);
302 // Calls the property changed callback passed to the constructor, used
303 // by sub-classes that do not call UpdatePropertiesFromReader() or
304 // UpdatePropertyFromReader(). Takes the |name| of the changed property.
305 void NotifyPropertyChanged(const std::string& name);
307 // Retrieves the object proxy this property set was initialized with,
308 // provided for sub-classes overriding methods that make D-Bus calls
309 // and for Property<>. Not permitted with const references to this class.
310 ObjectProxy* object_proxy() { return object_proxy_; }
312 // Retrieves the interface of this property set.
313 const std::string& interface() const { return interface_; }
316 // Get a weak pointer to this property set, provided so that sub-classes
317 // overriding methods that make D-Bus calls may use the existing (or
318 // override) callbacks without providing their own weak pointer factory.
319 base::WeakPtr<PropertySet> GetWeakPtr() {
320 return weak_ptr_factory_.GetWeakPtr();
324 // Invalidates properties by reading an array of names, from
325 // |message_reader|. Returns false if message is in incorrect format.
326 bool InvalidatePropertiesFromReader(MessageReader* reader);
328 // Pointer to object proxy for making method calls, no ownership is taken
329 // so this must outlive this class.
330 ObjectProxy* object_proxy_;
332 // Interface of property, e.g. "org.chromium.ExampleService", this is
333 // distinct from the interface of the method call itself which is the
334 // general D-Bus Properties interface "org.freedesktop.DBus.Properties".
335 std::string interface_;
337 // Callback for property changes.
338 PropertyChangedCallback property_changed_callback_;
340 // Map of properties (as PropertyBase*) defined in the structure to
341 // names as used in D-Bus method calls and signals. The base pointer
342 // restricts property access via this map to type-unsafe and non-specific
344 typedef std::map<const std::string, PropertyBase*> PropertiesMap;
345 PropertiesMap properties_map_;
347 // Weak pointer factory as D-Bus callbacks may last longer than these
349 base::WeakPtrFactory<PropertySet> weak_ptr_factory_;
351 DISALLOW_COPY_AND_ASSIGN(PropertySet);
354 // Property template, this defines the type-specific and type-safe methods
355 // of properties that can be accessed as members of a PropertySet structure.
357 // Properties provide a cached value that has an initial sensible default
358 // until the reply to PropertySet::GetAll() is retrieved and is updated by
359 // all calls to that method, PropertySet::Get() and property changed signals
360 // also handled by PropertySet. It can be obtained by calling value() on the
363 // It is recommended that this cached value be used where necessary, with
364 // code using PropertySet::PropertyChangedCallback to be notified of changes,
365 // rather than incurring a round-trip to the remote object for each property
368 // Where a round-trip is necessary, the Get() method is provided. And to
369 // update the remote object value, the Set() method is also provided; these
370 // both simply call methods on PropertySet.
372 // Handling of particular D-Bus types is performed via specialization,
373 // typically the PopValueFromReader() and AppendSetValueToWriter() methods
374 // will need to be provided, and in rare cases a constructor to provide a
375 // default value. Specializations for basic D-Bus types, strings, object
376 // paths and arrays are provided for you.
378 class CHROME_DBUS_EXPORT Property : public PropertyBase {
381 ~Property() override {}
383 // Retrieves the cached value.
384 const T& value() const { return value_; }
386 // Requests an updated value from the remote object incurring a
387 // round-trip. |callback| will be called when the new value is available.
388 // This may not be implemented by some interfaces.
389 virtual void Get(dbus::PropertySet::GetCallback callback) {
390 property_set()->Get(this, std::move(callback));
393 // The synchronous version of Get().
394 // This should never be used on an interactive thread.
395 virtual bool GetAndBlock() {
396 return property_set()->GetAndBlock(this);
399 // Requests that the remote object change the property value to |value|,
400 // |callback| will be called to indicate the success or failure of the
401 // request, however the new value may not be available depending on the
403 virtual void Set(const T& value, dbus::PropertySet::SetCallback callback) {
405 property_set()->Set(this, std::move(callback));
408 // The synchronous version of Set().
409 // This should never be used on an interactive thread.
410 virtual bool SetAndBlock(const T& value) {
412 return property_set()->SetAndBlock(this);
415 // Method used by PropertySet to retrieve the value from a MessageReader,
416 // no knowledge of the contained type is required, this method returns
417 // true if its expected type was found, false if not.
418 bool PopValueFromReader(MessageReader* reader) override;
420 // Method used by PropertySet to append the set value to a MessageWriter,
421 // no knowledge of the contained type is required.
422 // Implementation provided by specialization.
423 void AppendSetValueToWriter(MessageWriter* writer) override;
425 // Method used by test and stub implementations of dbus::PropertySet::Set
426 // to replace the property value with the set value without using a
427 // dbus::MessageReader.
428 void ReplaceValueWithSetValue() override {
430 property_set()->NotifyPropertyChanged(name());
433 // Method used by test and stub implementations to directly set the
434 // value of a property.
435 void ReplaceValue(const T& value) {
437 property_set()->NotifyPropertyChanged(name());
440 // Method used by test and stub implementations to directly set the
441 // |set_value_| of a property.
442 void ReplaceSetValueForTesting(const T& value) { set_value_ = value; }
444 // Method used by test and stub implementations to retrieve the |set_value|
446 const T& GetSetValueForTesting() const { return set_value_; }
449 // Current cached value of the property.
452 // Replacement value of the property.
456 // Clang and GCC don't agree on how attributes should work for explicitly
457 // instantiated templates. GCC ignores attributes on explicit instantiations
458 // (and emits a warning) while Clang requires the visiblity attribute on the
459 // explicit instantiations for them to be visible to other compilation units.
460 // Hopefully clang and GCC agree one day, and this can be cleaned up:
461 // https://llvm.org/bugs/show_bug.cgi?id=24815
462 #pragma GCC diagnostic push
463 #pragma GCC diagnostic ignored "-Wattributes"
466 CHROME_DBUS_EXPORT Property<uint8_t>::Property();
468 CHROME_DBUS_EXPORT bool Property<uint8_t>::PopValueFromReader(
469 MessageReader* reader);
471 CHROME_DBUS_EXPORT void Property<uint8_t>::AppendSetValueToWriter(
472 MessageWriter* writer);
473 extern template class CHROME_DBUS_EXPORT Property<uint8_t>;
476 CHROME_DBUS_EXPORT Property<bool>::Property();
478 CHROME_DBUS_EXPORT bool Property<bool>::PopValueFromReader(
479 MessageReader* reader);
481 CHROME_DBUS_EXPORT void Property<bool>::AppendSetValueToWriter(
482 MessageWriter* writer);
483 extern template class CHROME_DBUS_EXPORT Property<bool>;
486 CHROME_DBUS_EXPORT Property<int16_t>::Property();
488 CHROME_DBUS_EXPORT bool Property<int16_t>::PopValueFromReader(
489 MessageReader* reader);
491 CHROME_DBUS_EXPORT void Property<int16_t>::AppendSetValueToWriter(
492 MessageWriter* writer);
493 extern template class CHROME_DBUS_EXPORT Property<int16_t>;
496 CHROME_DBUS_EXPORT Property<uint16_t>::Property();
498 CHROME_DBUS_EXPORT bool Property<uint16_t>::PopValueFromReader(
499 MessageReader* reader);
501 CHROME_DBUS_EXPORT void Property<uint16_t>::AppendSetValueToWriter(
502 MessageWriter* writer);
503 extern template class CHROME_DBUS_EXPORT Property<uint16_t>;
506 CHROME_DBUS_EXPORT Property<int32_t>::Property();
508 CHROME_DBUS_EXPORT bool Property<int32_t>::PopValueFromReader(
509 MessageReader* reader);
511 CHROME_DBUS_EXPORT void Property<int32_t>::AppendSetValueToWriter(
512 MessageWriter* writer);
513 extern template class CHROME_DBUS_EXPORT Property<int32_t>;
516 CHROME_DBUS_EXPORT Property<uint32_t>::Property();
518 CHROME_DBUS_EXPORT bool Property<uint32_t>::PopValueFromReader(
519 MessageReader* reader);
521 CHROME_DBUS_EXPORT void Property<uint32_t>::AppendSetValueToWriter(
522 MessageWriter* writer);
523 extern template class CHROME_DBUS_EXPORT Property<uint32_t>;
526 CHROME_DBUS_EXPORT Property<int64_t>::Property();
528 CHROME_DBUS_EXPORT bool Property<int64_t>::PopValueFromReader(
529 MessageReader* reader);
531 CHROME_DBUS_EXPORT void Property<int64_t>::AppendSetValueToWriter(
532 MessageWriter* writer);
533 extern template class CHROME_DBUS_EXPORT Property<int64_t>;
536 CHROME_DBUS_EXPORT Property<uint64_t>::Property();
538 CHROME_DBUS_EXPORT bool Property<uint64_t>::PopValueFromReader(
539 MessageReader* reader);
541 CHROME_DBUS_EXPORT void Property<uint64_t>::AppendSetValueToWriter(
542 MessageWriter* writer);
543 extern template class CHROME_DBUS_EXPORT Property<uint64_t>;
546 CHROME_DBUS_EXPORT Property<double>::Property();
548 CHROME_DBUS_EXPORT bool Property<double>::PopValueFromReader(
549 MessageReader* reader);
551 CHROME_DBUS_EXPORT void Property<double>::AppendSetValueToWriter(
552 MessageWriter* writer);
553 extern template class CHROME_DBUS_EXPORT Property<double>;
556 CHROME_DBUS_EXPORT bool Property<std::string>::PopValueFromReader(
557 MessageReader* reader);
559 CHROME_DBUS_EXPORT void Property<std::string>::AppendSetValueToWriter(
560 MessageWriter* writer);
561 extern template class CHROME_DBUS_EXPORT Property<std::string>;
564 CHROME_DBUS_EXPORT bool Property<ObjectPath>::PopValueFromReader(
565 MessageReader* reader);
567 CHROME_DBUS_EXPORT void Property<ObjectPath>::AppendSetValueToWriter(
568 MessageWriter* writer);
569 extern template class CHROME_DBUS_EXPORT Property<ObjectPath>;
572 CHROME_DBUS_EXPORT bool Property<std::vector<std::string>>::PopValueFromReader(
573 MessageReader* reader);
575 CHROME_DBUS_EXPORT void Property<
576 std::vector<std::string>>::AppendSetValueToWriter(MessageWriter* writer);
577 extern template class CHROME_DBUS_EXPORT Property<std::vector<std::string>>;
580 CHROME_DBUS_EXPORT bool Property<std::vector<ObjectPath>>::PopValueFromReader(
581 MessageReader* reader);
583 CHROME_DBUS_EXPORT void Property<
584 std::vector<ObjectPath>>::AppendSetValueToWriter(MessageWriter* writer);
585 extern template class CHROME_DBUS_EXPORT Property<std::vector<ObjectPath>>;
588 CHROME_DBUS_EXPORT bool Property<std::vector<uint8_t>>::PopValueFromReader(
589 MessageReader* reader);
591 CHROME_DBUS_EXPORT void Property<std::vector<uint8_t>>::AppendSetValueToWriter(
592 MessageWriter* writer);
593 extern template class CHROME_DBUS_EXPORT Property<std::vector<uint8_t>>;
596 CHROME_DBUS_EXPORT bool
597 Property<std::map<std::string, std::string>>::PopValueFromReader(
598 MessageReader* reader);
600 CHROME_DBUS_EXPORT void
601 Property<std::map<std::string, std::string>>::AppendSetValueToWriter(
602 MessageWriter* writer);
603 extern template class CHROME_DBUS_EXPORT
604 Property<std::map<std::string, std::string>>;
607 CHROME_DBUS_EXPORT bool
608 Property<std::vector<std::pair<std::vector<uint8_t>, uint16_t>>>::
609 PopValueFromReader(MessageReader* reader);
611 CHROME_DBUS_EXPORT void
612 Property<std::vector<std::pair<std::vector<uint8_t>, uint16_t>>>::
613 AppendSetValueToWriter(MessageWriter* writer);
614 extern template class CHROME_DBUS_EXPORT
615 Property<std::vector<std::pair<std::vector<uint8_t>, uint16_t>>>;
618 CHROME_DBUS_EXPORT bool
619 Property<std::map<std::string, std::vector<uint8_t>>>::PopValueFromReader(
620 MessageReader* reader);
622 CHROME_DBUS_EXPORT void
623 Property<std::map<std::string, std::vector<uint8_t>>>::AppendSetValueToWriter(
624 MessageWriter* writer);
625 extern template class CHROME_DBUS_EXPORT
626 Property<std::map<std::string, std::vector<uint8_t>>>;
629 CHROME_DBUS_EXPORT bool
630 Property<std::map<uint16_t, std::vector<uint8_t>>>::PopValueFromReader(
631 MessageReader* reader);
633 CHROME_DBUS_EXPORT void
634 Property<std::map<uint16_t, std::vector<uint8_t>>>::AppendSetValueToWriter(
635 MessageWriter* writer);
636 extern template class CHROME_DBUS_EXPORT
637 Property<std::map<uint16_t, std::vector<uint8_t>>>;
639 #pragma GCC diagnostic pop
643 #endif // DBUS_PROPERTY_H_