Wraps a dbus connection pointer and runs the dispatch loop for it. More...

#include <DbusConnection.h>

Collaboration diagram for AI_IPC::DbusConnection:

[legend]

Classes
struct	_ReplyContext

Public Member Functions
bool	connect (DBusBusType busType, const std::string &serviceName=std::string())
	Attempts to connect to one of the known buses and optionally reserve the given service name. More...

bool	connect (const std::string &address, const std::string &serviceName=std::string())
	Attempts to connect to the bus and optionally reserve the given service name. More...

void	disconnect ()
	Disconnect from the bus. More...

void	registerMessageHandler (const std::function< DBusHandlerResult(DBusMessage *)> &handler)
	Registers a handler to be called when any message (method call or signal) is received. More...

bool	sendMessageNoReply (DBusMessage *msg)
	Sends a message on the connection without expecting a reply. More...

uint64_t	sendMessageWithReply (DBusMessage *msg, int timeout)
	Sends a dbus message out the connection. More...

DBusMessage *	getReply (uint64_t token)
	Gets the reply for the given request. More...

bool	cancelReply (uint64_t token)
	Cancels waiting for the reply. More...

bool	nameHasOwner (const std::string &name)
	Returns true if the supplied name exists on the bus. More...

uid_t	getUnixUser (const std::string &name)
	Returns the unix user id of the named client. More...

bool	addMatch (const std::string &rule)
	Adds a match rule for the connection. More...

bool	removeMatch (const std::string &rule)
	Removes a match rule from the connection. More...

std::string	getAddress ()

bool	flushConnection ()
	Flushes the dbus connection. More...

Private Types
typedef std::function< DBusHandlerResult(DBusMessage *)>	MessageHandler

typedef struct AI_IPC::DbusConnection::_ReplyContext	ReplyContext

Private Member Functions
bool	completeConnect (DBusConnection *conn, const std::string &serviceName)
	Completes the initialisation of the dbus connection. More...

bool	reserveServiceName (DBusConnection *dbusConnection, const std::string &name) const
	Attempts to reserve a service name on dbus. More...

Static Private Member Functions
static DBusHandlerResult	handleDbusMessageCb (DBusConnection connection, DBusMessage message, void *userData)
	Callback from the libdbus in the context of the event / dispatcher thread. More...

static void	pendingCallNotifyFcn (DBusPendingCall pending, void userData)
	Callback from libdus when either a reply is received for a pending call or the timeout expires. More...

static void	pendingCallFreeFcn (void *userData)
	Callback from libdus when a pending call notifier is being destroyed and we should clean up the context data. More...

Private Attributes
DBusConnection *	mDbusConnection

DbusEventDispatcher	mEventDispacher

MessageHandler	mHandler

AICommon::Spinlock	mHandlerLock

std::string	mServiceName

std::atomic< uint64_t >	mTokenCounter

AICommon::Mutex	mRepliesLock

AICommon::ConditionVariable	mRepliesCondVar

std::map< uint64_t, DBusMessage * >	mReplies

Detailed Description

Wraps a dbus connection pointer and runs the dispatch loop for it.

This class was added to force all libdus calls that take a DBusConnection* pointer as an argument to be routed through a single event loop thread.

Member Function Documentation

◆ addMatch()

bool DbusConnection::addMatch ( const std::string & rule )

Adds a match rule for the connection.

This calls dbus_bus_add_match(...), from the context of the dispatch thread loop.

Parameters

[in] rule The dbus match rule to add

Returns: true on success, false on failure.

◆ cancelReply()

bool DbusConnection::cancelReply ( uint64_t token )

Cancels waiting for the reply.

This frees the memory reserved for storing the reply.

Parameters

[in] token The token returned by the sendMessageWithReply(...) method.

Returns: true on success, false on failure.

◆ completeConnect()

bool DbusConnection::completeConnect	(	DBusConnection *	conn,
		const std::string &	serviceName
	)

private

Completes the initialisation of the dbus connection.

If an error occurs the supplied connection will be closed and unref'ed.

Parameters

[in]	conn	Pointer to the newly opened dbus connection.
[in]	serviceName	Service name to use for the connection.

Returns: true on success, false on failure.

◆ connect() [1/2]

bool DbusConnection::connect	(	const std::string &	address,
		const std::string &	serviceName = `std::string()`
	)

Attempts to connect to the bus and optionally reserve the given service name.

Parameters

[in]	address	The dbus address to connected to.
[in]	serviceName	Optional service name to use for the connection.

Returns: true on success, false on failure.

◆ connect() [2/2]

bool DbusConnection::connect	(	DBusBusType	busType,
		const std::string &	serviceName = `std::string()`
	)

Attempts to connect to one of the known buses and optionally reserve the given service name.

Parameters

[in]	busType	Must be either; DBUS_BUS_SESSION or DBUS_BUS_SYSTEM
[in]	serviceName	Optional service name to use for the connection.

Returns: true on success, false on failure.

◆ disconnect()

void DbusConnection::disconnect ( )

Disconnect from the bus.

This will also cancel any pending method calls.

◆ flushConnection()

bool DbusConnection::flushConnection ( )

Flushes the dbus connection.

This calls dbus_connection_flush(...), from the context of the dispatch thread loop.

Returns: true on success, false on failure.

◆ getReply()

DBusMessage * DbusConnection::getReply ( uint64_t token )

Gets the reply for the given request.

This method blocks until a reply or timeout has been received. The timeout time is set when the message was originally sent (by sendMessageWithReply). However there is a maximum timeout value of 120 seconds, this should never be hit in normal operation, if it is then it indicates a problem with the timeout code in libdbus.

Parameters

[in] token The token returned by the sendMessageWithReply(...) method.

Returns: on success the reply message, it is the callers responsbility to call dbus_message_unref on the message object. On failure a nullptr is returned.

◆ getUnixUser()

uid_t DbusConnection::getUnixUser ( const std::string & name )

Returns the unix user id of the named client.

This calls dbus_bus_get_unix_user(...), from the context of the dispatch thread loop.

Parameters

[in] name The client name to get the user id of.

Returns: positive user id if the name exists on the bus, -1 on error.

◆ handleDbusMessageCb()

DBusHandlerResult DbusConnection::handleDbusMessageCb	(	DBusConnection *	connection,
		DBusMessage *	message,
		void *	userData
	)

staticprivate

Callback from the libdbus in the context of the event / dispatcher thread.

This callback is installed right after we've connected, we hook this point so we can pass it onto the handler installed with registerMessageHandler

Parameters

[in]	connection	The connection dbus connection.
[in]	message	The message received.
[in]	userData	User data, in our case a pointer to this

Returns: if no handler is installed then DBUS_HANDLER_RESULT_NOT_YET_HANDLED is returned, otherwise the result returned by installed handler.

◆ nameHasOwner()

bool DbusConnection::nameHasOwner ( const std::string & name )

Returns true if the supplied name exists on the bus.

This calls dbus_bus_name_has_owner(...), from the context of the dispatch thread loop.

Parameters

[in] name The service name to search for.

Returns: true if the name exists on the bus, false on error or if the name is not on the bus.

◆ pendingCallFreeFcn()

void DbusConnection::pendingCallFreeFcn ( void * userData )

staticprivate

Callback from libdus when a pending call notifier is being destroyed and we should clean up the context data.

Parameters

[in] userData Pointer to the data to free.

◆ pendingCallNotifyFcn()

void DbusConnection::pendingCallNotifyFcn	(	DBusPendingCall *	pending,
		void *	userData
	)

staticprivate

Callback from libdus when either a reply is received for a pending call or the timeout expires.

The timeout for the call is set when the method call request is queued (i.e. with the sendMessageWithReply() method).

This is the point were we get the reply message (which could be a timeout message) and assign it against the token value stored in the map.

Parameters

[in]	pending	The pending call object that has completed
[in]	userData	User data, in our case a pointer to a ReplyContext object.

◆ registerMessageHandler()

void DbusConnection::registerMessageHandler ( const std::function< DBusHandlerResult(DBusMessage *)> & handler )

Registers a handler to be called when any message (method call or signal) is received.

Only one handler can be installed at a time, to remove the handler pass nullptr.

Parameters

[in] handler Function to call on receiving a message

◆ removeMatch()

bool DbusConnection::removeMatch ( const std::string & rule )

Removes a match rule from the connection.

This calls dbus_bus_remove_match(...), from the context of the dispatch thread loop.

Parameters

[in] rule The dbus match rule to remove.

Returns: true on success, false on failure.

◆ reserveServiceName()

bool DbusConnection::reserveServiceName	(	DBusConnection *	dbusConnection,
		const std::string &	name
	)		const

private

Attempts to reserve a service name on dbus.

Service names must be unique (per dbus) so if the name is already owned by another dbus client then this function will fail.

Parameters

[in]	dbusConnection	The dbus connection we want to reserve the name on.
[in]	name	The name we're trying to reserve.

Returns: true on success, false on failure.

◆ sendMessageNoReply()

bool DbusConnection::sendMessageNoReply ( DBusMessage * msg )

Sends a message on the connection without expecting a reply.

This is typically used for emitting a signal, however can be used for a method call that is not expecting a reply.

Parameters

[in] msg The message to send out the bus.

Returns: true on success, false on failure.

◆ sendMessageWithReply()

uint64_t DbusConnection::sendMessageWithReply	(	DBusMessage *	msg,
		int	timeout
	)

Sends a dbus message out the connection.

This calls dbus_connection_send_with_reply(...), from the context of the dispatch thread loop. If that succeeds it installs a notifier on the pending call result and allocates a reply token that the caller should use for getting the reply.

The returned token MUST be consumed by calling either getReply or cancelReply, if this is not done then the reply will be stored until the connection is disconnected.

Parameters

[in]	msg	The message to send, it should be a method call.
[in]	timeout	The timeout in milliseconds to wait for a response, if -1 then a 'sensible' default is used, typically 30 seconds.

Returns: a unique 64-bit token value to use for getting the reply message, on error 0 will be returned.

The documentation for this class was generated from the following files:

AppInfrastructure/IpcService/source/libdbus/DbusConnection.h
AppInfrastructure/IpcService/source/libdbus/DbusConnection.cpp

Classes

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ addMatch()

◆ cancelReply()

◆ completeConnect()

◆ connect() [1/2]

◆ connect() [2/2]

◆ disconnect()

◆ flushConnection()

◆ getReply()

◆ getUnixUser()

◆ handleDbusMessageCb()

◆ nameHasOwner()

◆ pendingCallFreeFcn()

◆ pendingCallNotifyFcn()

◆ registerMessageHandler()

◆ removeMatch()

◆ reserveServiceName()

◆ sendMessageNoReply()

◆ sendMessageWithReply()