![]() |
![]() |
![]() |
telepathy-glib API Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <telepathy-glib/telepathy-glib.h> void tp_dbus_g_method_return_not_implemented (DBusGMethodInvocation *context
); enum TpDBusNameType; #define TP_TYPE_DBUS_NAME_TYPE gboolean tp_dbus_check_valid_bus_name (const gchar *name
,TpDBusNameType allow_types
,GError **error
); gboolean tp_dbus_check_valid_interface_name (const gchar *name
,GError **error
); gboolean tp_dbus_check_valid_member_name (const gchar *name
,GError **error
); gboolean tp_dbus_check_valid_object_path (const gchar *path
,GError **error
); GValue * tp_g_value_slice_new_bytes (guint length
,gconstpointer bytes
); GValue * tp_g_value_slice_new_take_bytes (GArray *bytes
); GValue * tp_g_value_slice_new_object_path (const gchar *path
); GValue * tp_g_value_slice_new_static_object_path (const gchar *path
); GValue * tp_g_value_slice_new_take_object_path (gchar *path
); TpDBusDaemon; TpDBusDaemonClass; TpDBusDaemon * tp_dbus_daemon_dup (GError **error
); TpDBusDaemon * tp_dbus_daemon_new (DBusGConnection *connection
); const gchar * tp_dbus_daemon_get_unique_name (TpDBusDaemon *self
); void (*TpDBusDaemonNameOwnerChangedCb) (TpDBusDaemon *bus_daemon
,const gchar *name
,const gchar *new_owner
,gpointer user_data
); void tp_dbus_daemon_watch_name_owner (TpDBusDaemon *self
,const gchar *name
,TpDBusDaemonNameOwnerChangedCb callback
,gpointer user_data
,GDestroyNotify destroy
); gboolean tp_dbus_daemon_cancel_name_owner_watch (TpDBusDaemon *self
,const gchar *name
,TpDBusDaemonNameOwnerChangedCb callback
,gconstpointer user_data
); void (*TpDBusDaemonListNamesCb) (TpDBusDaemon *bus_daemon
,const gchar * const *names
,const GError *error
,gpointer user_data
,GObject *weak_object
); void tp_dbus_daemon_list_names (TpDBusDaemon *self
,gint timeout_ms
,TpDBusDaemonListNamesCb callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
); void tp_dbus_daemon_list_activatable_names (TpDBusDaemon *self
,gint timeout_ms
,TpDBusDaemonListNamesCb callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
); gboolean tp_dbus_daemon_release_name (TpDBusDaemon *self
,const gchar *well_known_name
,GError **error
); gboolean tp_dbus_daemon_request_name (TpDBusDaemon *self
,const gchar *well_known_name
,gboolean idempotent
,GError **error
); void tp_dbus_daemon_register_object (TpDBusDaemon *self
,const gchar *object_path
,gpointer object
); void tp_dbus_daemon_unregister_object (TpDBusDaemon *self
,gpointer object
); void tp_dbus_daemon_init_known_interfaces (void
);
void tp_dbus_g_method_return_not_implemented
(DBusGMethodInvocation *context
);
Return the Telepathy error NotImplemented from the method invocation
given by context
.
|
The D-Bus method invocation context |
typedef enum { TP_DBUS_NAME_TYPE_UNIQUE = 1, TP_DBUS_NAME_TYPE_WELL_KNOWN = 2, TP_DBUS_NAME_TYPE_BUS_DAEMON = 4, TP_DBUS_NAME_TYPE_NOT_BUS_DAEMON = TP_DBUS_NAME_TYPE_UNIQUE | TP_DBUS_NAME_TYPE_WELL_KNOWN, TP_DBUS_NAME_TYPE_ANY = TP_DBUS_NAME_TYPE_NOT_BUS_DAEMON | TP_DBUS_NAME_TYPE_BUS_DAEMON } 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
.
accept unique names like :1.123 (not including the name of the bus daemon itself) | |
accept well-known names like com.example.Service (not including the name of the bus daemon itself) | |
accept the name of the bus daemon itself, which has the syntax of a well-known name, but behaves like a unique name | |
accept either unique or well-known names, but not the bus daemon | |
accept any of the above |
Since 0.7.1
#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
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.
|
a possible bus name |
|
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 ) |
|
used to raise TP_DBUS_ERROR_INVALID_BUS_NAME if FALSE is returned |
Returns : |
TRUE if name is valid |
Since 0.7.1
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.
|
a possible interface name |
|
used to raise TP_DBUS_ERROR_INVALID_INTERFACE_NAME if FALSE is
returned |
Returns : |
TRUE if name is valid |
Since 0.7.1
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.
|
a possible member name |
|
used to raise TP_DBUS_ERROR_INVALID_MEMBER_NAME if FALSE is
returned |
Returns : |
TRUE if name is valid |
Since 0.7.1
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.
|
a possible object path |
|
used to raise TP_DBUS_ERROR_INVALID_OBJECT_PATH if FALSE is
returned |
Returns : |
TRUE if path is valid |
Since 0.7.1
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.
|
number of bytes to copy |
|
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
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.
|
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
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.
|
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
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.
|
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
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.
|
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
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
typedef struct _TpDBusDaemonClass TpDBusDaemonClass;
The class of TpDBusDaemon.
Since 0.7.1
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.
|
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
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).
|
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
const gchar * tp_dbus_daemon_get_unique_name (TpDBusDaemon *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
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()
.
|
The D-Bus daemon |
|
The name whose ownership has changed or been discovered |
|
The unique name that now owns name
|
|
Arbitrary user-supplied data as passed to
tp_dbus_daemon_watch_name_owner()
|
Since 0.7.1
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.
|
The D-Bus daemon |
|
The name whose ownership is to be watched |
|
Callback to call when the ownership is discovered or changes |
|
Arbitrary data to pass to callback
|
|
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
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.
|
the D-Bus daemon |
|
the name that was being watched |
|
the callback that was called |
|
the user data that was provided |
Returns : |
TRUE if there was such a watch, FALSE otherwise |
Since 0.7.1
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.
|
object representing a connection to a bus |
|
constant NULL -terminated array of constant strings representing
bus names, or NULL on error |
|
the error that occurred, or NULL on success |
|
the same user data that was passed to tp_dbus_daemon_list_names or tp_dbus_daemon_list_activatable_names |
|
the same object that was passed to tp_dbus_daemon_list_names or tp_dbus_daemon_list_activatable_names |
Since 0.7.35
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.
|
object representing a connection to a bus |
|
timeout for the call |
|
callback to be called on success or failure; must not be NULL
|
|
opaque user-supplied data to pass to the callback |
|
if not NULL , called with user_data as argument after the call
has succeeded or failed, or after weak_object has been destroyed |
|
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
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.
|
object representing a connection to a bus daemon |
|
timeout for the call |
|
callback to be called on success or failure; must not be NULL
|
|
opaque user-supplied data to pass to the callback |
|
if not NULL , called with user_data as argument after the call
has succeeded or failed, or after weak_object has been destroyed |
|
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
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.
|
a TpDBusDaemon |
|
a well-known name owned by this process to release |
|
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
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.
|
a TpDBusDaemon |
|
a well-known name to acquire |
|
whether to consider it to be a success if this process already owns the name |
|
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
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.
|
object representing a connection to a bus |
|
an object path |
|
an object to export. [type GObject.Object][transfer none] |
Since 0.11.3
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.
|
object representing a connection to a bus |
|
an object previously exported
with tp_dbus_daemon_register_object() . [type GObject.Object][transfer none]
|
Since 0.11.3
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