Top |
void | (*TpProxyPrepareAsync) () |
const TpProxyFeature * | (*TpProxyClassFeatureListFunc) () |
gboolean | tp_proxy_has_interface () |
gboolean | tp_proxy_has_interface_by_id () |
gboolean | tp_proxy_is_prepared () |
void | tp_proxy_prepare_async () |
gboolean | tp_proxy_prepare_finish () |
void | tp_proxy_pending_call_cancel () |
void | tp_proxy_signal_connection_disconnect () |
TpSimpleClientFactory * | tp_proxy_get_factory () |
TpDBusDaemon * | tp_proxy_get_dbus_daemon () |
DBusGConnection * | tp_proxy_get_dbus_connection () |
const gchar * | tp_proxy_get_bus_name () |
const gchar * | tp_proxy_get_object_path () |
const GError * | tp_proxy_get_invalidated () |
void | tp_proxy_dbus_error_to_gerror () |
gchar * | bus-name | Read / Write / Construct Only |
DBusGConnection * | dbus-connection | Read / Write / Construct Only |
TpDBusDaemon * | dbus-daemon | Read / Write / Construct Only |
TpSimpleClientFactory * | factory | Read / Write / Construct Only |
GStrv | interfaces | Read |
gchar * | object-path | Read / Write / Construct Only |
struct | TpProxy |
struct | TpProxyFeature |
struct | TpProxyClass |
TpProxyPendingCall | |
TpProxySignalConnection | |
#define | TP_DBUS_ERRORS |
enum | TpDBusError |
#define | NUM_TP_DBUS_ERRORS |
#define | TP_NUM_DBUS_ERRORS |
#define | TP_TYPE_DBUS_ERROR |
GEnum ╰── TpDBusError GObject ╰── TpProxy ├── TpAccount ├── TpAccountManager ├── TpChannel ├── TpCallContent ├── TpCallStream ├── TpChannelDispatchOperation ├── TpChannelDispatcher ├── TpChannelRequest ├── TpClient ├── TpConnection ├── TpConnectionManager ├── TpDBusDaemon ├── TpDebugClient ├── TpMediaSessionHandler ├── TpMediaStreamHandler ├── TpProtocol ╰── TpTLSCertificate
TpProxy is a base class for Telepathy client-side proxies, which represent an object accessed via D-Bus and provide access to its methods and signals.
void (*TpProxyPrepareAsync) (TpProxy *proxy
,const TpProxyFeature *feature
,GAsyncReadyCallback callback
,gpointer user_data
);
Function called when feature
has to be prepared for proxy
.
const TpProxyFeature *
(*TpProxyClassFeatureListFunc) (TpProxyClass *cls
);
A function called to list the features supported by
tp_proxy_prepare_async()
. Currently, only code inside telepathy-glib can
implement this.
Since: 0.11.3
gboolean tp_proxy_has_interface (gpointer self
,const gchar *iface
);
Return whether this proxy is known to have a particular interface. In
versions older than 0.11.11, this was a macro wrapper around
tp_proxy_has_interface_by_id()
.
For objects that discover their interfaces at runtime, this method will
indicate that interfaces are missing until they are known to be present.
In subclasses that define features for use with tp_proxy_prepare_async()
,
successfully preparing the "core" feature for that subclass (such as
TP_CHANNEL_FEATURE_CORE
or TP_CONNECTION_FEATURE_CORE
) implies that the
interfaces are known.
Since: 0.7.1
gboolean tp_proxy_has_interface_by_id (gpointer self
,GQuark iface
);
Return whether this proxy is known to have a particular interface, by its
quark ID. This is equivalent to using g_quark_to_string()
followed by
tp_proxy_has_interface()
, but more efficient.
Since: 0.7.1
gboolean tp_proxy_is_prepared (gpointer self
,GQuark feature
);
Return TRUE
if feature
has been prepared successfully, or FALSE
if
feature
has not been requested, has not been prepared yet, or is not
available on this object at all.
(For instance, if feature
is TP_CHANNEL_FEATURE_CHAT_STATES
and self
is a TpChannel in a protocol that doesn't actually implement chat states,
or is not a TpChannel at all, then this method will return FALSE
.)
To prepare features, call tp_proxy_prepare_async()
.
self |
an instance of a TpProxy subclass |
|
feature |
a feature that is supported by |
Since: 0.11.3
void tp_proxy_prepare_async (gpointer self
,const GQuark *features
,GAsyncReadyCallback callback
,gpointer user_data
);
TpProxy itself does not support any features, but subclasses like
TpChannel can support features, which can either be core functionality like
TP_CHANNEL_FEATURE_CORE
, or extended functionality like
TP_CHANNEL_FEATURE_CHAT_STATES
.
Proxy instances start with no features prepared. When features are
requested via tp_proxy_prepare_async()
, the proxy starts to do the
necessary setup to use those features.
tp_proxy_prepare_async() always waits for core functionality of the proxy's
class to be prepared, even if it is not specifically requested: for
instance, because TP_CHANNEL_FEATURE_CORE
is core functionality of a
TpChannel,
1 2 3 |
TpChannel *channel = ...; tp_proxy_prepare_async (channel, NULL, callback, user_data); |
is equivalent to
1 2 3 4 |
TpChannel *channel = ...; GQuark features[] = { TP_CHANNEL_FEATURE_CORE, 0 }; tp_proxy_prepare_async (channel, features, callback, user_data); |
If a feature represents core functionality (like TP_CHANNEL_FEATURE_CORE
),
failure to prepare it will result in tp_proxy_prepare_async()
finishing
unsuccessfully: if failure to prepare the feature indicates that the proxy
is no longer useful, it will also emit “invalidated”.
If a feature represents non-essential functionality
(like TP_CHANNEL_FEATURE_CHAT_STATES
), or is not supported by the object
at all, then failure to prepare it is not fatal:
tp_proxy_prepare_async()
will complete successfully, but
tp_proxy_is_prepared()
will still return FALSE
for the feature, and
accessor methods for the feature will typically return a dummy value.
Some TpProxy subclasses automatically start to prepare their core
features when instantiated, and features will sometimes become prepared as
a side-effect of other actions, but to ensure that a feature is present you
must generally call tp_proxy_prepare_async()
and wait for the result.
self |
an instance of a TpProxy subclass |
|
features |
an array
of desired features, ending with 0; |
[transfer none][array zero-terminated=1][allow-none] |
callback |
if not |
|
user_data |
user data for |
Since: 0.11.3
gboolean tp_proxy_prepare_finish (gpointer self
,GAsyncResult *result
,GError **error
);
Check for error in a call to tp_proxy_prepare_async()
. An error here
generally indicates that either the asynchronous call was cancelled,
or self
has emitted “invalidated”.
self |
an instance of a TpProxy subclass |
|
result |
the result passed to the callback of |
|
error |
used to return an error if |
Since: 0.11.3
void
tp_proxy_pending_call_cancel (TpProxyPendingCall *pc
);
Cancel the given pending call. After this function returns, you must not assume that the pending call remains valid, but you must not explicitly free it either.
Since: 0.7.1
void
tp_proxy_signal_connection_disconnect (TpProxySignalConnection *sc
);
Disconnect the given signal connection. After this function returns, you must not assume that the signal connection remains valid, but you must not explicitly free it either.
It is not safe to call this function if sc
has been disconnected already,
which happens in each of these situations:
weak_object
used when sc
was created has been
destroyedSince: 0.7.1
TpDBusDaemon *
tp_proxy_get_dbus_daemon (gpointer self
);
a borrowed reference to the TpDBusDaemon for
this object, if any; always NULL
if this object is itself a
TpDBusDaemon. The caller must reference the returned object with
g_object_ref()
if it will be kept.
[transfer none]
Since: 0.7.17
DBusGConnection *
tp_proxy_get_dbus_connection (gpointer self
);
[skip]
a borrowed reference to the D-Bus connection used by this object.
The caller must reference the returned pointer with
dbus_g_connection_ref()
if it will be kept.
Since: 0.7.17
const gchar *
tp_proxy_get_bus_name (gpointer self
);
the bus name of the application exporting the object. The caller
must copy the string with g_strdup()
if it will be kept.
Since: 0.7.17
const gchar *
tp_proxy_get_object_path (gpointer self
);
the object path of the remote object. The caller must copy the
string with g_strdup()
if it will be kept.
Since: 0.7.17
const GError *
tp_proxy_get_invalidated (gpointer self
);
the reason this proxy was invalidated, or NULL
if has not been
invalidated. The caller must copy the error, for instance with
g_error_copy()
, if it will be kept.
Since: 0.7.17
void tp_proxy_dbus_error_to_gerror (gpointer self
,const char *dbus_error
,const char *debug_message
,GError **error
);
Convert a D-Bus error name into a GError as if it was returned by a method on this proxy. This method is useful when D-Bus error names are emitted in signals, such as Connection.ConnectionError and Group.MembersChangedDetailed.
self |
a TpProxy or subclass |
|
dbus_error |
a D-Bus error name, for instance from the callback for
|
|
debug_message |
a debug message that accompanied the error name, or |
|
error |
used to return the corresponding GError |
Since: 0.7.24
struct TpProxyFeature { GQuark name; gboolean core; TpProxyPrepareAsync prepare_async; TpProxyPrepareAsync prepare_before_signalling_connected_async; const GQuark *interfaces_needed; /* Features we depend on */ const GQuark *depends_on; gboolean can_retry; };
Structure representing a feature.
a GQuark representing the name of the feature |
||
if |
||
TpProxyPrepareAsync |
called when the feature has to be prepared |
|
TpProxyPrepareAsync |
only relevant for
TpConnection sub-classes; same as |
|
an array of GQuark representing interfaces which have to be implemented on the object in order to be able to prepare the feature |
||
an array of GQuark representing other features which have to be prepared before trying to prepare this feature |
||
If |
Since: 0.11.3
struct TpProxyClass { GObjectClass parent_class; GQuark interface; unsigned int must_have_unique_name:1; };
The class of a TpProxy. The struct fields not documented here are reserved.
Since: 0.7.1
typedef struct _TpProxyPendingCall TpProxyPendingCall;
Opaque structure representing a pending D-Bus call.
Since: 0.7.1
typedef struct _TpProxySignalConnection TpProxySignalConnection;
Opaque structure representing a D-Bus signal connection.
Since: 0.7.1
#define TP_DBUS_ERRORS (tp_dbus_errors_quark ())
GError domain representing D-Bus errors not directly related to
Telepathy, for use by TpProxy. The code
in a GError with this
domain must be a member of TpDBusError.
This macro expands to a function call returning a GQuark.
Since: 0.7.1
GError codes for use with the TP_DBUS_ERRORS
domain.
Since 0.11.5, there is a corresponding GEnumClass type,
TP_TYPE_DBUS_ERROR
.
Raised if the error raised by a remote D-Bus object is not recognised |
||
Emitted in “invalidated” when the TpProxy has lost its last reference |
||
Raised by TpProxy methods if the remote object does not appear to have the required interface |
||
Emitted in “invalidated” if the remote process loses ownership of its bus name, and raised by any TpProxy methods that have not had a reply at that time or are called after the proxy becomes invalid in this way (usually meaning it crashed) |
||
Raised if a D-Bus bus name given is not valid, or is of an unacceptable type (e.g. well-known vs. unique) |
||
Raised if a D-Bus interface or error name given is not valid |
||
Raised if a D-Bus object path given is not valid |
||
Raised if a D-Bus method or signal name given is not valid |
||
A generic error which can be used with “invalidated” to indicate an application-specific indication that the remote object no longer exists, if no more specific error is available. |
||
Raised from calls that re-enter the main loop (*_run_*) if they are cancelled |
||
Raised if information received from a remote
object is inconsistent or otherwise obviously wrong (added in 0.7.17).
See also |
Since: 0.7.1
#define NUM_TP_DBUS_ERRORS TP_NUM_DBUS_ERRORS
1 more than the highest valid TpDBusError at the time of compilation.
In new code, use TP_NUM_DBUS_ERRORS
instead.
Since: 0.7.1
#define TP_NUM_DBUS_ERRORS (TP_DBUS_ERROR_INCONSISTENT + 1)
1 more than the highest valid TpDBusError at the time of compilation
Since: 0.19.0
#define TP_TYPE_DBUS_ERROR (tp_dbus_error_get_type ())
The GEnumClass type of a TpDBusError.
Since: 0.11.5
“bus-name”
property “bus-name” gchar *
The D-Bus bus name for this object. Read-only except during construction.
Owner: TpProxy
Flags: Read / Write / Construct Only
Default value: NULL
“dbus-connection”
property“dbus-connection” DBusGConnection *
The D-Bus connection for this object. Read-only except during construction.
[skip]
Owner: TpProxy
Flags: Read / Write / Construct Only
“dbus-daemon”
property“dbus-daemon” TpDBusDaemon *
The D-Bus daemon for this object (this object itself, if it is a TpDBusDaemon). Read-only except during construction.
Owner: TpProxy
Flags: Read / Write / Construct Only
“factory”
property“factory” TpSimpleClientFactory *
The TpSimpleClientFactory used to create this proxy,
or NULL
if this proxy was not created through a factory.
Owner: TpProxy
Flags: Read / Write / Construct Only
“interfaces”
property “interfaces” GStrv
Known D-Bus interface names for this object.
Owner: TpProxy
Flags: Read
“interface-added”
signalvoid user_function (TpProxy *self, guint id, DBusGProxy *proxy, gpointer user_data)
Emitted when this proxy has gained an interface. It is not guaranteed
to be emitted immediately, but will be emitted before the interface is
first used (at the latest: before it's returned from
tp_proxy_get_interface_by_id()
, any signal is connected, or any
method is called).
The intended use is to call dbus_g_proxy_add_signals()
. This signal
should only be used by TpProy implementations
[skip]
self |
the proxy object |
|
id |
the GQuark representing the interface |
|
proxy |
the dbus-glib proxy representing the interface |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details
“invalidated”
signalvoid user_function (TpProxy *self, guint domain, gint code, gchar *message, gpointer user_data)
Emitted when this proxy has been become invalid for whatever reason. Any more specific signal should be emitted first.
An invalidated proxy is one which can make no more method calls and will emit no more D-Bus signals. This is typically because the D-Bus object represented by the proxy ceased to exist, or there was some error obtaining the initial state.
Any pending or future method calls made on this proxy will fail gracefully
with the same error as returned by tp_proxy_get_invalidated()
.
self |
the proxy object |
|
domain |
domain of a GError indicating why this proxy was invalidated |
|
code |
error code of a GError indicating why this proxy was invalidated |
|
message |
a message associated with the error |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details