1# ASIO 2 3## Properties 4 5Properties can be dynamically registered to an interface by calling 6`register_property()`. If you need to provide a custom getter or setter for a 7property, it should follow the guidelines in this section. 8 9To return a D-Bus error reply for either GetProperty or SetProperty, throw a 10custom exception derived from `sdbusplus::exception_t`. For the custom 11exception, you can return a well-defined [org.freedesktop.DBus.Error][1] from 12the `name()` or a custom/arbitrary name. The former will be automatically 13translated into a matching [error code][2] that can be consumed by the caller, 14while the latter will always be mapped to `EIO`, requiring a `strcmp` to 15determine the exact error name. 16 17The handler may also throw any exception not derived from 18`sdbusplus::exception_t`, in which case a generic 19org.freedesktop.DBus.Error.InvalidArgs error will be returned to the caller. 20 21[1]: https://www.freedesktop.org/software/systemd/man/sd-bus-errors.html# 22[2]: 23 https://github.com/systemd/systemd/blob/485c9e19e7ebcd912d5fbf11f40afc62951173f8/src/libsystemd/sd-bus/bus-error.c 24 25### Get Property callback 26 27When registering a property using ASIO methods, the get callback should meet the 28following prototype: 29 30```c++ 31PropertyType getHandler(const PropertyType& value); 32``` 33 34The first argument is the current value cached in the D-Bus interface (i.e. the 35previously "getted" value, or the initialized value), and the return value is 36returned to the D-Bus caller. 37 38### Set Property callback 39 40When registering a writable property using ASIO methods, the set callback should 41meet the following prototype: 42 43```c++ 44bool setHandler(const PropertyType& newValue, PropertyType& value); 45``` 46 47The first argument is the new value requested to be set by the D-Bus caller. 48 49The second argument is the actual underlying value contained within the object 50server. If the new value meets the expected constraints, the handler must set 51`value = newValue` to make the set operation take effect and return true. If the 52new value is invalid or cannot be applied for whatever reason, the handler must 53leave `value` unmodified and return false. 54 55If the handler returns false but doesn't throw an exception, a generic 56org.freedesktop.DBus.Error.InvalidArgs error will be returned to the caller. 57