D-Bus utilities

D-Bus utilities — some D-Bus utility functions

Functions

Types and Values

Object Hierarchy

    GFlags
    ╰── TpDBusNameType

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
                               (GDBusMethodInvocation *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_dbus_connection_release_name ()

gboolean
tp_dbus_connection_release_name (GDBusConnection *dbus_connection,
                                 const gchar *well_known_name,
                                 GError **error);

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

Parameters

dbus_connection

a GDBusConnection

 

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_connection_request_name ()

gboolean
tp_dbus_connection_request_name (GDBusConnection *dbus_connection,
                                 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

dbus_connection

a GDBusConnection

 

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_connection_register_object ()

void
tp_dbus_connection_register_object (GDBusConnection *dbus_connection,
                                    const gchar *object_path,
                                    gpointer object);

Export object at object_path :

It is considered to be a programming error to register an object at a path where another object already exists.

Since 0.99.10, as a simplification, exporting an object in this way at more than one location or on more than one bus is not allowed, and is also considered to be a programming error. However, redundantly re-exporting the same object at the same path on the same bus is allowed.

Also since 0.99.10, this function must be called *before* taking any bus name whose presence is meant to correspond to the existence of this object. It is *not* sufficient to take the bus name within the same main-loop iteration as registering the object (even though that was sufficient under dbus-glib), because GDBus dispatches method calls in a separate thread.

Parameters

dbus_connection

a GDBusConnection

 

object_path

an object path

 

object

an object to export.

[type GObject.Object][transfer none]

tp_dbus_connection_try_register_object ()

gboolean
tp_dbus_connection_try_register_object
                               (GDBusConnection *dbus_connection,
                                const gchar *object_path,
                                gpointer object,
                                GError **error);

The same as tp_dbus_connection_register_object(), except that it is not considered to be a programming error to register an object at a path where another object exists.

Parameters

dbus_connection

a GDBusConnection

 

object_path

an object path

 

object

an object to export.

[type GObject.Object][transfer none]

error

used to raise G_IO_ERROR_EXISTS if an object exists at that path

 

Returns

TRUE if the object is successfully registered


tp_dbus_connection_unregister_object ()

void
tp_dbus_connection_unregister_object (GDBusConnection *dbus_connection,
                                      gpointer object);

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

Parameters

dbus_connection

a GDBusConnection

 

object

an object previously exported with tp_dbus_connection_register_object().

[type GObject.Object][transfer none]

Since 0.11.3

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