diff --git a/include/sdbus-c++/IConnection.h b/include/sdbus-c++/IConnection.h index 6f6feca..dd5a1c8 100644 --- a/include/sdbus-c++/IConnection.h +++ b/include/sdbus-c++/IConnection.h @@ -48,117 +48,117 @@ namespace sdbus { virtual ~IConnection() = default; /*! - * @brief Requests D-Bus name on the connection - * - * @param[in] name Name to request - * - * @throws sdbus::Error in case of failure - */ + * @brief Requests D-Bus name on the connection + * + * @param[in] name Name to request + * + * @throws sdbus::Error in case of failure + */ virtual void requestName(const std::string& name) = 0; /*! - * @brief Releases D-Bus name on the connection - * - * @param[in] name Name to release - * - * @throws sdbus::Error in case of failure - */ + * @brief Releases D-Bus name on the connection + * + * @param[in] name Name to release + * + * @throws sdbus::Error in case of failure + */ virtual void releaseName(const std::string& name) = 0; /*! - * @brief Enters the D-Bus processing loop - * - * The incoming D-Bus messages are processed in the loop. The method - * blocks indefinitely, until unblocked via leaveProcessingLoop. - * - * @throws sdbus::Error in case of failure - */ + * @brief Enters the D-Bus processing loop + * + * The incoming D-Bus messages are processed in the loop. The method + * blocks indefinitely, until unblocked via leaveProcessingLoop. + * + * @throws sdbus::Error in case of failure + */ virtual void enterProcessingLoop() = 0; /*! - * @brief Enters the D-Bus processing loop in a separate thread - * - * The same as enterProcessingLoop, except that it doesn't block - * because it runs the loop in a separate thread managed internally. - */ + * @brief Enters the D-Bus processing loop in a separate thread + * + * The same as enterProcessingLoop, except that it doesn't block + * because it runs the loop in a separate thread managed internally. + */ virtual void enterProcessingLoopAsync() = 0; /*! - * @brief Leaves the D-Bus processing loop - * - * Ends the previously started processing loop. - * - * @throws sdbus::Error in case of failure - */ + * @brief Leaves the D-Bus processing loop + * + * Ends the previously started processing loop. + * + * @throws sdbus::Error in case of failure + */ virtual void leaveProcessingLoop() = 0; /*! - * @brief Adds an ObjectManager at the specified D-Bus object path - * - * Creates an ObjectManager interface at the specified object path on - * the connection. This is a convenient way to interrogate a connection - * to see what objects it has. - * - * @throws sdbus::Error in case of failure - */ + * @brief Adds an ObjectManager at the specified D-Bus object path + * + * Creates an ObjectManager interface at the specified object path on + * the connection. This is a convenient way to interrogate a connection + * to see what objects it has. + * + * @throws sdbus::Error in case of failure + */ virtual void addObjectManager(const std::string& objectPath) = 0; }; /*! - * @brief Creates/opens D-Bus system connection - * - * @return Connection instance - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates/opens D-Bus system connection + * + * @return Connection instance + * + * @throws sdbus::Error in case of failure + */ std::unique_ptr createConnection(); /*! - * @brief Creates/opens D-Bus system connection with a name - * - * @param[in] name Name to request on the connection after its opening - * @return Connection instance - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates/opens D-Bus system connection with a name + * + * @param[in] name Name to request on the connection after its opening + * @return Connection instance + * + * @throws sdbus::Error in case of failure + */ std::unique_ptr createConnection(const std::string& name); /*! - * @brief Creates/opens D-Bus system connection - * - * @return Connection instance - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates/opens D-Bus system connection + * + * @return Connection instance + * + * @throws sdbus::Error in case of failure + */ std::unique_ptr createSystemBusConnection(); /*! - * @brief Creates/opens D-Bus system connection with a name - * - * @param[in] name Name to request on the connection after its opening - * @return Connection instance - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates/opens D-Bus system connection with a name + * + * @param[in] name Name to request on the connection after its opening + * @return Connection instance + * + * @throws sdbus::Error in case of failure + */ std::unique_ptr createSystemBusConnection(const std::string& name); /*! - * @brief Creates/opens D-Bus session connection - * - * @return Connection instance - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates/opens D-Bus session connection + * + * @return Connection instance + * + * @throws sdbus::Error in case of failure + */ std::unique_ptr createSessionBusConnection(); /*! - * @brief Creates/opens D-Bus session connection with a name - * - * @param[in] name Name to request on the connection after its opening - * @return Connection instance - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates/opens D-Bus session connection with a name + * + * @param[in] name Name to request on the connection after its opening + * @return Connection instance + * + * @throws sdbus::Error in case of failure + */ std::unique_ptr createSessionBusConnection(const std::string& name); } diff --git a/include/sdbus-c++/IObject.h b/include/sdbus-c++/IObject.h index b2bf96b..b2c8da9 100644 --- a/include/sdbus-c++/IObject.h +++ b/include/sdbus-c++/IObject.h @@ -61,17 +61,17 @@ namespace sdbus { virtual ~IObject() = default; /*! - * @brief Registers method that the object will provide on D-Bus - * - * @param[in] interfaceName Name of an interface that the method will belong to - * @param[in] methodName Name of the method - * @param[in] inputSignature D-Bus signature of method input parameters - * @param[in] outputSignature D-Bus signature of method output parameters - * @param[in] methodCallback Callback that implements the body of the method - * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply) - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers method that the object will provide on D-Bus + * + * @param[in] interfaceName Name of an interface that the method will belong to + * @param[in] methodName Name of the method + * @param[in] inputSignature D-Bus signature of method input parameters + * @param[in] outputSignature D-Bus signature of method output parameters + * @param[in] methodCallback Callback that implements the body of the method + * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply) + * + * @throws sdbus::Error in case of failure + */ virtual void registerMethod( const std::string& interfaceName , const std::string& methodName , const std::string& inputSignature @@ -80,31 +80,31 @@ namespace sdbus { , Flags flags = {} ) = 0; /*! - * @brief Registers signal that the object will emit on D-Bus - * - * @param[in] interfaceName Name of an interface that the signal will fall under - * @param[in] signalName Name of the signal - * @param[in] signature D-Bus signature of signal parameters - * @param[in] flags D-Bus signal flags (deprecated) - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers signal that the object will emit on D-Bus + * + * @param[in] interfaceName Name of an interface that the signal will fall under + * @param[in] signalName Name of the signal + * @param[in] signature D-Bus signature of signal parameters + * @param[in] flags D-Bus signal flags (deprecated) + * + * @throws sdbus::Error in case of failure + */ virtual void registerSignal( const std::string& interfaceName , const std::string& signalName , const std::string& signature , Flags flags = {} ) = 0; /*! - * @brief Registers read-only property that the object will provide on D-Bus - * - * @param[in] interfaceName Name of an interface that the property will fall under - * @param[in] propertyName Name of the property - * @param[in] signature D-Bus signature of property parameters - * @param[in] getCallback Callback that implements the body of the property getter - * @param[in] flags D-Bus property flags (deprecated, property update behavior) - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers read-only property that the object will provide on D-Bus + * + * @param[in] interfaceName Name of an interface that the property will fall under + * @param[in] propertyName Name of the property + * @param[in] signature D-Bus signature of property parameters + * @param[in] getCallback Callback that implements the body of the property getter + * @param[in] flags D-Bus property flags (deprecated, property update behavior) + * + * @throws sdbus::Error in case of failure + */ virtual void registerProperty( const std::string& interfaceName , const std::string& propertyName , const std::string& signature @@ -112,17 +112,17 @@ namespace sdbus { , Flags flags = {} ) = 0; /*! - * @brief Registers read/write property that the object will provide on D-Bus - * - * @param[in] interfaceName Name of an interface that the property will fall under - * @param[in] propertyName Name of the property - * @param[in] signature D-Bus signature of property parameters - * @param[in] getCallback Callback that implements the body of the property getter - * @param[in] setCallback Callback that implements the body of the property setter - * @param[in] flags D-Bus property flags (deprecated, property update behavior) - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers read/write property that the object will provide on D-Bus + * + * @param[in] interfaceName Name of an interface that the property will fall under + * @param[in] propertyName Name of the property + * @param[in] signature D-Bus signature of property parameters + * @param[in] getCallback Callback that implements the body of the property getter + * @param[in] setCallback Callback that implements the body of the property setter + * @param[in] flags D-Bus property flags (deprecated, property update behavior) + * + * @throws sdbus::Error in case of failure + */ virtual void registerProperty( const std::string& interfaceName , const std::string& propertyName , const std::string& signature @@ -131,80 +131,80 @@ namespace sdbus { , Flags flags = {} ) = 0; /*! - * @brief Sets flags for a given interface - * - * @param[in] interfaceName Name of an interface whose flags will be set - * @param[in] flags Flags to be set - * - * @throws sdbus::Error in case of failure - */ + * @brief Sets flags for a given interface + * + * @param[in] interfaceName Name of an interface whose flags will be set + * @param[in] flags Flags to be set + * + * @throws sdbus::Error in case of failure + */ virtual void setInterfaceFlags(const std::string& interfaceName, Flags flags) = 0; /*! - * @brief Finishes object API registration and publishes the object on the bus - * - * The method exports all up to now registered methods, signals and properties on D-Bus. - * Must be called after all methods, signals and properties have been registered. - * - * @throws sdbus::Error in case of failure - */ + * @brief Finishes object API registration and publishes the object on the bus + * + * The method exports all up to now registered methods, signals and properties on D-Bus. + * Must be called after all methods, signals and properties have been registered. + * + * @throws sdbus::Error in case of failure + */ virtual void finishRegistration() = 0; /*! - * @brief Unregisters object's API and removes object from the bus - * - * This method unregisters the object, its interfaces, methods, signals and properties - * from the bus. Unregistration is done automatically also in object's destructor. This - * method makes sense if, in the process of object removal, we need to make sure that - * callbacks are unregistered explicitly before the final destruction of the object instance. - * - * @throws sdbus::Error in case of failure - */ + * @brief Unregisters object's API and removes object from the bus + * + * This method unregisters the object, its interfaces, methods, signals and properties + * from the bus. Unregistration is done automatically also in object's destructor. This + * method makes sense if, in the process of object removal, we need to make sure that + * callbacks are unregistered explicitly before the final destruction of the object instance. + * + * @throws sdbus::Error in case of failure + */ virtual void unregister() = 0; /*! - * @brief Creates a signal message - * - * @param[in] interfaceName Name of an interface that the signal belongs under - * @param[in] signalName Name of the signal - * @return A signal message - * - * Serialize signal arguments into the returned message and emit the signal by passing - * the message with serialized arguments to the @c emitSignal function. - * Alternatively, use higher-level API @c emitSignal(const std::string& signalName) defined below. - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates a signal message + * + * @param[in] interfaceName Name of an interface that the signal belongs under + * @param[in] signalName Name of the signal + * @return A signal message + * + * Serialize signal arguments into the returned message and emit the signal by passing + * the message with serialized arguments to the @c emitSignal function. + * Alternatively, use higher-level API @c emitSignal(const std::string& signalName) defined below. + * + * @throws sdbus::Error in case of failure + */ virtual Signal createSignal(const std::string& interfaceName, const std::string& signalName) = 0; /*! - * @brief Emits signal for this object path - * - * @param[in] message Signal message to be sent out - * - * Note: To avoid messing with messages, use higher-level API defined below. - * - * @throws sdbus::Error in case of failure - */ + * @brief Emits signal for this object path + * + * @param[in] message Signal message to be sent out + * + * Note: To avoid messing with messages, use higher-level API defined below. + * + * @throws sdbus::Error in case of failure + */ virtual void emitSignal(const sdbus::Signal& message) = 0; /*! - * @brief Emits PropertyChanged signal for specified properties under a given interface of this object path - * - * @param[in] interfaceName Name of an interface that properties belong to - * @param[in] propNames Names of properties that will be included in the PropertiesChanged signal - * - * @throws sdbus::Error in case of failure - */ + * @brief Emits PropertyChanged signal for specified properties under a given interface of this object path + * + * @param[in] interfaceName Name of an interface that properties belong to + * @param[in] propNames Names of properties that will be included in the PropertiesChanged signal + * + * @throws sdbus::Error in case of failure + */ virtual void emitPropertiesChangedSignal(const std::string& interfaceName, const std::vector& propNames) = 0; /*! - * @brief Emits PropertyChanged signal for all properties on a given interface of this object path - * - * @param[in] interfaceName Name of an interface - * - * @throws sdbus::Error in case of failure - */ + * @brief Emits PropertyChanged signal for all properties on a given interface of this object path + * + * @param[in] interfaceName Name of an interface + * + * @throws sdbus::Error in case of failure + */ virtual void emitPropertiesChangedSignal(const std::string& interfaceName) = 0; /*! @@ -259,21 +259,21 @@ namespace sdbus { virtual void emitInterfacesRemovedSignal(const std::vector& interfaces) = 0; /*! - * @brief Adds an ObjectManager interface at the path of this D-Bus object - * - * Creates an ObjectManager interface at the specified object path on - * the connection. This is a convenient way to interrogate a connection - * to see what objects it has. - * - * @throws sdbus::Error in case of failure - */ + * @brief Adds an ObjectManager interface at the path of this D-Bus object + * + * Creates an ObjectManager interface at the specified object path on + * the connection. This is a convenient way to interrogate a connection + * to see what objects it has. + * + * @throws sdbus::Error in case of failure + */ virtual void addObjectManager() = 0; /*! - * @brief Removes an ObjectManager interface from the path of this D-Bus object - * - * @throws sdbus::Error in case of failure - */ + * @brief Removes an ObjectManager interface from the path of this D-Bus object + * + * @throws sdbus::Error in case of failure + */ virtual void removeObjectManager() = 0; /*! @@ -283,106 +283,106 @@ namespace sdbus { virtual bool hasObjectManager() const = 0; /*! - * @brief Provides D-Bus connection used by the object - * - * @return Reference to the D-Bus connection - */ + * @brief Provides D-Bus connection used by the object + * + * @return Reference to the D-Bus connection + */ virtual sdbus::IConnection& getConnection() const = 0; /*! - * @brief Registers method that the object will provide on D-Bus - * - * @param[in] methodName Name of the method - * @return A helper object for convenient registration of the method - * - * This is a high-level, convenience way of registering D-Bus methods that abstracts - * from the D-Bus message concept. Method arguments/return value are automatically (de)serialized - * in a message and D-Bus signatures automatically deduced from the parameters and return type - * of the provided native method implementation callback. - * - * Example of use: - * @code - * object.registerMethod("doFoo").onInterface("com.kistler.foo").implementedAs([this](int value){ return this->doFoo(value); }); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers method that the object will provide on D-Bus + * + * @param[in] methodName Name of the method + * @return A helper object for convenient registration of the method + * + * This is a high-level, convenience way of registering D-Bus methods that abstracts + * from the D-Bus message concept. Method arguments/return value are automatically (de)serialized + * in a message and D-Bus signatures automatically deduced from the parameters and return type + * of the provided native method implementation callback. + * + * Example of use: + * @code + * object.registerMethod("doFoo").onInterface("com.kistler.foo").implementedAs([this](int value){ return this->doFoo(value); }); + * @endcode + * + * @throws sdbus::Error in case of failure + */ MethodRegistrator registerMethod(const std::string& methodName); /*! - * @brief Registers signal that the object will provide on D-Bus - * - * @param[in] signalName Name of the signal - * @return A helper object for convenient registration of the signal - * - * This is a high-level, convenience way of registering D-Bus signals that abstracts - * from the D-Bus message concept. Signal arguments are automatically (de)serialized - * in a message and D-Bus signatures automatically deduced from the provided native parameters. - * - * Example of use: - * @code - * object.registerSignal("paramChange").onInterface("com.kistler.foo").withParameters>(); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers signal that the object will provide on D-Bus + * + * @param[in] signalName Name of the signal + * @return A helper object for convenient registration of the signal + * + * This is a high-level, convenience way of registering D-Bus signals that abstracts + * from the D-Bus message concept. Signal arguments are automatically (de)serialized + * in a message and D-Bus signatures automatically deduced from the provided native parameters. + * + * Example of use: + * @code + * object.registerSignal("paramChange").onInterface("com.kistler.foo").withParameters>(); + * @endcode + * + * @throws sdbus::Error in case of failure + */ SignalRegistrator registerSignal(const std::string& signalName); /*! - * @brief Registers property that the object will provide on D-Bus - * - * @param[in] propertyName Name of the property - * @return A helper object for convenient registration of the property - * - * This is a high-level, convenience way of registering D-Bus properties that abstracts - * from the D-Bus message concept. Property arguments are automatically (de)serialized - * in a message and D-Bus signatures automatically deduced from the provided native callbacks. - * - * Example of use: - * @code - * object_.registerProperty("state").onInterface("com.kistler.foo").withGetter([this](){ return this->state(); }); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers property that the object will provide on D-Bus + * + * @param[in] propertyName Name of the property + * @return A helper object for convenient registration of the property + * + * This is a high-level, convenience way of registering D-Bus properties that abstracts + * from the D-Bus message concept. Property arguments are automatically (de)serialized + * in a message and D-Bus signatures automatically deduced from the provided native callbacks. + * + * Example of use: + * @code + * object_.registerProperty("state").onInterface("com.kistler.foo").withGetter([this](){ return this->state(); }); + * @endcode + * + * @throws sdbus::Error in case of failure + */ PropertyRegistrator registerProperty(const std::string& propertyName); /*! - * @brief Sets flags (annotations) for a given interface - * - * @param[in] interfaceName Name of an interface whose flags will be set - * @return A helper object for convenient setting of Interface flags - * - * This is a high-level, convenience alternative to the other setInterfaceFlags overload. - * - * Example of use: - * @code - * object_.setInterfaceFlags("com.kistler.foo").markAsDeprecated().withPropertyUpdateBehavior(sdbus::Flags::EMITS_NO_SIGNAL); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Sets flags (annotations) for a given interface + * + * @param[in] interfaceName Name of an interface whose flags will be set + * @return A helper object for convenient setting of Interface flags + * + * This is a high-level, convenience alternative to the other setInterfaceFlags overload. + * + * Example of use: + * @code + * object_.setInterfaceFlags("com.kistler.foo").markAsDeprecated().withPropertyUpdateBehavior(sdbus::Flags::EMITS_NO_SIGNAL); + * @endcode + * + * @throws sdbus::Error in case of failure + */ InterfaceFlagsSetter setInterfaceFlags(const std::string& interfaceName); /*! - * @brief Emits signal on D-Bus - * - * @param[in] signalName Name of the signal - * @return A helper object for convenient emission of signals - * - * This is a high-level, convenience way of emitting D-Bus signals that abstracts - * from the D-Bus message concept. Signal arguments are automatically serialized - * in a message and D-Bus signatures automatically deduced from the provided native arguments. - * - * Example of use: - * @code - * int arg1 = ...; - * double arg2 = ...; - * object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Emits signal on D-Bus + * + * @param[in] signalName Name of the signal + * @return A helper object for convenient emission of signals + * + * This is a high-level, convenience way of emitting D-Bus signals that abstracts + * from the D-Bus message concept. Signal arguments are automatically serialized + * in a message and D-Bus signatures automatically deduced from the provided native arguments. + * + * Example of use: + * @code + * int arg1 = ...; + * double arg2 = ...; + * object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2); + * @endcode + * + * @throws sdbus::Error in case of failure + */ SignalEmitter emitSignal(const std::string& signalName); }; @@ -412,23 +412,23 @@ namespace sdbus { } /*! - * @brief Creates instance representing a D-Bus object - * - * @param[in] connection D-Bus connection to be used by the object - * @param[in] objectPath Path of the D-Bus object - * @return Pointer to the object representation instance - * - * The provided connection will be used by the object to export methods, - * issue signals and provide properties. - * - * Creating a D-Bus object instance is (thread-)safe even upon the connection - * which is already running its processing loop. - * - * Code example: - * @code - * auto proxy = sdbus::createObject(connection, "/com/kistler/foo"); - * @endcode - */ + * @brief Creates instance representing a D-Bus object + * + * @param[in] connection D-Bus connection to be used by the object + * @param[in] objectPath Path of the D-Bus object + * @return Pointer to the object representation instance + * + * The provided connection will be used by the object to export methods, + * issue signals and provide properties. + * + * Creating a D-Bus object instance is (thread-)safe even upon the connection + * which is already running its processing loop. + * + * Code example: + * @code + * auto proxy = sdbus::createObject(connection, "/com/kistler/foo"); + * @endcode + */ std::unique_ptr createObject(sdbus::IConnection& connection, std::string objectPath); } diff --git a/include/sdbus-c++/IProxy.h b/include/sdbus-c++/IProxy.h index 0855319..51db3ab 100644 --- a/include/sdbus-c++/IProxy.h +++ b/include/sdbus-c++/IProxy.h @@ -61,205 +61,205 @@ namespace sdbus { virtual ~IProxy() = default; /*! - * @brief Creates a method call message - * - * @param[in] interfaceName Name of an interface that provides a given method - * @param[in] methodName Name of the method - * @return A method call message - * - * Serialize method arguments into the returned message and invoke the method by passing - * the message with serialized arguments to the @c callMethod function. - * Alternatively, use higher-level API @c callMethod(const std::string& methodName) defined below. - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates a method call message + * + * @param[in] interfaceName Name of an interface that provides a given method + * @param[in] methodName Name of the method + * @return A method call message + * + * Serialize method arguments into the returned message and invoke the method by passing + * the message with serialized arguments to the @c callMethod function. + * Alternatively, use higher-level API @c callMethod(const std::string& methodName) defined below. + * + * @throws sdbus::Error in case of failure + */ virtual MethodCall createMethodCall(const std::string& interfaceName, const std::string& methodName) = 0; /*! - * @brief Creates an asynchronous method call message - * - * @param[in] interfaceName Name of an interface that provides a given method - * @param[in] methodName Name of the method - * @return A method call message - * - * Serialize method arguments into the returned message and invoke the method by passing - * the message with serialized arguments to the @c callMethod function. - * Alternatively, use higher-level API @c callMethodAsync(const std::string& methodName) defined below. - * - * @throws sdbus::Error in case of failure - */ + * @brief Creates an asynchronous method call message + * + * @param[in] interfaceName Name of an interface that provides a given method + * @param[in] methodName Name of the method + * @return A method call message + * + * Serialize method arguments into the returned message and invoke the method by passing + * the message with serialized arguments to the @c callMethod function. + * Alternatively, use higher-level API @c callMethodAsync(const std::string& methodName) defined below. + * + * @throws sdbus::Error in case of failure + */ virtual AsyncMethodCall createAsyncMethodCall(const std::string& interfaceName, const std::string& methodName) = 0; /*! - * @brief Calls method on the proxied D-Bus object - * - * @param[in] message Message representing a method call - * @return A method reply message - * - * Normally, the call is blocking, i.e. it waits for the remote method to finish with either - * a return value or an error. - * - * If the method call argument is set to not expect reply, the call will not wait for the remote - * method to finish, i.e. the call will be non-blocking, and the function will return an empty, - * invalid MethodReply object (representing void). - * - * Note: To avoid messing with messages, use higher-level API defined below. - * - * @throws sdbus::Error in case of failure - */ + * @brief Calls method on the proxied D-Bus object + * + * @param[in] message Message representing a method call + * @return A method reply message + * + * Normally, the call is blocking, i.e. it waits for the remote method to finish with either + * a return value or an error. + * + * If the method call argument is set to not expect reply, the call will not wait for the remote + * method to finish, i.e. the call will be non-blocking, and the function will return an empty, + * invalid MethodReply object (representing void). + * + * Note: To avoid messing with messages, use higher-level API defined below. + * + * @throws sdbus::Error in case of failure + */ virtual MethodReply callMethod(const MethodCall& message) = 0; /*! - * @brief Calls method on the proxied D-Bus object asynchronously - * - * @param[in] message Message representing an async method call - * @param[in] asyncReplyCallback Handler for the async reply - * - * The call is non-blocking. It doesn't wait for the reply. Once the reply arrives, - * the provided async reply handler will get invoked from the context of the connection - * event loop processing thread. - * - * Note: To avoid messing with messages, use higher-level API defined below. - * - * @throws sdbus::Error in case of failure - */ + * @brief Calls method on the proxied D-Bus object asynchronously + * + * @param[in] message Message representing an async method call + * @param[in] asyncReplyCallback Handler for the async reply + * + * The call is non-blocking. It doesn't wait for the reply. Once the reply arrives, + * the provided async reply handler will get invoked from the context of the connection + * event loop processing thread. + * + * Note: To avoid messing with messages, use higher-level API defined below. + * + * @throws sdbus::Error in case of failure + */ virtual void callMethod(const AsyncMethodCall& message, async_reply_handler asyncReplyCallback) = 0; /*! - * @brief Registers a handler for the desired signal emitted by the proxied D-Bus object - * - * @param[in] interfaceName Name of an interface that the signal belongs to - * @param[in] signalName Name of the signal - * @param[in] signalHandler Callback that implements the body of the signal handler - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers a handler for the desired signal emitted by the proxied D-Bus object + * + * @param[in] interfaceName Name of an interface that the signal belongs to + * @param[in] signalName Name of the signal + * @param[in] signalHandler Callback that implements the body of the signal handler + * + * @throws sdbus::Error in case of failure + */ virtual void registerSignalHandler( const std::string& interfaceName , const std::string& signalName , signal_handler signalHandler ) = 0; /*! - * @brief Finishes the registration of signal handlers - * - * The method physically subscribes to the desired signals. - * Must be called only once, after all signals have been registered already. - * - * @throws sdbus::Error in case of failure - */ + * @brief Finishes the registration of signal handlers + * + * The method physically subscribes to the desired signals. + * Must be called only once, after all signals have been registered already. + * + * @throws sdbus::Error in case of failure + */ virtual void finishRegistration() = 0; /*! - * @brief Unregisters proxy's signal handlers and stops receving replies to pending async calls - * - * Unregistration is done automatically also in proxy's destructor. This method makes - * sense if, in the process of proxy removal, we need to make sure that callbacks - * are unregistered explicitly before the final destruction of the proxy instance. - * - * @throws sdbus::Error in case of failure - */ + * @brief Unregisters proxy's signal handlers and stops receving replies to pending async calls + * + * Unregistration is done automatically also in proxy's destructor. This method makes + * sense if, in the process of proxy removal, we need to make sure that callbacks + * are unregistered explicitly before the final destruction of the proxy instance. + * + * @throws sdbus::Error in case of failure + */ virtual void unregister() = 0; /*! - * @brief Calls method on the proxied D-Bus object - * - * @param[in] methodName Name of the method - * @return A helper object for convenient invocation of the method - * - * This is a high-level, convenience way of calling D-Bus methods that abstracts - * from the D-Bus message concept. Method arguments/return value are automatically (de)serialized - * in a message and D-Bus signatures automatically deduced from the provided native arguments - * and return values. - * - * Example of use: - * @code - * int result, a = ..., b = ...; - * object_.callMethod("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Calls method on the proxied D-Bus object + * + * @param[in] methodName Name of the method + * @return A helper object for convenient invocation of the method + * + * This is a high-level, convenience way of calling D-Bus methods that abstracts + * from the D-Bus message concept. Method arguments/return value are automatically (de)serialized + * in a message and D-Bus signatures automatically deduced from the provided native arguments + * and return values. + * + * Example of use: + * @code + * int result, a = ..., b = ...; + * object_.callMethod("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result); + * @endcode + * + * @throws sdbus::Error in case of failure + */ MethodInvoker callMethod(const std::string& methodName); /*! - * @brief Calls method on the proxied D-Bus object asynchronously - * - * @param[in] methodName Name of the method - * @return A helper object for convenient asynchronous invocation of the method - * - * This is a high-level, convenience way of calling D-Bus methods that abstracts - * from the D-Bus message concept. Method arguments/return value are automatically (de)serialized - * in a message and D-Bus signatures automatically deduced from the provided native arguments - * and return values. - * - * Example of use: - * @code - * int a = ..., b = ...; - * object_.callMethodAsync("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).uponReplyInvoke([](int result) - * { - * std::cout << "Got result of multiplying " << a << " and " << b << ": " << result << std::endl; - * }); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Calls method on the proxied D-Bus object asynchronously + * + * @param[in] methodName Name of the method + * @return A helper object for convenient asynchronous invocation of the method + * + * This is a high-level, convenience way of calling D-Bus methods that abstracts + * from the D-Bus message concept. Method arguments/return value are automatically (de)serialized + * in a message and D-Bus signatures automatically deduced from the provided native arguments + * and return values. + * + * Example of use: + * @code + * int a = ..., b = ...; + * object_.callMethodAsync("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).uponReplyInvoke([](int result) + * { + * std::cout << "Got result of multiplying " << a << " and " << b << ": " << result << std::endl; + * }); + * @endcode + * + * @throws sdbus::Error in case of failure + */ AsyncMethodInvoker callMethodAsync(const std::string& methodName); /*! - * @brief Registers signal handler for a given signal of the proxied D-Bus object - * - * @param[in] signalName Name of the signal - * @return A helper object for convenient registration of the signal handler - * - * This is a high-level, convenience way of registering to D-Bus signals that abstracts - * from the D-Bus message concept. Signal arguments are automatically serialized - * in a message and D-Bus signatures automatically deduced from the parameters - * of the provided native signal callback. - * - * Example of use: - * @code - * object_.uponSignal("fooSignal").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onFooSignal(arg1, arg2); }); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Registers signal handler for a given signal of the proxied D-Bus object + * + * @param[in] signalName Name of the signal + * @return A helper object for convenient registration of the signal handler + * + * This is a high-level, convenience way of registering to D-Bus signals that abstracts + * from the D-Bus message concept. Signal arguments are automatically serialized + * in a message and D-Bus signatures automatically deduced from the parameters + * of the provided native signal callback. + * + * Example of use: + * @code + * object_.uponSignal("fooSignal").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onFooSignal(arg1, arg2); }); + * @endcode + * + * @throws sdbus::Error in case of failure + */ SignalSubscriber uponSignal(const std::string& signalName); /*! - * @brief Gets value of a property of the proxied D-Bus object - * - * @param[in] propertyName Name of the property - * @return A helper object for convenient getting of property value - * - * This is a high-level, convenience way of reading D-Bus property values that abstracts - * from the D-Bus message concept. sdbus::Variant is returned which shall then be converted - * to the real property type (implicit conversion is supported). - * - * Example of use: - * @code - * int state = object.getProperty("state").onInterface("com.kistler.foo"); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Gets value of a property of the proxied D-Bus object + * + * @param[in] propertyName Name of the property + * @return A helper object for convenient getting of property value + * + * This is a high-level, convenience way of reading D-Bus property values that abstracts + * from the D-Bus message concept. sdbus::Variant is returned which shall then be converted + * to the real property type (implicit conversion is supported). + * + * Example of use: + * @code + * int state = object.getProperty("state").onInterface("com.kistler.foo"); + * @endcode + * + * @throws sdbus::Error in case of failure + */ PropertyGetter getProperty(const std::string& propertyName); /*! - * @brief Sets value of a property of the proxied D-Bus object - * - * @param[in] propertyName Name of the property - * @return A helper object for convenient setting of property value - * - * This is a high-level, convenience way of writing D-Bus property values that abstracts - * from the D-Bus message concept. - * - * Example of use: - * @code - * int state = ...; - * object_.setProperty("state").onInterface("com.kistler.foo").toValue(state); - * @endcode - * - * @throws sdbus::Error in case of failure - */ + * @brief Sets value of a property of the proxied D-Bus object + * + * @param[in] propertyName Name of the property + * @return A helper object for convenient setting of property value + * + * This is a high-level, convenience way of writing D-Bus property values that abstracts + * from the D-Bus message concept. + * + * Example of use: + * @code + * int state = ...; + * object_.setProperty("state").onInterface("com.kistler.foo").toValue(state); + * @endcode + * + * @throws sdbus::Error in case of failure + */ PropertySetter setProperty(const std::string& propertyName); }; @@ -289,68 +289,68 @@ namespace sdbus { } /*! - * @brief Creates a proxy object for a specific remote D-Bus object - * - * @param[in] connection D-Bus connection to be used by the proxy object - * @param[in] destination Bus name that provides the remote D-Bus object - * @param[in] objectPath Path of the remote D-Bus object - * @return Pointer to the proxy object instance - * - * The provided connection will be used by the proxy to issue calls against the object, - * and signals, if any, will be subscribed to on this connection. The caller still - * remains the owner of the connection (the proxy just keeps a reference to it), and - * should make sure that a processing loop is running on that connection, so the proxy - * may receive incoming signals and asynchronous method replies. - * - * Code example: - * @code - * auto proxy = sdbus::createProxy(connection, "com.kistler.foo", "/com/kistler/foo"); - * @endcode - */ + * @brief Creates a proxy object for a specific remote D-Bus object + * + * @param[in] connection D-Bus connection to be used by the proxy object + * @param[in] destination Bus name that provides the remote D-Bus object + * @param[in] objectPath Path of the remote D-Bus object + * @return Pointer to the proxy object instance + * + * The provided connection will be used by the proxy to issue calls against the object, + * and signals, if any, will be subscribed to on this connection. The caller still + * remains the owner of the connection (the proxy just keeps a reference to it), and + * should make sure that a processing loop is running on that connection, so the proxy + * may receive incoming signals and asynchronous method replies. + * + * Code example: + * @code + * auto proxy = sdbus::createProxy(connection, "com.kistler.foo", "/com/kistler/foo"); + * @endcode + */ std::unique_ptr createProxy( sdbus::IConnection& connection , std::string destination , std::string objectPath ); /*! - * @brief Creates a proxy object for a specific remote D-Bus object - * - * @param[in] connection D-Bus connection to be used by the proxy object - * @param[in] destination Bus name that provides the remote D-Bus object - * @param[in] objectPath Path of the remote D-Bus object - * @return Pointer to the object proxy instance - * - * The provided connection will be used by the proxy to issue calls against the object, - * and signals, if any, will be subscribed to on this connection. The Object proxy becomes - * an exclusive owner of this connection, and will automatically start a procesing loop - * 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. - * - * Code example: - * @code - * auto proxy = sdbus::createProxy(std::move(connection), "com.kistler.foo", "/com/kistler/foo"); - * @endcode - */ + * @brief Creates a proxy object for a specific remote D-Bus object + * + * @param[in] connection D-Bus connection to be used by the proxy object + * @param[in] destination Bus name that provides the remote D-Bus object + * @param[in] objectPath Path of the remote D-Bus object + * @return Pointer to the object proxy instance + * + * The provided connection will be used by the proxy to issue calls against the object, + * and signals, if any, will be subscribed to on this connection. The Object proxy becomes + * an exclusive owner of this connection, and will automatically start a procesing loop + * 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. + * + * Code example: + * @code + * auto proxy = sdbus::createProxy(std::move(connection), "com.kistler.foo", "/com/kistler/foo"); + * @endcode + */ std::unique_ptr createProxy( std::unique_ptr&& connection , std::string destination , std::string objectPath ); /*! - * @brief Creates a proxy object for a specific remote D-Bus object - * - * @param[in] destination Bus name that provides the remote D-Bus object - * @param[in] objectPath Path of the remote D-Bus object - * @return Pointer to the object proxy instance - * - * No D-Bus connection is provided here, so the object proxy will create and manage - * his own connection, and will automatically start a procesing loop 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. - * - * Code example: - * @code - * auto proxy = sdbus::createProxy("com.kistler.foo", "/com/kistler/foo"); - * @endcode - */ + * @brief Creates a proxy object for a specific remote D-Bus object + * + * @param[in] destination Bus name that provides the remote D-Bus object + * @param[in] objectPath Path of the remote D-Bus object + * @return Pointer to the object proxy instance + * + * No D-Bus connection is provided here, so the object proxy will create and manage + * his own connection, and will automatically start a procesing loop 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. + * + * Code example: + * @code + * auto proxy = sdbus::createProxy("com.kistler.foo", "/com/kistler/foo"); + * @endcode + */ std::unique_ptr createProxy( std::string destination , std::string objectPath ); diff --git a/include/sdbus-c++/ProxyInterfaces.h b/include/sdbus-c++/ProxyInterfaces.h index f471ed5..9747960 100644 --- a/include/sdbus-c++/ProxyInterfaces.h +++ b/include/sdbus-c++/ProxyInterfaces.h @@ -94,14 +94,14 @@ namespace sdbus { { public: /*! - * @brief Creates native-like proxy object instance - * - * @param[in] destination Bus name that provides a D-Bus object - * @param[in] objectPath Path of the D-Bus object - * - * This constructor overload creates a proxy that manages its own D-Bus connection(s). - * For more information on its behavior, consult @ref createProxy(std::string,std::string) - */ + * @brief Creates native-like proxy object instance + * + * @param[in] destination Bus name that provides a D-Bus object + * @param[in] objectPath Path of the D-Bus object + * + * This constructor overload creates a proxy that manages its own D-Bus connection(s). + * For more information on its behavior, consult @ref createProxy(std::string,std::string) + */ ProxyInterfaces(std::string destination, std::string objectPath) : ProxyObjectHolder(createProxy(std::move(destination), std::move(objectPath))) , _Interfaces(getProxy())... @@ -109,15 +109,15 @@ namespace sdbus { } /*! - * @brief Creates native-like proxy object instance - * - * @param[in] connection D-Bus connection to be used by the proxy object - * @param[in] destination Bus name that provides a D-Bus object - * @param[in] objectPath Path of the D-Bus object - * - * The proxy created this way just references a D-Bus connection owned and managed by the user. - * For more information on its behavior, consult @ref createProxy(IConnection&,std::string,std::string) - */ + * @brief Creates native-like proxy object instance + * + * @param[in] connection D-Bus connection to be used by the proxy object + * @param[in] destination Bus name that provides a D-Bus object + * @param[in] objectPath Path of the D-Bus object + * + * The proxy created this way just references a D-Bus connection owned and managed by the user. + * For more information on its behavior, consult @ref createProxy(IConnection&,std::string,std::string) + */ ProxyInterfaces(IConnection& connection, std::string destination, std::string objectPath) : ProxyObjectHolder(createProxy(connection, std::move(destination), std::move(objectPath))) , _Interfaces(getProxy())... @@ -125,15 +125,15 @@ namespace sdbus { } /*! - * @brief Creates native-like proxy object instance - * - * @param[in] connection D-Bus connection to be used by the proxy object - * @param[in] destination Bus name that provides a D-Bus object - * @param[in] objectPath Path of the D-Bus object - * - * The proxy created this way becomes an owner of the connection. - * For more information on its behavior, consult @ref createProxy(std::unique_ptr&&,std::string,std::string) - */ + * @brief Creates native-like proxy object instance + * + * @param[in] connection D-Bus connection to be used by the proxy object + * @param[in] destination Bus name that provides a D-Bus object + * @param[in] objectPath Path of the D-Bus object + * + * The proxy created this way becomes an owner of the connection. + * For more information on its behavior, consult @ref createProxy(std::unique_ptr&&,std::string,std::string) + */ ProxyInterfaces(std::unique_ptr&& connection, std::string destination, std::string objectPath) : ProxyObjectHolder(createProxy(std::move(connection), std::move(destination), std::move(objectPath))) , _Interfaces(getProxy())...