From f336811fc71cae44cf13b9b8bdb61f843c2ac144 Mon Sep 17 00:00:00 2001 From: b-s-e <63726360+b-s-e@users.noreply.github.com> Date: Mon, 5 Sep 2022 13:51:05 +0200 Subject: [PATCH] docs: add section on D-Bus types to C++ types mapping (#285) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added D-Bus type C++ type table * docs: do corrections and rewordings in the proposed chapter Co-authored-by: Stanislav Angelovič --- docs/using-sdbus-c++.md | 46 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/using-sdbus-c++.md b/docs/using-sdbus-c++.md index 4afb5b3..acf7608 100644 --- a/docs/using-sdbus-c++.md +++ b/docs/using-sdbus-c++.md @@ -19,8 +19,9 @@ Using sdbus-c++ library 14. [Asynchronous client-side methods](#asynchronous-client-side-methods) 15. [Using D-Bus properties](#using-d-bus-properties) 16. [Standard D-Bus interfaces](#standard-d-bus-interfaces) -17. [Support for match rules](#support-for-match-rules) -18. [Conclusion](#conclusion) +17. [Using D-Bus Types](#using-d-bus-types) +18. [Support for match rules](#support-for-match-rules) +19. [Conclusion](#conclusion) Introduction ------------ @@ -1280,6 +1281,47 @@ Note that signals of afore-mentioned standard D-Bus interfaces are not emitted b Working examples of using standard D-Bus interfaces can be found in [sdbus-c++ integration tests](/tests/integrationtests/DBusStandardInterfacesTests.cpp) or the [examples](/examples) directory. +Using D-Bus Types +----------------- + +For many D-Bus interactions dealing with D-Bus types is necessary. For that, sdbus-c++ provides many predefined D-Bus types. The table below shows which C++ type corresponds to which D-Bus type. + + +| Category | Code | Code ASCII | Conventional Name | C++ Type | +|---------------------|-------------|------------|--------------------|---------------------------------| +| reserved | 0 | NUL | INVALID | - | +| fixed, basic | 121 | y | BYTE | `uint8_t` | +| fixed, basic | 98 | b | BOOLEAN | `bool` | +| fixed, basic | 110 | n | INT16 | `int16_t` | +| fixed, basic | 113 | q | UINT16 | `uint16_t` | +| fixed, basic | 105 | i | INT32 | `int32_t` | +| fixed, basic | 117 | u | UINT32 | `uint32_t` | +| fixed, basic | 120 | x | INT64 | `int64_t` | +| fixed, basic | 116 | t | UINT64 | `uint64_t` | +| fixed, basic | 100 | d | DOUBLE | `double` | +| string-like, basic | 115 | s | STRING | `const char*`, `std::string` | +| string-like, basic | 111 | o | OBJECT_PATH | `sdbus::ObjectPath` | +| string-like, basic | 103 | g | SIGNATURE | `sdbus::Signature` | +| container | 97 | a | ARRAY | `std::vector` (if used as an array followed by a single complete type T), or `std::map` (if used as an array of dict entries) | +| container | 114,40,41 | r() | STRUCT | `sdbus::Struct` variadic class template | +| container | 118 | v | VARIANT | `sdbus::Variant` | +| container | 101,123,125 | e{} | DICT_ENTRY | - | +| fixed, basic | 104 | h | UNIX_FD | `sdbus::UnixFd` | +| reserved | 109 | m | (reserved) | - | +| reserved | 42 | * | (reserved) | - | +| reserved | 63 | ? | (reserved) | - | +| reserved | 64,38,94 | @&^ | (reserved) | - | + +A few examples: + +* The D-Bus signature of an output argument of method `GetManagedObjects()` on standard interface `org.freedesktop.DBus.ObjectManager` is `a{oa{sa{sv}}}`. For this the corresponding C++ method return type is: `std::map>>`. +* Or an input argument of method `InterfacesRemoved` on that interface has signature `as`. Ths corresponds to the C++ parameter of type `std::vector`. +* Or a D-Bus signature `a(bdh)` corresponds to the array of D-Bus structures: `std::vector>`. + +To see how C++ types are mapped to D-Bus types (including container types) in sdbus-c++, have a look at individual [specializations of `sdbus::signature_of` class template](https://github.com/Kistler-Group/sdbus-cpp/blob/master/include/sdbus-c%2B%2B/TypeTraits.h#L87) in TypeTraits.h header file. For more examples of type mappings, look into [TypeTraits unit tests](https://github.com/Kistler-Group/sdbus-cpp/blob/master/tests/unittests/TypeTraits_test.cpp#L62). + +For more information on basic D-Bus types, D-Bus container types, and D-Bus type system in general, make sure to consult the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system). + Support for match rules -----------------------