feat: add support for direct connections (#350)

* feat: add support for direct connections

* refactor: simplify a bit, change comments, extend tests

* fix: compiler warning about unused variable

* docs: add section on direct connections to the tutorial

---------

Co-authored-by: Maksim Fedyarov <m.fedyarov@omp.ru>
Co-authored-by: Stanislav Angelovič <stanislav.angelovic@protonmail.com>

include/sdbus-c++/IConnection.h

@@ -458,6 +458,45 @@ namespace sdbus {
      * @throws sdbus::Error in case of failure
      */
     [[nodiscard]] std::unique_ptr<sdbus::IConnection> createRemoteSystemBusConnection(const std::string& host);
+
+    /*!
+     * @brief Opens direct D-Bus connection at a custom address
+     *
+     * @param[in] address ";"-separated list of addresses of bus brokers to try to connect to
+     * @return Connection instance
+     *
+     * @throws sdbus::Error in case of failure
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IConnection> createDirectBusConnection(const std::string& address);
+
+    /*!
+     * @brief Opens direct D-Bus connection at the given file descriptor
+     *
+     * @param[in] fd File descriptor used to communicate directly from/to a D-Bus server
+     * @return Connection instance
+     *
+     * The underlying sdbus-c++ connection instance takes over ownership of fd, so the caller can let it go.
+     * If, however, the call throws an exception, the ownership of fd remains with the caller.
+     *
+     * @throws sdbus::Error in case of failure
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IConnection> createDirectBusConnection(int fd);
+
+    /*!
+     * @brief Opens direct D-Bus connection at fd as a server
+     *
+     * @param[in] fd File descriptor to use for server DBus connection
+     * @return Server connection instance
+     *
+     * This creates a new, custom bus object in server mode. One can then call createDirectBusConnection()
+     * on client side to connect to this bus.
+     *
+     * The underlying sdbus-c++ connection instance takes over ownership of fd, so the caller can let it go.
+     * If, however, the call throws an exception, the ownership of fd remains with the caller.
+     *
+     * @throws sdbus::Error in case of failure
+     */
+    [[nodiscard]] std::unique_ptr<sdbus::IConnection> createServerBus(int fd);
 }
 
 #endif /* SDBUS_CXX_ICONNECTION_H_ */

include/sdbus-c++/IProxy.h

@@ -562,6 +562,9 @@ namespace sdbus {
      * should make sure that an I/O event loop is running on that connection, so the proxy
      * may receive incoming signals and asynchronous method replies.
      *
+     * The destination parameter may be an empty string (useful e.g. in case of direct
+     * D-Bus connections to a custom server bus).
+     *
      * Code example:
      * @code
      * auto proxy = sdbus::createProxy(connection, "com.kistler.foo", "/com/kistler/foo");
@@ -585,6 +588,9 @@ namespace sdbus {
      * upon that connection in a separate internal thread. Handlers for incoming signals and
      * asynchronous method replies will be executed in the context of that thread.
      *
+     * The destination parameter may be an empty string (useful e.g. in case of direct
+     * D-Bus connections to a custom server bus).
+     *
      * Code example:
      * @code
      * auto proxy = sdbus::createProxy(std::move(connection), "com.kistler.foo", "/com/kistler/foo");
@@ -603,10 +609,14 @@ namespace sdbus {
      * @return Pointer to the object proxy instance
      *
      * The provided connection will be used by the proxy to issue calls against the object.
-     * The Object proxy becomes an exclusive owner of this connection, but will not start an event loop
-     * thread on this connection. This is cheap construction and is suitable for short-lived proxies
-     * created just to execute simple synchronous D-Bus calls and then destroyed. Such blocking request-reply
-     * calls will work without an event loop (but signals, async calls, etc. won't).
+     * The Object proxy becomes an exclusive owner of this connection, but will not start
+     * an event loop thread on this connection. This is cheap construction and is suitable
+     * for short-lived proxies created just to execute simple synchronous D-Bus calls and
+     * then destroyed. Such blocking request-reply calls will work without an event loop
+     * (but signals, async calls, etc. won't).
+     *
+     * The destination parameter may be an empty string (useful e.g. in case of direct
+     * D-Bus connections to a custom server bus).
      *
      * Code example:
      * @code