glibmm: D-Bus API

API to use D-Bus services as a client or to implement a D-Bus service. More...

Classes

class  Gio::DBus::AuthObserver
 AuthObserver - An object used for authenticating connections. More...

 
class  Gio::DBus::Connection
 A D-Bus Connection. More...

 
class  Gio::DBus::InterfaceVTable
 This represents a virtual table for handling properties and method calls for a D-Bus interface. More...

 
class  Gio::DBus::AnnotationInfo
 Stores information about an annotation. More...

 
class  Gio::DBus::ArgInfo
 ArgInfo - Stores information about an argument for a method or a signal. More...

 
class  Gio::DBus::MethodInfo
 Stores information about a method on an D-Bus interface. More...

 
class  Gio::DBus::SignalInfo
 Stores information about a signal on a D-Bus interface. More...

 
class  Gio::DBus::PropertyInfo
 Stores information about a property on a D-Bus interface. More...

 
class  Gio::DBus::InterfaceInfo
 Stores information about a D-Bus interface. More...

 
class  Gio::DBus::NodeInfo
 NodeInfo - Stores information about nodes in a remote object hierarchy. More...

 
class  Gio::DBus::Message
 A type for representing D-Bus messages that can be sent or received on a Connection. More...

 
class  Gio::DBus::MethodInvocation
 An Object for handling remote calls. More...

 
class  Gio::DBus::ObjectManager
 Base type for D-Bus object managers. More...

 
class  Gio::DBus::ObjectManagerClient
 Client-side object manager. More...

 
class  Gio::DBus::ObjectManagerServer
 Service-side object manager. More...

 
class  Gio::DBus::ObjectProxy
 Client-side D-Bus object. More...

 
class  Gio::DBus::ObjectSkeleton
 Service-side D-Bus object. More...

 
class  Gio::DBus::Proxy
 A client-side proxy. More...

 
class  Gio::DBus::Server
 This is a helper for listening to and accepting D-Bus connections. More...

 
class  Gio::DBus::SubtreeVTable
 This represents a virtual table for subtrees registered with Gio::DBus::Connection::register_subtree(). More...

 

Typedefs

using Gio::DBus::SlotBusAcquired = sigc::slot< void(const Glib::RefPtr< Gio::DBus::Connection >&, Glib::ustring)>
 For example, void on_bus_acquired(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);. More...

 
using Gio::DBus::SlotNameAcquired = sigc::slot< void(const Glib::RefPtr< Gio::DBus::Connection >&, Glib::ustring)>
 For example, void on_name_acquired(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);. More...

 
using Gio::DBus::SlotNameLost = sigc::slot< void(const Glib::RefPtr< Gio::DBus::Connection >&, Glib::ustring)>
 For example, void on_name_lost(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);. More...

 
using Gio::DBus::SlotNameAppeared = sigc::slot< void(const Glib::RefPtr< Gio::DBus::Connection >&, Glib::ustring, const Glib::ustring&)>
 For example, void on_name_appeared(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name, const Glib::ustring& name_owner);. More...

 
using Gio::DBus::SlotNameVanished = sigc::slot< void(const Glib::RefPtr< Gio::DBus::Connection >&, Glib::ustring)>
 For example, void on_name_vanished(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);. More...

 

Functions

bool Gio::DBus::Address::is_address (const std::string&string)
 Checks if string is a D-Bus address. More...

 
bool Gio::DBus::Address::is_supported (const std::string& address)
 Like is_address() but also checks if the library supports the transports in address and that key/value pairs for each transport are valid. More...

 
void Gio::DBus::Address::get_stream (const std::string& address, const SlotAsyncReady slot, const Glib::RefPtr< Cancellable >& cancellable)
 Asynchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. More...

 
Glib::RefPtr< IOStream > Gio::DBus::Address::get_stream_finish (const Glib::RefPtr< AsyncResult >& res, std::string& out_guid)
 Finishes an operation started with get_stream(). More...

 
Glib::RefPtr< IOStream > Gio::DBus::Address::get_stream_finish (const Glib::RefPtr< AsyncResult >& res)
 Finishes an operation started with get_stream(). More...

 
Glib::RefPtr< IOStream > Gio::DBus::Address::get_stream_sync (const std::string& address, const Glib::RefPtr< Cancellable >& cancellable, std::string& out_guid)
 Synchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. More...

 
Glib::RefPtr< IOStream > Gio::DBus::Address::get_stream_sync (const std::string& address, const Glib::RefPtr< Cancellable >& cancellable)
 Synchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. More...

 
std::string Gio::DBus::Address::get_for_bus_sync (BusType bus_type, const Glib::RefPtr< Cancellable >& cancellable)
 Synchronously looks up the D-Bus address for the well-known message bus instance specified by bus_type. More...

 
bool Gio::DBus::ErrorUtils::is_remote_error (const Glib::Error& error)
 Checks if error represents an error received via D-Bus from a remote peer. More...

 
Glib::ustring Gio::DBus::ErrorUtils::get_remote_error (const Glib::Error& error)
 Gets the D-Bus error name used for error, if any. More...

 
bool Gio::DBus::ErrorUtils::strip_remote_error (Glib::Error& error)
 Looks for extra information in the error message used to recover the D-Bus error name and strips it if found. More...

 
guint Gio::DBus::own_name (BusType bus_type, const Glib::ustring& name, const SlotBusAcquired& bus_acquired_slot={}, const SlotNameAcquired& name_acquired_slot={}, const SlotNameLost& name_lost_slot={}, BusNameOwnerFlags flags=Gio::DBus::BusNameOwnerFlags::NONE)
 Starts acquiring name on the bus specified by bus_type and calls name_acquired_slot and name_lost_slot when the name is acquired respectively lost. More...

 
std::string Gio::DBus::generate_guid ()
 Generate a D-Bus GUID that can be used with e.g. More...

 
bool Gio::DBus::is_guid (const std::string&string)
 Checks if string is a D-Bus GUID. More...

 
bool Gio::DBus::is_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus bus name (either unique or well-known). More...

 
bool Gio::DBus::is_unique_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus unique bus name. More...

 
bool Gio::DBus::is_member_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus member (e.g. More...

 
bool Gio::DBus::is_interface_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus interface name. More...

 
guint Gio::DBus::watch_name (BusType bus_type, const Glib::ustring& name, const SlotNameAppeared& name_appeared_slot={}, const SlotNameVanished& name_vanished_slot={}, BusNameWatcherFlags flags=Gio::DBus::BusNameWatcherFlags::NONE)
 Starts watching name on the bus specified by bus_type and calls name_appeared_slot and name_vanished_slot when the name is known to have a owner respectively known to lose its owner. More...

 
guint Gio::DBus::watch_name (const Glib::RefPtr< Connection >& connection, const Glib::ustring& name, const SlotNameAppeared& name_appeared_slot={}, const SlotNameVanished& name_vanished_slot={}, BusNameWatcherFlags flags=Gio::DBus::BusNameWatcherFlags::NONE)
 A watch_name() function that takes a Connection instead of a BusType. More...

 
void Gio::DBus::unwatch_name (guint watcher_id)
 Stops watching a name. More...

 

Detailed Description

API to use D-Bus services as a client or to implement a D-Bus service.

To write client code, see Gio::DBus::Proxy. To export objects on the bus for other clients, see Gio::DBus::own_name(), for instance.

Typedef Documentation

using Gio::DBus::SlotBusAcquired = typedef sigc::slot<void(const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring)>

For example, void on_bus_acquired(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);.

Since glibmm 2.28:

For example, void on_name_acquired(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);.

For example, void on_name_appeared(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name, const Glib::ustring& name_owner);.

using Gio::DBus::SlotNameLost = typedef sigc::slot<void(const Glib::RefPtr<Gio::DBus::Connection>&, Glib::ustring)>

For example, void on_name_lost(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);.

For example, void on_name_vanished(const Glib::RefPtr<Gio::DBus::Connection>& connection, const Glib::ustring& name);.

Function Documentation

std::string Gio::DBus::generate_guid ( )

Generate a D-Bus GUID that can be used with e.g.

Gio::DBus::Connection::create().

See the D-Bus specification regarding what strings are valid D-Bus GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).

Returns
A valid D-Bus GUID.
Since glibmm 2.28:
std::string Gio::DBus::Address::get_for_bus_sync ( BusType  bus_type,
const Glib::RefPtr< Cancellable >&  cancellable 
)

Synchronously looks up the D-Bus address for the well-known message bus instance specified by bus_type.

This may involve using various platform specific mechanisms.

Parameters
bus_typeA BusType.
cancellableA Cancellable.
Returns
A valid D-Bus address string for bus_type.
Exceptions
Glib::Error.
Since glibmm 2.28:
Glib::ustring Gio::DBus::ErrorUtils::get_remote_error ( const Glib::Error error)

Gets the D-Bus error name used for error, if any.

This function is guaranteed to return a D-Bus error name for all Glib::Error instances returned from functions handling remote method calls (e.g. Gio::DBus::Connection::call_finish()) unless strip_remote_error() has been used on error.

Parameters
errorA Glib::Error.
Returns
An allocated string or 0 if the D-Bus error name could not be found.
Since glibmm 2.28:
void Gio::DBus::Address::get_stream ( const std::string address,
const SlotAsyncReady  slot,
const Glib::RefPtr< Cancellable >&  cancellable 
)

Asynchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation.

When the operation is finished, slot will be invoked. You can then call get_stream_finish() to get the result of the operation.

This is an asynchronous failable function. See get_stream_sync() for the synchronous version.

Parameters
addressA valid D-Bus address.
cancellableA Cancellable.
slotA SlotAsyncReady to call when the request is satisfied.
Since glibmm 2.28:
Glib::RefPtr<IOStream> Gio::DBus::Address::get_stream_finish ( const Glib::RefPtr< AsyncResult >&  res,
std::string out_guid 
)

Finishes an operation started with get_stream().

Parameters
resA AsyncResult obtained from the SlotAsyncReady passed to get_stream().
out_guidReturn location to store the GUID extracted from address, if any.
Returns
A IOStream.
Exceptions
Glib::Error.
Since glibmm 2.28:
Glib::RefPtr<IOStream> Gio::DBus::Address::get_stream_finish ( const Glib::RefPtr< AsyncResult >&  res)

Finishes an operation started with get_stream().

Parameters
resA AsyncResult obtained from the SlotAsyncReady passed to get_stream().
Returns
A IOStream.
Exceptions
Glib::Error.
Since glibmm 2.28:
Glib::RefPtr<IOStream> Gio::DBus::Address::get_stream_sync ( const std::string address,
const Glib::RefPtr< Cancellable >&  cancellable,
std::string out_guid 
)

Synchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation.

This is a synchronous failable function. See get_stream() for the asynchronous version.

Parameters
addressA valid D-Bus address.
cancellableA Cancellable.
out_guidA return location to store the GUID extracted from address, if any.
Returns
A IOStream.
Exceptions
Glib::Error.
Since glibmm 2.28:
Glib::RefPtr<IOStream> Gio::DBus::Address::get_stream_sync ( const std::string address,
const Glib::RefPtr< Cancellable >&  cancellable 
)

Synchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation.

This is a synchronous failable function. See get_stream() for the asynchronous version.

Parameters
addressA valid D-Bus address.
cancellableA Cancellable.
Returns
A IOStream.
Exceptions
Glib::Error.
Since glibmm 2.28:
bool Gio::DBus::Address::is_address ( const std::string string)

Checks if string is a D-Bus address.

This doesn't check if string is actually supported by BusServer or BusConnection - use is_supported_address() to do more checks.

Parameters
stringA string.
Returns
true if string is a valid D-Bus address, false otherwise.
Since glibmm 2.28:
bool Gio::DBus::is_guid ( const std::string string)

Checks if string is a D-Bus GUID.

See the D-Bus specification regarding what strings are valid D-Bus GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).

Parameters
stringThe string to check.
Returns
true if string is a guid, false otherwise.
Since glibmm 2.28:
bool Gio::DBus::is_interface_name ( const Glib::ustring string)

Checks if string is a valid D-Bus interface name.

Parameters
stringThe string to check.
Returns
true if valid, false otherwise.
Since glibmm 2.28:
bool Gio::DBus::is_member_name ( const Glib::ustring string)

Checks if string is a valid D-Bus member (e.g.

signal or method) name.

Parameters
stringThe string to check.
Returns
true if valid, false otherwise.
Since glibmm 2.28:
bool Gio::DBus::is_name ( const Glib::ustring string)

Checks if string is a valid D-Bus bus name (either unique or well-known).

Parameters
stringThe string to check.
Returns
true if valid, false otherwise.
Since glibmm 2.28:
bool Gio::DBus::ErrorUtils::is_remote_error ( const Glib::Error error)

Checks if error represents an error received via D-Bus from a remote peer.

If so, use get_remote_error() to get the name of the error.

Parameters
errorA Glib::Error.
Returns
true if error represents an error from a remote peer, false otherwise.
Since glibmm 2.28:
bool Gio::DBus::Address::is_supported ( const std::string address)

Like is_address() but also checks if the library supports the transports in address and that key/value pairs for each transport are valid.

Parameters
addressA supposed address.
Returns
true if address is a valid D-Bus address that is supported by this library, false otherwise.
Exceptions
Glib::Error.
Since glibmm 2.28:
bool Gio::DBus::is_unique_name ( const Glib::ustring string)

Checks if string is a valid D-Bus unique bus name.

Parameters
stringThe string to check.
Returns
true if valid, false otherwise.
Since glibmm 2.28:
guint Gio::DBus::own_name ( BusType  bus_type,
const Glib::ustring name,
const SlotBusAcquired bus_acquired_slot = {},
const SlotNameAcquired name_acquired_slot = {},
const SlotNameLost name_lost_slot = {},
BusNameOwnerFlags  flags = Gio::DBus::BusNameOwnerFlags::NONE 
)

Starts acquiring name on the bus specified by bus_type and calls name_acquired_slot and name_lost_slot when the name is acquired respectively lost.

Slots will be invoked in the thread-default main loop of the thread you are calling this function from.

You are guaranteed that one of the name_acquired_slot and name_lost_slot slots will be invoked after calling this function - there are three possible cases:

  • name_lost_slot with a nullptr connection (if a connection to the bus can't be made).
  • bus_acquired_slot then name_lost_slot (if the name can't be obtained)
  • bus_acquired_slot then name_acquired_slot (if the name was obtained).

When you are done owning the name, just call unown_name() with the owner id this function returns.

If the name is acquired or lost (for example another application could acquire the name if you allow replacement or the application currently owning the name exits), the slots are also invoked. If the Connection that is used for attempting to own the name closes, then name_lost_slot is invoked since it is no longer possible for other processes to access the process.

You cannot use own_name() several times for the same name (unless interleaved with calls to unown_name()) - only the first call will work.

Another guarantee is that invocations of name_acquired_slot and name_lost_slot are guaranteed to alternate; that is, if name_acquired_slot is invoked then you are guaranteed that the next time one of the slots is invoked, it will be name_lost_slot. The reverse is also true.

If you plan on exporting objects (using e.g. Gio::DbusConnection::register_object()), note that it is generally too late to export the objects in name_acquired_slot. Instead, you can do this in bus_acquired_slot since you are guaranteed that this will run before name is requested from the bus.

This behavior makes it very simple to write applications that wants to own names and export objects.

Parameters
bus_typeThe type of bus to own a name on.
nameThe well-known name to own.
bus_acquired_slotSlot to invoke when connected to the bus of type bus_type.
name_acquired_slotSlot to invoke when name is acquired.
name_lost_slotSlot to invoke when name is lost.
flagsA set of flags from the BusNameOwnerFlags enumeration.
Returns
An identifier (never 0) that an be used with unown_name() to stop owning the name.
Since glibmm 2.28:
bool Gio::DBus::ErrorUtils::strip_remote_error ( Glib::Error error)

Looks for extra information in the error message used to recover the D-Bus error name and strips it if found.

If stripped, the message field in error will correspond exactly to what was received on the wire.

This is typically used when presenting errors to the end user.

Parameters
errorA Glib::Error.
Returns
true if information was stripped, false otherwise.
Since glibmm 2.28:
void Gio::DBus::unwatch_name ( guint  watcher_id)

Stops watching a name.

Parameters
watcher_idAn identifier obtained from watch_name().
guint Gio::DBus::watch_name ( BusType  bus_type,
const Glib::ustring name,
const SlotNameAppeared name_appeared_slot = {},
const SlotNameVanished name_vanished_slot = {},
BusNameWatcherFlags  flags = Gio::DBus::BusNameWatcherFlags::NONE 
)

Starts watching name on the bus specified by bus_type and calls name_appeared_slot and name_vanished_slot when the name is known to have a owner respectively known to lose its owner.

Callbacks will be invoked in the thread-default main loop of the thread you are calling this function from.

You are guaranteed that one of the slot will be invoked after calling this function. When you are done watching the name, just call unwatch_name() with the watcher id this function returns.

If the name vanishes or appears (for example the application owning the name could restart), the slot are also invoked. If the Connection that is used for watching the name disconnects, then name_vanished_slot is invoked since it is no longer possible to access the name.

Another guarantee is that invocations of name_appeared_slot and name_vanished_slot are guaranteed to alternate; that is, if name_appeared_slot is invoked then you are guaranteed that the next time one of the slot is invoked, it will be name_vanished_slot. The reverse is also true.

This behavior makes it very simple to write applications that wants to take action when a certain name exists, see the C API's Example 9, “Simple application watching a name” for more information. Basically, the application should create object proxies in name_appeared_slot and destroy them again (if any) in name_vanished_slot.

Parameters
bus_typeThe type of bus to watch a name on.
nameThe name (well-known or unique) to watch.
name_appeared_slotSlot to invoke when name is known to exist.
name_vanished_slotSlot to invoke when name is known to not exist.
flagsFlags from the BusNameWatcherFlags enumeration.
Returns
An identifier (never 0) that can be used with unwatch_name() to stop watching the name.
Since glibmm 2.28:
guint Gio::DBus::watch_name ( const Glib::RefPtr< Connection >&  connection,
const Glib::ustring name,
const SlotNameAppeared name_appeared_slot = {},
const SlotNameVanished name_vanished_slot = {},
BusNameWatcherFlags  flags = Gio::DBus::BusNameWatcherFlags::NONE 
)

A watch_name() function that takes a Connection instead of a BusType.

Parameters
connectionA Connection.
nameThe name (well-known or unique) to watch.
name_appeared_slotSlot to invoke when name is known to exist.
name_vanished_slotSlot to invoke when name is known to not exist.
flagsFlags from the BusNameWatcherFlags enumeration.
Returns
An identifier (never 0) that can be used with unwatch_name() to stop watching the name.
Since glibmm 2.28: