D-Bus utilities

D-Bus utilities — some D-Bus utility functions

Functions

Types and Values

Object Hierarchy

    GFlags
    ╰── TpDBusNameType
    GObject
    ╰── TpProxy
        ╰── TpDBusDaemon

Includes

#include <telepathy-glib/telepathy-glib.h>

Description

D-Bus utility functions used in telepathy-glib.

Functions

tp_dbus_g_method_return_not_implemented ()

void
tp_dbus_g_method_return_not_implemented
                               (DBusGMethodInvocation *context);

Return the Telepathy error NotImplemented from the method invocation given by context .

Parameters

context

The D-Bus method invocation context

 

TP_TYPE_DBUS_NAME_TYPE

#define TP_TYPE_DBUS_NAME_TYPE (tp_dbus_name_type_get_type ())

The GFlagsClass type of a TpDBusNameType or a set of name types.

Since 0.11.5


tp_dbus_check_valid_bus_name ()

gboolean
tp_dbus_check_valid_bus_name (const gchar *name,
                              TpDBusNameType allow_types,
                              GError **error);

Check that the given string is a valid D-Bus bus name of an appropriate type.

Parameters

name

a possible bus name

 

allow_types

some combination of TP_DBUS_NAME_TYPE_UNIQUE, TP_DBUS_NAME_TYPE_WELL_KNOWN or TP_DBUS_NAME_TYPE_BUS_DAEMON (often this will be TP_DBUS_NAME_TYPE_NOT_BUS_DAEMON or TP_DBUS_NAME_TYPE_ANY)

 

error

used to raise TP_DBUS_ERROR_INVALID_BUS_NAME if FALSE is returned

 

Returns

TRUE if name is valid

Since 0.7.1


tp_dbus_check_valid_interface_name ()

gboolean
tp_dbus_check_valid_interface_name (const gchar *name,
                                    GError **error);

Check that the given string is a valid D-Bus interface name. This is also appropriate to use to check for valid error names.

Since GIO 2.26, g_dbus_is_interface_name() should always return the same thing, although the GLib function does not raise an error explaining why the interface name is incorrect.

Parameters

name

a possible interface name

 

error

used to raise TP_DBUS_ERROR_INVALID_INTERFACE_NAME if FALSE is returned

 

Returns

TRUE if name is valid

Since 0.7.1


tp_dbus_check_valid_member_name ()

gboolean
tp_dbus_check_valid_member_name (const gchar *name,
                                 GError **error);

Check that the given string is a valid D-Bus member (method or signal) name.

Since GIO 2.26, g_dbus_is_member_name() should always return the same thing, although the GLib function does not raise an error explaining why the interface name is incorrect.

Parameters

name

a possible member name

 

error

used to raise TP_DBUS_ERROR_INVALID_MEMBER_NAME if FALSE is returned

 

Returns

TRUE if name is valid

Since 0.7.1


tp_dbus_check_valid_object_path ()

gboolean
tp_dbus_check_valid_object_path (const gchar *path,
                                 GError **error);

Check that the given string is a valid D-Bus object path. Since GLib 2.24, g_variant_is_object_path() should always return the same thing as this function, although it doesn't provide an error explaining why the object path is invalid.

Parameters

path

a possible object path

 

error

used to raise TP_DBUS_ERROR_INVALID_OBJECT_PATH if FALSE is returned

 

Returns

TRUE if path is valid

Since 0.7.1


tp_g_value_slice_new_bytes ()

GValue *
tp_g_value_slice_new_bytes (guint length,
                            gconstpointer bytes);

Slice-allocate a GValue containing a byte-array, using tp_g_value_slice_new_boxed(). This function is convenient to use when constructing hash tables from string to GValue, for example.

Parameters

length

number of bytes to copy

 

bytes

location of an array of bytes to be copied (this may be NULL if and only if length is 0)

 

Returns

a GValue of type DBUS_TYPE_G_UCHAR_ARRAY whose value is a copy of length bytes from bytes , to be freed with tp_g_value_slice_free() or g_slice_free()

Since 0.7.27


tp_g_value_slice_new_take_bytes ()

GValue *
tp_g_value_slice_new_take_bytes (GArray *bytes);

Slice-allocate a GValue containing bytes , using tp_g_value_slice_new_boxed(). This function is convenient to use when constructing hash tables from string to GValue, for example.

Parameters

bytes

a non-NULL GArray of guchar, ownership of which will be taken by the GValue

 

Returns

a GValue of type DBUS_TYPE_G_UCHAR_ARRAY whose value is bytes , to be freed with tp_g_value_slice_free() or g_slice_free()

Since 0.7.27


tp_g_value_slice_new_object_path ()

GValue *
tp_g_value_slice_new_object_path (const gchar *path);

Slice-allocate a GValue containing an object path, using tp_g_value_slice_new_boxed(). This function is convenient to use when constructing hash tables from string to GValue, for example.

Parameters

path

a valid D-Bus object path which will be copied

 

Returns

a GValue of type DBUS_TYPE_G_OBJECT_PATH whose value is a copy of path , to be freed with tp_g_value_slice_free() or g_slice_free()

Since 0.7.27


tp_g_value_slice_new_static_object_path ()

GValue *
tp_g_value_slice_new_static_object_path
                               (const gchar *path);

Slice-allocate a GValue containing an object path, using tp_g_value_slice_new_static_boxed(). This function is convenient to use when constructing hash tables from string to GValue, for example.

Parameters

path

a valid D-Bus object path which must remain valid forever

 

Returns

a GValue of type DBUS_TYPE_G_OBJECT_PATH whose value is path , to be freed with tp_g_value_slice_free() or g_slice_free()

Since 0.7.27


tp_g_value_slice_new_take_object_path ()

GValue *
tp_g_value_slice_new_take_object_path (gchar *path);

Slice-allocate a GValue containing an object path, using tp_g_value_slice_new_take_boxed(). This function is convenient to use when constructing hash tables from string to GValue, for example.

Parameters

path

a valid D-Bus object path which will be freed with g_free() by the returned GValue (the caller must own it before calling this function, but no longer owns it after this function returns)

 

Returns

a GValue of type DBUS_TYPE_G_OBJECT_PATH whose value is path , to be freed with tp_g_value_slice_free() or g_slice_free()

Since 0.7.27


tp_dbus_daemon_dup ()

TpDBusDaemon *
tp_dbus_daemon_dup (GError **error);

Returns a proxy for signals and method calls on the D-Bus daemon on which this process was activated (if it was launched by D-Bus service activation), or the session bus (otherwise).

If it is not possible to connect to the appropriate bus, raise an error and return NULL.

The returned TpDBusDaemon is cached; the same TpDBusDaemon object will be returned by this function repeatedly, as long as at least one reference exists.

Parameters

error

Used to indicate error if NULL is returned

 

Returns

a reference to a proxy for signals and method calls on the bus daemon, or NULL.

[transfer full]

Since 0.7.26


tp_dbus_daemon_new ()

TpDBusDaemon *
tp_dbus_daemon_new (DBusGConnection *connection);

Returns a proxy for signals and method calls on a particular bus connection.

Use tp_dbus_daemon_dup() instead if you just want a connection to the starter or session bus (which is almost always the right thing for Telepathy).

Parameters

connection

a connection to D-Bus

 

Returns

a new proxy for signals and method calls on the bus daemon to which connection is connected

Since 0.7.1


tp_dbus_daemon_get_unique_name ()

const gchar *
tp_dbus_daemon_get_unique_name (TpDBusDaemon *self);

Parameters

self

object representing a connection to a bus

 

Returns

the unique name of this connection to the bus, which is valid for as long as this TpDBusDaemon is

Since 0.7.35


TpDBusDaemonNameOwnerChangedCb ()

void
(*TpDBusDaemonNameOwnerChangedCb) (TpDBusDaemon *bus_daemon,
                                   const gchar *name,
                                   const gchar *new_owner,
                                   gpointer user_data);

The signature of the callback called by tp_dbus_daemon_watch_name_owner().

Parameters

bus_daemon

The D-Bus daemon

 

name

The name whose ownership has changed or been discovered

 

new_owner

The unique name that now owns name

 

user_data

Arbitrary user-supplied data as passed to tp_dbus_daemon_watch_name_owner()

 

Since 0.7.1


tp_dbus_daemon_watch_name_owner ()

void
tp_dbus_daemon_watch_name_owner (TpDBusDaemon *self,
                                 const gchar *name,
                                 TpDBusDaemonNameOwnerChangedCb callback,
                                 gpointer user_data,
                                 GDestroyNotify destroy);

Arrange for callback to be called with the owner of name as soon as possible (which might even be before this function returns!), then again every time the ownership of name changes.

If multiple watches are registered for the same name , they will be called in the order they were registered.

Parameters

self

The D-Bus daemon

 

name

The name whose ownership is to be watched

 

callback

Callback to call when the ownership is discovered or changes

 

user_data

Arbitrary data to pass to callback

 

destroy

Called to destroy user_data when the name owner watch is cancelled due to tp_dbus_daemon_cancel_name_owner_watch()

 

Since 0.7.1


tp_dbus_daemon_cancel_name_owner_watch ()

gboolean
tp_dbus_daemon_cancel_name_owner_watch
                               (TpDBusDaemon *self,
                                const gchar *name,
                                TpDBusDaemonNameOwnerChangedCb callback,
                                gconstpointer user_data);

If there was a previous call to tp_dbus_daemon_watch_name_owner() with exactly the given name , callback and user_data , remove it.

If more than one watch matching the details provided was active, remove only the most recently added one.

Parameters

self

the D-Bus daemon

 

name

the name that was being watched

 

callback

the callback that was called

 

user_data

the user data that was provided

 

Returns

TRUE if there was such a watch, FALSE otherwise

Since 0.7.1


TpDBusDaemonListNamesCb ()

void
(*TpDBusDaemonListNamesCb) (TpDBusDaemon *bus_daemon,
                            const gchar * const *names,
                            const GError *error,
                            gpointer user_data,
                            GObject *weak_object);

Signature of a callback for functions that list bus names.

Parameters

bus_daemon

object representing a connection to a bus

 

names

constant NULL-terminated array of constant strings representing bus names, or NULL on error

 

error

the error that occurred, or NULL on success

 

user_data

the same user data that was passed to tp_dbus_daemon_list_names or tp_dbus_daemon_list_activatable_names

 

weak_object

the same object that was passed to tp_dbus_daemon_list_names or tp_dbus_daemon_list_activatable_names

 

Since 0.7.35


tp_dbus_daemon_list_names ()

void
tp_dbus_daemon_list_names (TpDBusDaemon *self,
                           gint timeout_ms,
                           TpDBusDaemonListNamesCb callback,
                           gpointer user_data,
                           GDestroyNotify destroy,
                           GObject *weak_object);

Call the ListNames method on the bus daemon, asynchronously. The callback will be called from the main loop with a list of all the names (either unique or well-known) that exist on the bus.

In versions of telepathy-glib that have it, this should be preferred instead of calling tp_cli_dbus_daemon_call_list_names(), since that function will result in wakeups for every NameOwnerChanged signal.

Parameters

self

object representing a connection to a bus

 

timeout_ms

timeout for the call

 

callback

callback to be called on success or failure; must not be NULL

 

user_data

opaque user-supplied data to pass to the callback

 

destroy

if not NULL, called with user_data as argument after the call has succeeded or failed, or after weak_object has been destroyed

 

weak_object

if not NULL, a GObject which will be weakly referenced; if it is destroyed, callback will not be called at all

 

Since 0.7.35


tp_dbus_daemon_list_activatable_names ()

void
tp_dbus_daemon_list_activatable_names (TpDBusDaemon *self,
                                       gint timeout_ms,
                                       TpDBusDaemonListNamesCb callback,
                                       gpointer user_data,
                                       GDestroyNotify destroy,
                                       GObject *weak_object);

Call the ListActivatableNames method on the bus daemon, asynchronously. The callback will be called from the main loop with a list of all the well-known names that are available for service-activation on the bus.

In versions of telepathy-glib that have it, this should be preferred instead of calling tp_cli_dbus_daemon_call_list_activatable_names(), since that function will result in wakeups for every NameOwnerChanged signal.

Parameters

self

object representing a connection to a bus daemon

 

timeout_ms

timeout for the call

 

callback

callback to be called on success or failure; must not be NULL

 

user_data

opaque user-supplied data to pass to the callback

 

destroy

if not NULL, called with user_data as argument after the call has succeeded or failed, or after weak_object has been destroyed

 

weak_object

if not NULL, a GObject which will be weakly referenced; if it is destroyed, callback will not be called at all

 

Since 0.7.35


tp_dbus_daemon_release_name ()

gboolean
tp_dbus_daemon_release_name (TpDBusDaemon *self,
                             const gchar *well_known_name,
                             GError **error);

Release the given well-known name. This makes a synchronous call to the bus daemon.

Parameters

self

a TpDBusDaemon

 

well_known_name

a well-known name owned by this process to release

 

error

used to raise an error if FALSE is returned

 

Returns

TRUE if well_known_name was released, or FALSE and sets error if an error occurred.

Since 0.7.30


tp_dbus_daemon_request_name ()

gboolean
tp_dbus_daemon_request_name (TpDBusDaemon *self,
                             const gchar *well_known_name,
                             gboolean idempotent,
                             GError **error);

Claim the given well-known name without queueing, allowing replacement or replacing an existing name-owner. This makes a synchronous call to the bus daemon.

Parameters

self

a TpDBusDaemon

 

well_known_name

a well-known name to acquire

 

idempotent

whether to consider it to be a success if this process already owns the name

 

error

used to raise an error if FALSE is returned

 

Returns

TRUE if well_known_name was claimed, or FALSE and sets error if an error occurred.

Since 0.7.30


tp_dbus_daemon_register_object ()

void
tp_dbus_daemon_register_object (TpDBusDaemon *self,
                                const gchar *object_path,
                                gpointer object);

Export object at object_path . This is a convenience wrapper around dbus_g_connection_register_g_object(), and behaves similarly.

Parameters

self

object representing a connection to a bus

 

object_path

an object path

 

object

an object to export.

[type GObject.Object][transfer none]

Since 0.11.3


tp_dbus_daemon_unregister_object ()

void
tp_dbus_daemon_unregister_object (TpDBusDaemon *self,
                                  gpointer object);

Stop exporting object on D-Bus. This is a convenience wrapper around dbus_g_connection_unregister_g_object(), and behaves similarly.

Parameters

self

object representing a connection to a bus

 

object

an object previously exported with tp_dbus_daemon_register_object().

[type GObject.Object][transfer none]

Since 0.11.3


tp_dbus_daemon_init_known_interfaces ()

void
tp_dbus_daemon_init_known_interfaces (void);

Ensure that the known interfaces for TpDBusDaemon have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument TP_TYPE_DBUS_DAEMON.

Since 0.7.32

Types and Values

enum TpDBusNameType

A set of flags indicating which D-Bus bus names are acceptable. They can be combined with the bitwise-or operator to accept multiple types. TP_DBUS_NAME_TYPE_NOT_BUS_DAEMON and TP_DBUS_NAME_TYPE_ANY are the bitwise-or of other appropriate types, for convenience.

Since 0.11.5, there is a corresponding GFlagsClass type, TP_TYPE_DBUS_NAME_TYPE.

Members

TP_DBUS_NAME_TYPE_UNIQUE

accept unique names like :1.123 (not including the name of the bus daemon itself)

 

TP_DBUS_NAME_TYPE_WELL_KNOWN

accept well-known names like com.example.Service (not including the name of the bus daemon itself)

 

TP_DBUS_NAME_TYPE_BUS_DAEMON

accept the name of the bus daemon itself, which has the syntax of a well-known name, but behaves like a unique name

 

TP_DBUS_NAME_TYPE_NOT_BUS_DAEMON

accept either unique or well-known names, but not the bus daemon

 

TP_DBUS_NAME_TYPE_ANY

accept any of the above

 

Since 0.7.1


TpDBusDaemon

typedef struct _TpDBusDaemon TpDBusDaemon;

A subclass of TpProxy that represents the D-Bus daemon. It mainly provides functionality to manage well-known names on the bus.

Since 0.7.1


TpDBusDaemonClass

typedef struct _TpDBusDaemonClass TpDBusDaemonClass;

The class of TpDBusDaemon.

Since 0.7.1