Gio::DBus Namespace Reference

Namespaces

namespace Error

Typedefs

typedef sigc::slot< void,
const Glib::RefPtr
< Gio::DBusConnection >
&, Glib::ustring
SlotBusAcquired
 For example, void on_bus_acquired(const Glib::RefPtr<Gio::DBusConnection>& connection, const Glib::ustring& name);.
typedef sigc::slot< void,
const Glib::RefPtr
< Gio::DBusConnection >
&, Glib::ustring
SlotNameAcquired
 For example, void on_name_acquired(const Glib::RefPtr<Gio::DBusConnection>& connection, const Glib::ustring& name);.
typedef sigc::slot< void,
const Glib::RefPtr
< Gio::DBusConnection >
&, Glib::ustring
SlotNameLost
 For example, void on_name_lost(const Glib::RefPtr<Gio::DBusConnection>& connection, const Glib::ustring& name);.
typedef sigc::slot< void,
const Glib::RefPtr
< Gio::DBusConnection >
&, Glib::ustring, const
Glib::ustring& > 
SlotNameAppeared
 For example, void on_name_appeared(const Glib::RefPtr<Gio::DBusConnection>& connection, const Glib::ustring& name, const Glib::ustring& name_owner);.
typedef sigc::slot< void,
const Glib::RefPtr
< Gio::DBusConnection >
&, Glib::ustring
SlotNameVanished
 For example, void on_name_vanished(const Glib::RefPtr<Gio::DBusConnection>& connection, const Glib::ustring& name);.

Enumerations

enum BusNameOwnerFlags {
  BUS_NAME_OWNER_FLAGS_NONE = 0x0,
  BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT = (1<<0),
  BUS_NAME_OWNER_FLAGS_REPLACE = (1<<1)
}
enum BusNameWatcherFlags {
  BUS_NAME_WATCHER_FLAGS_NONE = 0x0,
  BUS_NAME_WATCHER_FLAGS_AUTO_START = (1<<0)
}

Functions

BusNameOwnerFlags operator| (BusNameOwnerFlags lhs, BusNameOwnerFlags rhs)
BusNameOwnerFlags operator& (BusNameOwnerFlags lhs, BusNameOwnerFlags rhs)
BusNameOwnerFlags operator^ (BusNameOwnerFlags lhs, BusNameOwnerFlags rhs)
BusNameOwnerFlags operator~ (BusNameOwnerFlags flags)
BusNameOwnerFlagsoperator|= (BusNameOwnerFlags& lhs, BusNameOwnerFlags rhs)
BusNameOwnerFlagsoperator&= (BusNameOwnerFlags& lhs, BusNameOwnerFlags rhs)
BusNameOwnerFlagsoperator^= (BusNameOwnerFlags& lhs, BusNameOwnerFlags rhs)
guint own_name (BusType bus_type, const Glib::ustring& name, BusNameOwnerFlags flags, const SlotBusAcquired& bus_acquired_slot, const SlotNameAcquired& name_acquired_slot, const SlotNameLost& name_lost_slot)
 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.
void unown_name (guint owner_id)
 Stops owning a name.
Glib::ustring generate_guid ()
 Generate a D-Bus GUID that can be used with e.g.
bool is_guid (const Glib::ustring&string)
 Checks if string is a D-Bus GUID.
bool is_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus bus name (either unique or well-known).
bool is_unique_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus unique bus name.
bool is_member_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus member (e.g.
bool is_interface_name (const Glib::ustring&string)
 Checks if string is a valid D-Bus interface name.
BusNameWatcherFlags operator| (BusNameWatcherFlags lhs, BusNameWatcherFlags rhs)
BusNameWatcherFlags operator& (BusNameWatcherFlags lhs, BusNameWatcherFlags rhs)
BusNameWatcherFlags operator^ (BusNameWatcherFlags lhs, BusNameWatcherFlags rhs)
BusNameWatcherFlags operator~ (BusNameWatcherFlags flags)
BusNameWatcherFlagsoperator|= (BusNameWatcherFlags& lhs, BusNameWatcherFlags rhs)
BusNameWatcherFlagsoperator&= (BusNameWatcherFlags& lhs, BusNameWatcherFlags rhs)
BusNameWatcherFlagsoperator^= (BusNameWatcherFlags& lhs, BusNameWatcherFlags rhs)
guint watch_name (BusType bus_type, const Glib::ustring& name, BusNameWatcherFlags flags, const SlotNameAppeared& name_appeared_slot, const SlotNameVanished& name_vanished_slot)
 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.
guint watch_name (const Glib::RefPtr< DBusConnection >& connection, const Glib::ustring& name, BusNameWatcherFlags flags, const SlotNameAppeared& name_appeared_slot, const SlotNameVanished& name_vanished_slot)
 A watch_name() function that takes a DBusConnection instead of a BusType.
void unwatch_name (guint watcher_id)
 Stops watching a name.

Typedef Documentation

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

Since glibmm 2.26:

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

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

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

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


Function Documentation

Glib::ustring Gio::DBus::generate_guid (  ) 

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

Gio::DBusConnection::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.26:
bool Gio::DBus::is_guid ( const Glib::ustring 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:
string The string to check.
Returns:
true if string is a guid, false otherwise.
Since glibmm 2.26:
bool Gio::DBus::is_interface_name ( const Glib::ustring string  ) 

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

Parameters:
string The string to check.
Returns:
true if valid, false otherwise.
Since glibmm 2.26:
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:
string The string to check.
Returns:
true if valid, false otherwise.
Since glibmm 2.26:
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:
string The string to check.
Returns:
true if valid, false otherwise.
Since glibmm 2.26:
bool Gio::DBus::is_unique_name ( const Glib::ustring string  ) 

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

Parameters:
string The string to check.
Returns:
true if valid, false otherwise.
Since glibmm 2.26:
guint Gio::DBus::own_name ( BusType  bus_type,
const Glib::ustring name,
BusNameOwnerFlags  flags,
const SlotBusAcquired &  bus_acquired_slot,
const SlotNameAcquired &  name_acquired_slot,
const SlotNameLost &  name_lost_slot 
)

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 NULL 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 DBusConnection 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_type The type of bus to own a name on.
name The well-known name to own.
flags A set of flags from the BusNameOwnerFlags enumeration.
bus_acquired_slot Slot to invoke when connected to the bus of type bus_type.
name_acquired_slot Slot to invoke when name is acquired.
name_lost_slot Slot to invoke when name is lost.
Returns:
An identifier (never 0) that an be used with unown_name() to stop owning the name.
Since glibmm 2.26:
void Gio::DBus::unown_name ( guint  owner_id  ) 

Stops owning a name.

Parameters:
owner_id An identifier obtained from own_name().
void Gio::DBus::unwatch_name ( guint  watcher_id  ) 

Stops watching a name.

Parameters:
watcher_id An identifier obtained from watch_name().
guint Gio::DBus::watch_name ( const Glib::RefPtr< DBusConnection >&  connection,
const Glib::ustring name,
BusNameWatcherFlags  flags,
const SlotNameAppeared &  name_appeared_slot,
const SlotNameVanished &  name_vanished_slot 
)

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

Parameters:
connection A DBusConnection.
name The name (well-known or unique) to watch.
flags Flags from the BusNameWatcherFlags enumeration.
name_appeared_slot Slot to invoke when name is known to exist.
name_vanished_slot Slot to invoke when name is known to not exist.
Returns:
 An identifier (never 0) that can be used with unwatch_name() to stop watching the name.
Since glibmm 2.26:
guint Gio::DBus::watch_name ( BusType  bus_type,
const Glib::ustring name,
BusNameWatcherFlags  flags,
const SlotNameAppeared &  name_appeared_slot,
const SlotNameVanished &  name_vanished_slot 
)

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 DBusConnection 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_type The type of bus to watch a name on.
name The name (well-known or unique) to watch.
flags Flags from the BusNameWatcherFlags enumeration.
name_appeared_slot Slot to invoke when name is known to exist.
name_vanished_slot Slot to invoke when name is known to not exist.
Returns:
 An identifier (never 0) that can be used with unwatch_name() to stop watching the name.
Since glibmm 2.26:
Generated on Sun Sep 19 21:30:39 2010 for glibmm by  doxygen 1.6.3