Kistler-Group/sdbus-cpp
1
0
Fork 1
mirror of https://github.com/Kistler-Group/sdbus-cpp.git synced 2025-07-31 18:44:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Fix indentation of doxygen comments

Browse Source
This commit is contained in:
sangelovic
2019-06-04 22:21:49 +02:00
parent 07625a435b
commit 946cc8d0cd
4 changed files with 530 additions and 530 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
include/sdbus-c++/IConnection.h
View File

@@ -48,117 +48,117 @@ namespace sdbus {
virtual ~IConnection() = default; virtual ~IConnection() = default;
/*! /*!
* @brief Requests D-Bus name on the connection * @brief Requests D-Bus name on the connection
* *
* @param[in] name Name to request * @param[in] name Name to request
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void requestName(const std::string& name) = 0; virtual void requestName(const std::string& name) = 0;
/*! /*!
* @brief Releases D-Bus name on the connection * @brief Releases D-Bus name on the connection
* *
* @param[in] name Name to release * @param[in] name Name to release
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void releaseName(const std::string& name) = 0; virtual void releaseName(const std::string& name) = 0;
/*! /*!
* @brief Enters the D-Bus processing loop * @brief Enters the D-Bus processing loop
* *
* The incoming D-Bus messages are processed in the loop. The method * The incoming D-Bus messages are processed in the loop. The method
* blocks indefinitely, until unblocked via leaveProcessingLoop. * blocks indefinitely, until unblocked via leaveProcessingLoop.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void enterProcessingLoop() = 0; virtual void enterProcessingLoop() = 0;
/*! /*!
* @brief Enters the D-Bus processing loop in a separate thread * @brief Enters the D-Bus processing loop in a separate thread
* *
* The same as enterProcessingLoop, except that it doesn't block * The same as enterProcessingLoop, except that it doesn't block
* because it runs the loop in a separate thread managed internally. * because it runs the loop in a separate thread managed internally.
*/ */
virtual void enterProcessingLoopAsync() = 0; virtual void enterProcessingLoopAsync() = 0;
/*! /*!
* @brief Leaves the D-Bus processing loop * @brief Leaves the D-Bus processing loop
* *
* Ends the previously started processing loop. * Ends the previously started processing loop.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void leaveProcessingLoop() = 0; virtual void leaveProcessingLoop() = 0;
/*! /*!
* @brief Adds an ObjectManager at the specified D-Bus object path * @brief Adds an ObjectManager at the specified D-Bus object path
* *
* Creates an ObjectManager interface at the specified object path on * Creates an ObjectManager interface at the specified object path on
* the connection. This is a convenient way to interrogate a connection * the connection. This is a convenient way to interrogate a connection
* to see what objects it has. * to see what objects it has.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void addObjectManager(const std::string& objectPath) = 0; virtual void addObjectManager(const std::string& objectPath) = 0;
}; };
/*! /*!
* @brief Creates/opens D-Bus system connection * @brief Creates/opens D-Bus system connection
* *
* @return Connection instance * @return Connection instance
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
std::unique_ptr<sdbus::IConnection> createConnection(); std::unique_ptr<sdbus::IConnection> createConnection();
/*! /*!
* @brief Creates/opens D-Bus system connection with a name * @brief Creates/opens D-Bus system connection with a name
* *
* @param[in] name Name to request on the connection after its opening * @param[in] name Name to request on the connection after its opening
* @return Connection instance * @return Connection instance
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
std::unique_ptr<sdbus::IConnection> createConnection(const std::string& name); std::unique_ptr<sdbus::IConnection> createConnection(const std::string& name);
/*! /*!
* @brief Creates/opens D-Bus system connection * @brief Creates/opens D-Bus system connection
* *
* @return Connection instance * @return Connection instance
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
std::unique_ptr<sdbus::IConnection> createSystemBusConnection(); std::unique_ptr<sdbus::IConnection> createSystemBusConnection();
/*! /*!
* @brief Creates/opens D-Bus system connection with a name * @brief Creates/opens D-Bus system connection with a name
* *
* @param[in] name Name to request on the connection after its opening * @param[in] name Name to request on the connection after its opening
* @return Connection instance * @return Connection instance
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
std::unique_ptr<sdbus::IConnection> createSystemBusConnection(const std::string& name); std::unique_ptr<sdbus::IConnection> createSystemBusConnection(const std::string& name);
/*! /*!
* @brief Creates/opens D-Bus session connection * @brief Creates/opens D-Bus session connection
* *
* @return Connection instance * @return Connection instance
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
std::unique_ptr<sdbus::IConnection> createSessionBusConnection(); std::unique_ptr<sdbus::IConnection> createSessionBusConnection();
/*! /*!
* @brief Creates/opens D-Bus session connection with a name * @brief Creates/opens D-Bus session connection with a name
* *
* @param[in] name Name to request on the connection after its opening * @param[in] name Name to request on the connection after its opening
* @return Connection instance * @return Connection instance
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
std::unique_ptr<sdbus::IConnection> createSessionBusConnection(const std::string& name); std::unique_ptr<sdbus::IConnection> createSessionBusConnection(const std::string& name);
} }

422
include/sdbus-c++/IObject.h
View File

@@ -61,17 +61,17 @@ namespace sdbus {
virtual ~IObject() = default; virtual ~IObject() = default;
/*! /*!
* @brief Registers method that the object will provide on D-Bus * @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] interfaceName Name of an interface that the method will belong to
* @param[in] methodName Name of the method * @param[in] methodName Name of the method
* @param[in] inputSignature D-Bus signature of method input parameters * @param[in] inputSignature D-Bus signature of method input parameters
* @param[in] outputSignature D-Bus signature of method output parameters * @param[in] outputSignature D-Bus signature of method output parameters
* @param[in] methodCallback Callback that implements the body of the method * @param[in] methodCallback Callback that implements the body of the method
* @param[in] flags D-Bus method flags (privileged, deprecated, or no reply) * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply)
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void registerMethod( const std::string& interfaceName virtual void registerMethod( const std::string& interfaceName
, const std::string& methodName , const std::string& methodName
, const std::string& inputSignature , const std::string& inputSignature
@@ -80,31 +80,31 @@ namespace sdbus {
, Flags flags = {} ) = 0; , Flags flags = {} ) = 0;
/*! /*!
* @brief Registers signal that the object will emit on D-Bus * @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] interfaceName Name of an interface that the signal will fall under
* @param[in] signalName Name of the signal * @param[in] signalName Name of the signal
* @param[in] signature D-Bus signature of signal parameters * @param[in] signature D-Bus signature of signal parameters
* @param[in] flags D-Bus signal flags (deprecated) * @param[in] flags D-Bus signal flags (deprecated)
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void registerSignal( const std::string& interfaceName virtual void registerSignal( const std::string& interfaceName
, const std::string& signalName , const std::string& signalName
, const std::string& signature , const std::string& signature
, Flags flags = {} ) = 0; , Flags flags = {} ) = 0;
/*! /*!
* @brief Registers read-only property that the object will provide on D-Bus * @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] interfaceName Name of an interface that the property will fall under
* @param[in] propertyName Name of the property * @param[in] propertyName Name of the property
* @param[in] signature D-Bus signature of property parameters * @param[in] signature D-Bus signature of property parameters
* @param[in] getCallback Callback that implements the body of the property getter * @param[in] getCallback Callback that implements the body of the property getter
* @param[in] flags D-Bus property flags (deprecated, property update behavior) * @param[in] flags D-Bus property flags (deprecated, property update behavior)
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void registerProperty( const std::string& interfaceName virtual void registerProperty( const std::string& interfaceName
, const std::string& propertyName , const std::string& propertyName
, const std::string& signature , const std::string& signature
@@ -112,17 +112,17 @@ namespace sdbus {
, Flags flags = {} ) = 0; , Flags flags = {} ) = 0;
/*! /*!
* @brief Registers read/write property that the object will provide on D-Bus * @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] interfaceName Name of an interface that the property will fall under
* @param[in] propertyName Name of the property * @param[in] propertyName Name of the property
* @param[in] signature D-Bus signature of property parameters * @param[in] signature D-Bus signature of property parameters
* @param[in] getCallback Callback that implements the body of the property getter * @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] setCallback Callback that implements the body of the property setter
* @param[in] flags D-Bus property flags (deprecated, property update behavior) * @param[in] flags D-Bus property flags (deprecated, property update behavior)
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void registerProperty( const std::string& interfaceName virtual void registerProperty( const std::string& interfaceName
, const std::string& propertyName , const std::string& propertyName
, const std::string& signature , const std::string& signature
@@ -131,80 +131,80 @@ namespace sdbus {
, Flags flags = {} ) = 0; , Flags flags = {} ) = 0;
/*! /*!
* @brief Sets flags for a given interface * @brief Sets flags for a given interface
* *
* @param[in] interfaceName Name of an interface whose flags will be set * @param[in] interfaceName Name of an interface whose flags will be set
* @param[in] flags Flags to be set * @param[in] flags Flags to be set
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void setInterfaceFlags(const std::string& interfaceName, Flags flags) = 0; virtual void setInterfaceFlags(const std::string& interfaceName, Flags flags) = 0;
/*! /*!
* @brief Finishes object API registration and publishes the object on the bus * @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. * 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. * Must be called after all methods, signals and properties have been registered.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void finishRegistration() = 0; virtual void finishRegistration() = 0;
/*! /*!
* @brief Unregisters object's API and removes object from the bus * @brief Unregisters object's API and removes object from the bus
* *
* This method unregisters the object, its interfaces, methods, signals and properties * This method unregisters the object, its interfaces, methods, signals and properties
* from the bus. Unregistration is done automatically also in object's destructor. This * 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 * 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. * callbacks are unregistered explicitly before the final destruction of the object instance.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void unregister() = 0; virtual void unregister() = 0;
/*! /*!
* @brief Creates a signal message * @brief Creates a signal message
* *
* @param[in] interfaceName Name of an interface that the signal belongs under * @param[in] interfaceName Name of an interface that the signal belongs under
* @param[in] signalName Name of the signal * @param[in] signalName Name of the signal
* @return A signal message * @return A signal message
* *
* Serialize signal arguments into the returned message and emit the signal by passing * Serialize signal arguments into the returned message and emit the signal by passing
* the message with serialized arguments to the @c emitSignal function. * the message with serialized arguments to the @c emitSignal function.
* Alternatively, use higher-level API @c emitSignal(const std::string& signalName) defined below. * Alternatively, use higher-level API @c emitSignal(const std::string& signalName) defined below.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual Signal createSignal(const std::string& interfaceName, const std::string& signalName) = 0; virtual Signal createSignal(const std::string& interfaceName, const std::string& signalName) = 0;
/*! /*!
* @brief Emits signal for this object path * @brief Emits signal for this object path
* *
* @param[in] message Signal message to be sent out * @param[in] message Signal message to be sent out
* *
* Note: To avoid messing with messages, use higher-level API defined below. * Note: To avoid messing with messages, use higher-level API defined below.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void emitSignal(const sdbus::Signal& message) = 0; virtual void emitSignal(const sdbus::Signal& message) = 0;
/*! /*!
* @brief Emits PropertyChanged signal for specified properties under a given interface of this object path * @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] interfaceName Name of an interface that properties belong to
* @param[in] propNames Names of properties that will be included in the PropertiesChanged signal * @param[in] propNames Names of properties that will be included in the PropertiesChanged signal
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void emitPropertiesChangedSignal(const std::string& interfaceName, const std::vector<std::string>& propNames) = 0; virtual void emitPropertiesChangedSignal(const std::string& interfaceName, const std::vector<std::string>& propNames) = 0;
/*! /*!
* @brief Emits PropertyChanged signal for all properties on a given interface of this object path * @brief Emits PropertyChanged signal for all properties on a given interface of this object path
* *
* @param[in] interfaceName Name of an interface * @param[in] interfaceName Name of an interface
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void emitPropertiesChangedSignal(const std::string& interfaceName) = 0; virtual void emitPropertiesChangedSignal(const std::string& interfaceName) = 0;
/*! /*!
@@ -259,21 +259,21 @@ namespace sdbus {
virtual void emitInterfacesRemovedSignal(const std::vector<std::string>& interfaces) = 0; virtual void emitInterfacesRemovedSignal(const std::vector<std::string>& interfaces) = 0;
/*! /*!
* @brief Adds an ObjectManager interface at the path of this D-Bus object * @brief Adds an ObjectManager interface at the path of this D-Bus object
* *
* Creates an ObjectManager interface at the specified object path on * Creates an ObjectManager interface at the specified object path on
* the connection. This is a convenient way to interrogate a connection * the connection. This is a convenient way to interrogate a connection
* to see what objects it has. * to see what objects it has.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void addObjectManager() = 0; virtual void addObjectManager() = 0;
/*! /*!
* @brief Removes an ObjectManager interface from the path of this D-Bus object * @brief Removes an ObjectManager interface from the path of this D-Bus object
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void removeObjectManager() = 0; virtual void removeObjectManager() = 0;
/*! /*!
@@ -283,106 +283,106 @@ namespace sdbus {
virtual bool hasObjectManager() const = 0; virtual bool hasObjectManager() const = 0;
/*! /*!
* @brief Provides D-Bus connection used by the object * @brief Provides D-Bus connection used by the object
* *
* @return Reference to the D-Bus connection * @return Reference to the D-Bus connection
*/ */
virtual sdbus::IConnection& getConnection() const = 0; virtual sdbus::IConnection& getConnection() const = 0;
/*! /*!
* @brief Registers method that the object will provide on D-Bus * @brief Registers method that the object will provide on D-Bus
* *
* @param[in] methodName Name of the method * @param[in] methodName Name of the method
* @return A helper object for convenient registration 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 * 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 * 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 * in a message and D-Bus signatures automatically deduced from the parameters and return type
* of the provided native method implementation callback. * of the provided native method implementation callback.
* *
* Example of use: * Example of use:
* @code * @code
* object.registerMethod("doFoo").onInterface("com.kistler.foo").implementedAs([this](int value){ return this->doFoo(value); }); * object.registerMethod("doFoo").onInterface("com.kistler.foo").implementedAs([this](int value){ return this->doFoo(value); });
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
MethodRegistrator registerMethod(const std::string& methodName); MethodRegistrator registerMethod(const std::string& methodName);
/*! /*!
* @brief Registers signal that the object will provide on D-Bus * @brief Registers signal that the object will provide on D-Bus
* *
* @param[in] signalName Name of the signal * @param[in] signalName Name of the signal
* @return A helper object for convenient registration 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 * 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 * 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. * in a message and D-Bus signatures automatically deduced from the provided native parameters.
* *
* Example of use: * Example of use:
* @code * @code
* object.registerSignal("paramChange").onInterface("com.kistler.foo").withParameters<std::map<int32_t, std::string>>(); * object.registerSignal("paramChange").onInterface("com.kistler.foo").withParameters<std::map<int32_t, std::string>>();
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
SignalRegistrator registerSignal(const std::string& signalName); SignalRegistrator registerSignal(const std::string& signalName);
/*! /*!
* @brief Registers property that the object will provide on D-Bus * @brief Registers property that the object will provide on D-Bus
* *
* @param[in] propertyName Name of the property * @param[in] propertyName Name of the property
* @return A helper object for convenient registration 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 * 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 * 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. * in a message and D-Bus signatures automatically deduced from the provided native callbacks.
* *
* Example of use: * Example of use:
* @code * @code
* object_.registerProperty("state").onInterface("com.kistler.foo").withGetter([this](){ return this->state(); }); * object_.registerProperty("state").onInterface("com.kistler.foo").withGetter([this](){ return this->state(); });
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
PropertyRegistrator registerProperty(const std::string& propertyName); PropertyRegistrator registerProperty(const std::string& propertyName);
/*! /*!
* @brief Sets flags (annotations) for a given interface * @brief Sets flags (annotations) for a given interface
* *
* @param[in] interfaceName Name of an interface whose flags will be set * @param[in] interfaceName Name of an interface whose flags will be set
* @return A helper object for convenient setting of Interface flags * @return A helper object for convenient setting of Interface flags
* *
* This is a high-level, convenience alternative to the other setInterfaceFlags overload. * This is a high-level, convenience alternative to the other setInterfaceFlags overload.
* *
* Example of use: * Example of use:
* @code * @code
* object_.setInterfaceFlags("com.kistler.foo").markAsDeprecated().withPropertyUpdateBehavior(sdbus::Flags::EMITS_NO_SIGNAL); * object_.setInterfaceFlags("com.kistler.foo").markAsDeprecated().withPropertyUpdateBehavior(sdbus::Flags::EMITS_NO_SIGNAL);
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
InterfaceFlagsSetter setInterfaceFlags(const std::string& interfaceName); InterfaceFlagsSetter setInterfaceFlags(const std::string& interfaceName);
/*! /*!
* @brief Emits signal on D-Bus * @brief Emits signal on D-Bus
* *
* @param[in] signalName Name of the signal * @param[in] signalName Name of the signal
* @return A helper object for convenient emission of signals * @return A helper object for convenient emission of signals
* *
* This is a high-level, convenience way of emitting D-Bus signals that abstracts * 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 * 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. * in a message and D-Bus signatures automatically deduced from the provided native arguments.
* *
* Example of use: * Example of use:
* @code * @code
* int arg1 = ...; * int arg1 = ...;
* double arg2 = ...; * double arg2 = ...;
* object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2); * object_.emitSignal("fooSignal").onInterface("com.kistler.foo").withArguments(arg1, arg2);
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
SignalEmitter emitSignal(const std::string& signalName); SignalEmitter emitSignal(const std::string& signalName);
}; };
@@ -412,23 +412,23 @@ namespace sdbus {
} }
/*! /*!
* @brief Creates instance representing a D-Bus object * @brief Creates instance representing a D-Bus object
* *
* @param[in] connection D-Bus connection to be used by the object * @param[in] connection D-Bus connection to be used by the object
* @param[in] objectPath Path of the D-Bus object * @param[in] objectPath Path of the D-Bus object
* @return Pointer to the object representation instance * @return Pointer to the object representation instance
* *
* The provided connection will be used by the object to export methods, * The provided connection will be used by the object to export methods,
* issue signals and provide properties. * issue signals and provide properties.
* *
* Creating a D-Bus object instance is (thread-)safe even upon the connection * Creating a D-Bus object instance is (thread-)safe even upon the connection
* which is already running its processing loop. * which is already running its processing loop.
* *
* Code example: * Code example:
* @code * @code
* auto proxy = sdbus::createObject(connection, "/com/kistler/foo"); * auto proxy = sdbus::createObject(connection, "/com/kistler/foo");
* @endcode * @endcode
*/ */
std::unique_ptr<sdbus::IObject> createObject(sdbus::IConnection& connection, std::string objectPath); std::unique_ptr<sdbus::IObject> createObject(sdbus::IConnection& connection, std::string objectPath);
} }

432
include/sdbus-c++/IProxy.h
View File

@@ -61,205 +61,205 @@ namespace sdbus {
virtual ~IProxy() = default; virtual ~IProxy() = default;
/*! /*!
* @brief Creates a method call message * @brief Creates a method call message
* *
* @param[in] interfaceName Name of an interface that provides a given method * @param[in] interfaceName Name of an interface that provides a given method
* @param[in] methodName Name of the method * @param[in] methodName Name of the method
* @return A method call message * @return A method call message
* *
* Serialize method arguments into the returned message and invoke the method by passing * Serialize method arguments into the returned message and invoke the method by passing
* the message with serialized arguments to the @c callMethod function. * the message with serialized arguments to the @c callMethod function.
* Alternatively, use higher-level API @c callMethod(const std::string& methodName) defined below. * Alternatively, use higher-level API @c callMethod(const std::string& methodName) defined below.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual MethodCall createMethodCall(const std::string& interfaceName, const std::string& methodName) = 0; virtual MethodCall createMethodCall(const std::string& interfaceName, const std::string& methodName) = 0;
/*! /*!
* @brief Creates an asynchronous method call message * @brief Creates an asynchronous method call message
* *
* @param[in] interfaceName Name of an interface that provides a given method * @param[in] interfaceName Name of an interface that provides a given method
* @param[in] methodName Name of the method * @param[in] methodName Name of the method
* @return A method call message * @return A method call message
* *
* Serialize method arguments into the returned message and invoke the method by passing * Serialize method arguments into the returned message and invoke the method by passing
* the message with serialized arguments to the @c callMethod function. * the message with serialized arguments to the @c callMethod function.
* Alternatively, use higher-level API @c callMethodAsync(const std::string& methodName) defined below. * Alternatively, use higher-level API @c callMethodAsync(const std::string& methodName) defined below.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual AsyncMethodCall createAsyncMethodCall(const std::string& interfaceName, const std::string& methodName) = 0; virtual AsyncMethodCall createAsyncMethodCall(const std::string& interfaceName, const std::string& methodName) = 0;
/*! /*!
* @brief Calls method on the proxied D-Bus object * @brief Calls method on the proxied D-Bus object
* *
* @param[in] message Message representing a method call * @param[in] message Message representing a method call
* @return A method reply message * @return A method reply message
* *
* Normally, the call is blocking, i.e. it waits for the remote method to finish with either * Normally, the call is blocking, i.e. it waits for the remote method to finish with either
* a return value or an error. * 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 * 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, * method to finish, i.e. the call will be non-blocking, and the function will return an empty,
* invalid MethodReply object (representing void). * invalid MethodReply object (representing void).
* *
* Note: To avoid messing with messages, use higher-level API defined below. * Note: To avoid messing with messages, use higher-level API defined below.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual MethodReply callMethod(const MethodCall& message) = 0; virtual MethodReply callMethod(const MethodCall& message) = 0;
/*! /*!
* @brief Calls method on the proxied D-Bus object asynchronously * @brief Calls method on the proxied D-Bus object asynchronously
* *
* @param[in] message Message representing an async method call * @param[in] message Message representing an async method call
* @param[in] asyncReplyCallback Handler for the async reply * @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 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 * the provided async reply handler will get invoked from the context of the connection
* event loop processing thread. * event loop processing thread.
* *
* Note: To avoid messing with messages, use higher-level API defined below. * Note: To avoid messing with messages, use higher-level API defined below.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void callMethod(const AsyncMethodCall& message, async_reply_handler asyncReplyCallback) = 0; 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 * @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] interfaceName Name of an interface that the signal belongs to
* @param[in] signalName Name of the signal * @param[in] signalName Name of the signal
* @param[in] signalHandler Callback that implements the body of the signal handler * @param[in] signalHandler Callback that implements the body of the signal handler
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void registerSignalHandler( const std::string& interfaceName virtual void registerSignalHandler( const std::string& interfaceName
, const std::string& signalName , const std::string& signalName
, signal_handler signalHandler ) = 0; , signal_handler signalHandler ) = 0;
/*! /*!
* @brief Finishes the registration of signal handlers * @brief Finishes the registration of signal handlers
* *
* The method physically subscribes to the desired signals. * The method physically subscribes to the desired signals.
* Must be called only once, after all signals have been registered already. * Must be called only once, after all signals have been registered already.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void finishRegistration() = 0; virtual void finishRegistration() = 0;
/*! /*!
* @brief Unregisters proxy's signal handlers and stops receving replies to pending async calls * @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 * 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 * 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. * are unregistered explicitly before the final destruction of the proxy instance.
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
virtual void unregister() = 0; virtual void unregister() = 0;
/*! /*!
* @brief Calls method on the proxied D-Bus object * @brief Calls method on the proxied D-Bus object
* *
* @param[in] methodName Name of the method * @param[in] methodName Name of the method
* @return A helper object for convenient invocation 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 * 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 * 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 * in a message and D-Bus signatures automatically deduced from the provided native arguments
* and return values. * and return values.
* *
* Example of use: * Example of use:
* @code * @code
* int result, a = ..., b = ...; * int result, a = ..., b = ...;
* object_.callMethod("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result); * object_.callMethod("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).storeResultsTo(result);
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
MethodInvoker callMethod(const std::string& methodName); MethodInvoker callMethod(const std::string& methodName);
/*! /*!
* @brief Calls method on the proxied D-Bus object asynchronously * @brief Calls method on the proxied D-Bus object asynchronously
* *
* @param[in] methodName Name of the method * @param[in] methodName Name of the method
* @return A helper object for convenient asynchronous invocation 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 * 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 * 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 * in a message and D-Bus signatures automatically deduced from the provided native arguments
* and return values. * and return values.
* *
* Example of use: * Example of use:
* @code * @code
* int a = ..., b = ...; * int a = ..., b = ...;
* object_.callMethodAsync("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).uponReplyInvoke([](int result) * object_.callMethodAsync("multiply").onInterface(INTERFACE_NAME).withArguments(a, b).uponReplyInvoke([](int result)
* { * {
* std::cout << "Got result of multiplying " << a << " and " << b << ": " << result << std::endl; * std::cout << "Got result of multiplying " << a << " and " << b << ": " << result << std::endl;
* }); * });
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
AsyncMethodInvoker callMethodAsync(const std::string& methodName); AsyncMethodInvoker callMethodAsync(const std::string& methodName);
/*! /*!
* @brief Registers signal handler for a given signal of the proxied D-Bus object * @brief Registers signal handler for a given signal of the proxied D-Bus object
* *
* @param[in] signalName Name of the signal * @param[in] signalName Name of the signal
* @return A helper object for convenient registration of the signal handler * @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 * 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 * from the D-Bus message concept. Signal arguments are automatically serialized
* in a message and D-Bus signatures automatically deduced from the parameters * in a message and D-Bus signatures automatically deduced from the parameters
* of the provided native signal callback. * of the provided native signal callback.
* *
* Example of use: * Example of use:
* @code * @code
* object_.uponSignal("fooSignal").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onFooSignal(arg1, arg2); }); * object_.uponSignal("fooSignal").onInterface("com.kistler.foo").call([this](int arg1, double arg2){ this->onFooSignal(arg1, arg2); });
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
SignalSubscriber uponSignal(const std::string& signalName); SignalSubscriber uponSignal(const std::string& signalName);
/*! /*!
* @brief Gets value of a property of the proxied D-Bus object * @brief Gets value of a property of the proxied D-Bus object
* *
* @param[in] propertyName Name of the property * @param[in] propertyName Name of the property
* @return A helper object for convenient getting of property value * @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 * 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 * from the D-Bus message concept. sdbus::Variant is returned which shall then be converted
* to the real property type (implicit conversion is supported). * to the real property type (implicit conversion is supported).
* *
* Example of use: * Example of use:
* @code * @code
* int state = object.getProperty("state").onInterface("com.kistler.foo"); * int state = object.getProperty("state").onInterface("com.kistler.foo");
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
PropertyGetter getProperty(const std::string& propertyName); PropertyGetter getProperty(const std::string& propertyName);
/*! /*!
* @brief Sets value of a property of the proxied D-Bus object * @brief Sets value of a property of the proxied D-Bus object
* *
* @param[in] propertyName Name of the property * @param[in] propertyName Name of the property
* @return A helper object for convenient setting of property value * @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 * This is a high-level, convenience way of writing D-Bus property values that abstracts
* from the D-Bus message concept. * from the D-Bus message concept.
* *
* Example of use: * Example of use:
* @code * @code
* int state = ...; * int state = ...;
* object_.setProperty("state").onInterface("com.kistler.foo").toValue(state); * object_.setProperty("state").onInterface("com.kistler.foo").toValue(state);
* @endcode * @endcode
* *
* @throws sdbus::Error in case of failure * @throws sdbus::Error in case of failure
*/ */
PropertySetter setProperty(const std::string& propertyName); PropertySetter setProperty(const std::string& propertyName);
}; };
@@ -289,68 +289,68 @@ namespace sdbus {
} }
/*! /*!
* @brief Creates a proxy object for a specific remote D-Bus object * @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] 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] destination Bus name that provides the remote D-Bus object
* @param[in] objectPath Path of the remote D-Bus object * @param[in] objectPath Path of the remote D-Bus object
* @return Pointer to the proxy object instance * @return Pointer to the proxy object instance
* *
* The provided connection will be used by the proxy to issue calls against the object, * 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 * 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 * 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 * should make sure that a processing loop is running on that connection, so the proxy
* may receive incoming signals and asynchronous method replies. * may receive incoming signals and asynchronous method replies.
* *
* Code example: * Code example:
* @code * @code
* auto proxy = sdbus::createProxy(connection, "com.kistler.foo", "/com/kistler/foo"); * auto proxy = sdbus::createProxy(connection, "com.kistler.foo", "/com/kistler/foo");
* @endcode * @endcode
*/ */
std::unique_ptr<sdbus::IProxy> createProxy( sdbus::IConnection& connection std::unique_ptr<sdbus::IProxy> createProxy( sdbus::IConnection& connection
, std::string destination , std::string destination
, std::string objectPath ); , std::string objectPath );
/*! /*!
* @brief Creates a proxy object for a specific remote D-Bus object * @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] 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] destination Bus name that provides the remote D-Bus object
* @param[in] objectPath Path of the remote D-Bus object * @param[in] objectPath Path of the remote D-Bus object
* @return Pointer to the object proxy instance * @return Pointer to the object proxy instance
* *
* The provided connection will be used by the proxy to issue calls against the object, * 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 * 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 * 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 * 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. * asynchronous method replies will be executed in the context of that thread.
* *
* Code example: * Code example:
* @code * @code
* auto proxy = sdbus::createProxy(std::move(connection), "com.kistler.foo", "/com/kistler/foo"); * auto proxy = sdbus::createProxy(std::move(connection), "com.kistler.foo", "/com/kistler/foo");
* @endcode * @endcode
*/ */
std::unique_ptr<sdbus::IProxy> createProxy( std::unique_ptr<sdbus::IConnection>&& connection std::unique_ptr<sdbus::IProxy> createProxy( std::unique_ptr<sdbus::IConnection>&& connection
, std::string destination , std::string destination
, std::string objectPath ); , std::string objectPath );
/*! /*!
* @brief Creates a proxy object for a specific remote D-Bus object * @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] destination Bus name that provides the remote D-Bus object
* @param[in] objectPath Path of the remote D-Bus object * @param[in] objectPath Path of the remote D-Bus object
* @return Pointer to the object proxy instance * @return Pointer to the object proxy instance
* *
* No D-Bus connection is provided here, so the object proxy will create and manage * 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 * his own connection, and will automatically start a procesing loop upon that connection
* in a separate internal thread. Handlers for incoming signals and asynchronous * in a separate internal thread. Handlers for incoming signals and asynchronous
* method replies will be executed in the context of that thread. * method replies will be executed in the context of that thread.
* *
* Code example: * Code example:
* @code * @code
* auto proxy = sdbus::createProxy("com.kistler.foo", "/com/kistler/foo"); * auto proxy = sdbus::createProxy("com.kistler.foo", "/com/kistler/foo");
* @endcode * @endcode
*/ */
std::unique_ptr<sdbus::IProxy> createProxy( std::string destination std::unique_ptr<sdbus::IProxy> createProxy( std::string destination
, std::string objectPath ); , std::string objectPath );

52
include/sdbus-c++/ProxyInterfaces.h
View File

@@ -94,14 +94,14 @@ namespace sdbus {
{ {
public: public:
/*! /*!
* @brief Creates native-like proxy object instance * @brief Creates native-like proxy object instance
* *
* @param[in] destination Bus name that provides a D-Bus object * @param[in] destination Bus name that provides a D-Bus object
* @param[in] objectPath Path of the 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). * 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) * For more information on its behavior, consult @ref createProxy(std::string,std::string)
*/ */
ProxyInterfaces(std::string destination, std::string objectPath) ProxyInterfaces(std::string destination, std::string objectPath)
: ProxyObjectHolder(createProxy(std::move(destination), std::move(objectPath))) : ProxyObjectHolder(createProxy(std::move(destination), std::move(objectPath)))
, _Interfaces(getProxy())... , _Interfaces(getProxy())...
@@ -109,15 +109,15 @@ namespace sdbus {
} }
/*! /*!
* @brief Creates native-like proxy object instance * @brief Creates native-like proxy object instance
* *
* @param[in] connection D-Bus connection to be used by the proxy object * @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] destination Bus name that provides a D-Bus object
* @param[in] objectPath Path of the 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. * 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) * For more information on its behavior, consult @ref createProxy(IConnection&,std::string,std::string)
*/ */
ProxyInterfaces(IConnection& connection, std::string destination, std::string objectPath) ProxyInterfaces(IConnection& connection, std::string destination, std::string objectPath)
: ProxyObjectHolder(createProxy(connection, std::move(destination), std::move(objectPath))) : ProxyObjectHolder(createProxy(connection, std::move(destination), std::move(objectPath)))
, _Interfaces(getProxy())... , _Interfaces(getProxy())...
@@ -125,15 +125,15 @@ namespace sdbus {
} }
/*! /*!
* @brief Creates native-like proxy object instance * @brief Creates native-like proxy object instance
* *
* @param[in] connection D-Bus connection to be used by the proxy object * @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] destination Bus name that provides a D-Bus object
* @param[in] objectPath Path of the D-Bus object * @param[in] objectPath Path of the D-Bus object
* *
* The proxy created this way becomes an owner of the connection. * The proxy created this way becomes an owner of the connection.
* For more information on its behavior, consult @ref createProxy(std::unique_ptr<sdbus::IConnection>&&,std::string,std::string) * For more information on its behavior, consult @ref createProxy(std::unique_ptr<sdbus::IConnection>&&,std::string,std::string)
*/ */
ProxyInterfaces(std::unique_ptr<sdbus::IConnection>&& connection, std::string destination, std::string objectPath) ProxyInterfaces(std::unique_ptr<sdbus::IConnection>&& connection, std::string destination, std::string objectPath)
: ProxyObjectHolder(createProxy(std::move(connection), std::move(destination), std::move(objectPath))) : ProxyObjectHolder(createProxy(std::move(connection), std::move(destination), std::move(objectPath)))
, _Interfaces(getProxy())... , _Interfaces(getProxy())...