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