telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
TpBaseConnectionTpBaseConnection — base class for TpSvcConnection implementations |
Synopsis
#include <telepathy-glib/telepathy-glib.h> #define TP_INTERNAL_CONNECTION_STATUS_NEW TpBaseConnection; struct TpBaseConnectionClass; GPtrArray * (*TpBaseConnectionCreateChannelFactoriesImpl) (TpBaseConnection *self
); GPtrArray * (*TpBaseConnectionCreateChannelManagersImpl) (TpBaseConnection *self
); void (*TpBaseConnectionCreateHandleReposImpl) (TpBaseConnection *self
,TpHandleRepoIface *repos[TP_NUM_HANDLE_TYPES]
); gchar * (*TpBaseConnectionGetUniqueConnectionNameImpl) (TpBaseConnection *self
); GPtrArray * (*TpBaseConnectionGetInterfacesImpl) (TpBaseConnection *self
); void (*TpBaseConnectionProc) (TpBaseConnection *self
); gboolean (*TpBaseConnectionStartConnectingImpl) (TpBaseConnection *self
,GError **error
); const gchar * tp_base_connection_get_bus_name (TpBaseConnection *self
); const gchar * tp_base_connection_get_object_path (TpBaseConnection *self
); TpDBusDaemon * tp_base_connection_get_dbus_daemon (TpBaseConnection *self
); gboolean tp_base_connection_register (TpBaseConnection *self
,const gchar *cm_name
,gchar **bus_name
,gchar **object_path
,GError **error
); TpHandleRepoIface * tp_base_connection_get_handles (TpBaseConnection *self
,TpHandleType handle_type
); TpHandle tp_base_connection_get_self_handle (TpBaseConnection *self
); void tp_base_connection_set_self_handle (TpBaseConnection *self
,TpHandle self_handle
); TpConnectionStatus tp_base_connection_get_status (TpBaseConnection *self
); gboolean tp_base_connection_is_destroyed (TpBaseConnection *self
); gboolean tp_base_connection_check_connected (TpBaseConnection *self
,GError **error
); void tp_base_connection_change_status (TpBaseConnection *self
,TpConnectionStatus status
,TpConnectionStatusReason reason
); void tp_base_connection_disconnect_with_dbus_error (TpBaseConnection *self
,const gchar *error_name
,GHashTable *details
,TpConnectionStatusReason reason
); void tp_base_connection_disconnect_with_dbus_error_vardict (TpBaseConnection *self
,const gchar *error_name
,GVariant *details
,TpConnectionStatusReason reason
); void tp_base_connection_finish_shutdown (TpBaseConnection *self
); void tp_base_connection_add_interfaces (TpBaseConnection *self
,const gchar **interfaces
); void tp_base_connection_dbus_request_handles (TpSvcConnection *iface
,guint handle_type
,const gchar **names
,DBusGMethodInvocation *context
); #define TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED(conn, context) void tp_base_connection_register_with_contacts_mixin (TpBaseConnection *self
); void tp_base_connection_add_possible_client_interest (TpBaseConnection *self
,GQuark token
); void tp_base_connection_add_client_interest (TpBaseConnection *self
,const gchar *unique_name
,const gchar *token
,gboolean only_if_uninterested
); const gchar * tp_base_connection_get_account_path_suffix (TpBaseConnection *self
); struct TpChannelManagerIter; void tp_base_connection_channel_manager_iter_init (TpChannelManagerIter *iter
,TpBaseConnection *self
); gboolean tp_base_connection_channel_manager_iter_next (TpChannelManagerIter *iter
,TpChannelManager **manager_out
);
Implemented Interfaces
TpBaseConnection implements TpSvcConnection, TpSvcDBusProperties and TpSvcConnectionInterfaceRequests.
Properties
"account-path-suffix" gchar* : Read / Write / Construct Only "dbus-daemon" TpDBusDaemon* : Read / Write / Construct Only "dbus-status" guint : Read "has-immortal-handles" gboolean : Read "interfaces" GStrv : Read "protocol" gchar* : Read / Write / Construct Only "self-handle" guint : Read / Write "self-id" gchar* : Read
Signals
"clients-interested" :Has Details
"clients-uninterested" :Has Details
"shutdown-finished" :Has Details
Description
This base class makes it easier to write TpSvcConnection implementations by managing connection status, channel factories and handle tracking. A subclass should often not need to implement any of the Connection methods itself.
However, methods may be reimplemented if needed: for instance, Gabble overrides RequestHandles so it can validate MUC rooms, which must be done asynchronously.
Details
TP_INTERNAL_CONNECTION_STATUS_NEW
# define TP_INTERNAL_CONNECTION_STATUS_NEW ((TpConnectionStatus)(-1))
A special value for TpConnectionStatus, used within GLib connection managers to indicate that the connection is disconnected because connection has never been attempted (as distinct from disconnected after connection has started, either by user request or an error).
Must never be visible on the D-Bus - TP_CONNECTION_STATUS_DISCONNECTED
is sent instead.
TpBaseConnection
typedef struct _TpBaseConnection TpBaseConnection;
Data structure representing a generic TpSvcConnection implementation.
Since 0.19.1, accessing the fields of this structure is deprecated.
Use tp_base_connection_get_bus_name()
, tp_base_connection_get_object_path()
,
tp_base_connection_get_status()
, tp_base_connection_get_self_handle()
instead.
struct TpBaseConnectionClass
struct TpBaseConnectionClass { GObjectClass parent_class; #ifdef __GI_SCANNER__ #else TpBaseConnectionCreateHandleReposImpl create_handle_repos; #endif TpBaseConnectionCreateChannelFactoriesImpl create_channel_factories; TpBaseConnectionGetUniqueConnectionNameImpl get_unique_connection_name; TpBaseConnectionProc connecting; TpBaseConnectionProc connected; TpBaseConnectionProc disconnected; TpBaseConnectionProc shut_down; TpBaseConnectionStartConnectingImpl start_connecting; TpBaseConnectionCreateChannelManagersImpl create_channel_managers; TpBaseConnectionGetInterfacesImpl get_interfaces_always_present; };
The class of a TpBaseConnection. Many members are virtual methods etc. to be filled in in the subclass' class_init function.
GObjectClass |
The superclass' structure |
TpBaseConnectionCreateHandleReposImpl |
Fill in suitable handle repositories in the
given array for all those handle types this Connection supports.
Must be set by subclasses to a non-NULL value; the function must create
at least a CONTACT handle repository (failing to do so will cause a crash). |
TpBaseConnectionCreateChannelFactoriesImpl |
Create an array of channel factories for this
Connection. At least one of this or create_channel_managers must be set by
subclasses to a non-NULL value; in new code, setting this to NULL and
using channel managers exclusively is recommended. |
TpBaseConnectionGetUniqueConnectionNameImpl |
Construct a unique name for this connection
(for example using the protocol's format for usernames). If NULL (the
default), a unique name will be generated. Subclasses should usually
override this to get more obvious names, to aid debugging and prevent
multiple connections to the same account. |
TpBaseConnectionProc |
If set by subclasses, will be called just after the state
changes to CONNECTING. May be NULL if nothing special needs to happen. |
TpBaseConnectionProc |
If set by subclasses, will be called just after the state
changes to CONNECTED. May be NULL if nothing special needs to happen. |
TpBaseConnectionProc |
If set by subclasses, will be called just after the state
changes to DISCONNECTED. May be NULL if nothing special needs to happen. |
TpBaseConnectionProc |
Called after disconnected() is called, to clean up the
connection. Must start the shutdown process for the underlying
network connection, and arrange for tp_base_connection_finish_shutdown()
to be called after the underlying connection has been closed. May not
be left as NULL . |
TpBaseConnectionStartConnectingImpl |
Asynchronously start connecting - called to implement
the Connect D-Bus method. See TpBaseConnectionStartConnectingImpl for
details. May not be left as NULL . |
TpBaseConnectionCreateChannelManagersImpl |
Create an array of channel managers for this
Connection. At least one of this or create_channel_factories must be set
by subclasses to a non-NULL value. Since: 0.7.15 |
TpBaseConnectionGetInterfacesImpl |
Returns a GPtrArray of extra D-Bus
interfaces which are always implemented by instances of this class,
which may be filled in by subclasses. The default is to list no
additional interfaces. Individual instances may detect which
additional interfaces they support and signal them before going
to state CONNECTED by calling tp_base_connection_add_interfaces() . |
TpBaseConnectionCreateChannelFactoriesImpl ()
GPtrArray * (*TpBaseConnectionCreateChannelFactoriesImpl)
(TpBaseConnection *self
);
Signature of an implementation of the create_channel_factories method of TpBaseConnection.
|
The implementation, a subclass of TpBaseConnection |
Returns : |
a GPtrArray of objects implementing TpChannelFactoryIface which, between them, implement all channel types this Connection supports. [transfer full] |
TpBaseConnectionCreateChannelManagersImpl ()
GPtrArray * (*TpBaseConnectionCreateChannelManagersImpl)
(TpBaseConnection *self
);
Signature of an implementation of the create_channel_managers method of TpBaseConnection.
|
The implementation, a subclass of TpBaseConnection |
Returns : |
a GPtrArray of objects implementing TpChannelManager which, between them, implement all channel types this Connection supports. [transfer full] |
TpBaseConnectionCreateHandleReposImpl ()
void (*TpBaseConnectionCreateHandleReposImpl) (TpBaseConnection *self
,TpHandleRepoIface *repos[TP_NUM_HANDLE_TYPES]
);
Signature of an implementation of the create_handle_repos method of TpBaseConnection.
|
The connection object |
|
An array of pointers to be filled in; the implementation may assume all are initially NULL. |
TpBaseConnectionGetUniqueConnectionNameImpl ()
gchar * (*TpBaseConnectionGetUniqueConnectionNameImpl)
(TpBaseConnection *self
);
Signature of the get_unique_connection_name
virtual method
on TpBaseConnection.
|
The implementation, a subclass of TpBaseConnection |
Returns : |
a name for this connection which will be unique within this connection manager process, as a string which the caller must free with g_free. [transfer full] |
TpBaseConnectionGetInterfacesImpl ()
GPtrArray * (*TpBaseConnectionGetInterfacesImpl)
(TpBaseConnection *self
);
Signature of an implementation of TpBaseConnectionClass.get_interfaces_always_present virtual function.
Implementation must first chainup on parent class implementation and then add extra interfaces into the GPtrArray.
1 2 3 4 5 6 7 8 9 10 11 12 |
static GPtrArray * my_connection_get_interfaces_always_present (TpBaseConnection *self) { GPtrArray *interfaces; interfaces = TP_BASE_CONNECTION_CLASS ( my_connection_parent_class)->get_interfaces_always_present (self); g_ptr_array_add (interfaces, TP_IFACE_BADGERS); return interfaces; } |
|
a TpBaseConnection |
Returns : |
a GPtrArray of static strings for D-Bus interfaces implemented by this client. [transfer container] |
Since 0.19.4
TpBaseConnectionProc ()
void (*TpBaseConnectionProc) (TpBaseConnection *self
);
Signature of a virtual method on TpBaseConnection that takes no additional parameters and returns nothing.
|
The connection object |
TpBaseConnectionStartConnectingImpl ()
gboolean (*TpBaseConnectionStartConnectingImpl) (TpBaseConnection *self
,GError **error
);
Signature of an implementation of the start_connecting method of TpBaseConnection.
On entry, the implementation may assume that it is in state NEW.
If TRUE
is returned, the Connect D-Bus method succeeds; the
implementation must either have already set the status to CONNECTED by
calling tp_base_connection_change_status()
, or have arranged for a
status change to either state DISCONNECTED or CONNECTED to be signalled by
calling tp_base_connection_change_status()
at some later time.
If the status is still NEW after returning TRUE
, TpBaseConnection will
automatically change it to CONNECTING for reason REQUESTED.
If FALSE
is returned, the error will be raised from Connect as an
exception. If the status is not DISCONNECTED after FALSE
is returned,
TpBaseConnection will automatically change it to DISCONNECTED
with a reason appropriate to the error; NetworkError results in
NETWORK_ERROR, PermissionDenied results in AUTHENTICATION_FAILED, and all
other errors currently result in NONE_SPECIFIED.
All except the simplest connection managers are expected to implement this
asynchronously, returning TRUE
in most cases and changing the status
to CONNECTED or DISCONNECTED later.
tp_base_connection_get_bus_name ()
const gchar * tp_base_connection_get_bus_name (TpBaseConnection *self
);
Return the bus name starting with TP_CONN_BUS_NAME_BASE
that represents
this connection on D-Bus.
The returned string belongs to the TpBaseConnection and must be copied by the caller if it will be kept.
If this connection has never been present on D-Bus
(tp_base_connection_register()
has never been called), return NULL
instead.
|
the connection |
Returns : |
the bus name of this connection,
or NULL . [allow-none][transfer none]
|
Since 0.19.1
tp_base_connection_get_object_path ()
const gchar * tp_base_connection_get_object_path (TpBaseConnection *self
);
Return the object path starting with TP_CONN_OBJECT_PATH_BASE
that
represents this connection on D-Bus.
The returned string belongs to the TpBaseConnection and must be copied by the caller if it will be kept.
If this connection has never been present on D-Bus
(tp_base_connection_register()
has never been called), return NULL
instead.
|
the connection |
Returns : |
the object path of this connection,
or NULL . [allow-none][transfer none]
|
Since 0.19.1
tp_base_connection_get_dbus_daemon ()
TpDBusDaemon * tp_base_connection_get_dbus_daemon (TpBaseConnection *self
);
|
the connection manager |
Returns : |
the value of the
"dbus-daemon" property. The caller must reference
the returned object with g_object_ref() if it will be kept. [transfer none]
|
Since 0.11.3
tp_base_connection_register ()
gboolean tp_base_connection_register (TpBaseConnection *self
,const gchar *cm_name
,gchar **bus_name
,gchar **object_path
,GError **error
);
Make the connection object appear on the bus, returning the bus
name and object path used. If TRUE
is returned, the connection owns the
bus name, and will release it when destroyed.
Since 0.11.11, bus_name
and object_path
may be NULL
if the
strings are not needed.
|
A connection |
|
The name of the connection manager in the Telepathy protocol |
|
Used to return the bus name corresponding to the connection
if TRUE is returned. To be freed by the caller. [out]
|
|
Used to return the object path of the connection if
TRUE is returned. To be freed by the caller. [out]
|
|
Used to return an error if FALSE is returned; may be NULL
|
Returns : |
TRUE on success, FALSE on error. |
tp_base_connection_get_handles ()
TpHandleRepoIface * tp_base_connection_get_handles (TpBaseConnection *self
,TpHandleType handle_type
);
|
A connection |
|
The handle type |
Returns : |
the handle repository corresponding to the given handle type, or NULL if it's unsupported or invalid. [transfer none] |
tp_base_connection_get_self_handle ()
TpHandle tp_base_connection_get_self_handle (TpBaseConnection *self
);
Returns the "self-handle" property, which is guaranteed not to be 0 once the connection has moved to the CONNECTED state.
|
A connection |
Returns : |
the current self handle of the connection. |
Since 0.7.15
tp_base_connection_set_self_handle ()
void tp_base_connection_set_self_handle (TpBaseConnection *self
,TpHandle self_handle
);
Sets the "self-handle" property. self_handle may not be 0 once the connection has moved to the CONNECTED state.
|
A connection |
|
The new self handle for the connection. |
Since 0.7.15
tp_base_connection_get_status ()
TpConnectionStatus tp_base_connection_get_status (TpBaseConnection *self
);
Return the status of this connection, as set by
tp_base_connection_change_status()
or similar functions like
tp_base_connection_disconnect_with_dbus_error()
.
Like the corresponding D-Bus property, this method returns
TP_CONNECTION_STATUS_DISCONNECTED
in two situations:
either the connection is newly-created (and has never emitted
"status-changed"), or D-Bus clients have already been
told that it has been destroyed (by the Disconnect D-Bus method,
a failed attempt to connect, or loss of an established connection).
Use tp_base_connection_is_destroyed()
to distinguish between the two.
|
the connection |
Returns : |
the value of "dbus-status" |
Since 0.19.1
tp_base_connection_is_destroyed ()
gboolean tp_base_connection_is_destroyed (TpBaseConnection *self
);
Return whether this connection has already emitted the D-Bus signal indicating that it has been destroyed.
In particular, this can be used to distinguish between the two reasons
why tp_base_connection_get_status()
would return
TP_CONNECTION_STATUS_DISCONNECTED
: it will return FALSE
if the
connection is newly-created, and TRUE
if the Disconnect D-Bus method
has been called, an attempt to connect has failed, or an established
connection has encountered an error.
|
the connection |
Returns : |
TRUE if this connection is disappearing from D-Bus |
Since 0.19.1
tp_base_connection_check_connected ()
gboolean tp_base_connection_check_connected (TpBaseConnection *self
,GError **error
);
Return whether this connection is fully active and connected.
If it is not, raise TP_ERROR_DISCONNECTED
.
This is equivalent to checking whether tp_base_connection_get_status()
returns TP_CONNECTION_STATUS_CONNECTED
; it is provided because methods
on the connection often need to make this check, and return a
GError if it fails.
|
the connection |
|
used to raise TP_ERROR_DISCONNECTED if FALSE is returned |
Returns : |
TRUE if this connection is connected |
Since 0.19.1
tp_base_connection_change_status ()
void tp_base_connection_change_status (TpBaseConnection *self
,TpConnectionStatus status
,TpConnectionStatusReason reason
);
Change the status of the connection. The allowed state transitions are:
- TP_INTERNAL_CONNECTION_STATUS_NEW → TP_CONNECTION_STATUS_CONNECTING
- TP_CONNECTION_STATUS_CONNECTING → TP_CONNECTION_STATUS_CONNECTED
- TP_INTERNAL_CONNECTION_STATUS_NEW → TP_CONNECTION_STATUS_CONNECTED (exactly equivalent to both of the above one after the other; see below)
- anything except TP_CONNECTION_STATUS_DISCONNECTED → TP_CONNECTION_STATUS_DISCONNECTED
Before the transition to TP_CONNECTION_STATUS_CONNECTED, the implementation
must have discovered the handle for the local user and passed it to
tp_base_connection_set_self_handle()
.
Changing from NEW to CONNECTED is implemented by doing the transition from NEW to CONNECTING, followed by the transition from CONNECTING to CONNECTED; it's exactly equivalent to calling tp_base_connection_change_status for those two transitions one after the other.
Any other valid transition does the following, in this order:
- Update TpBaseConnection.status;
- If the new state is TP_CONNECTION_STATUS_DISCONNECTED, call
tp_channel_factory_iface_close_all()
on all channel factories - Emit the D-Bus StatusChanged signal;
- Call TpBaseConnectionClass.connecting, TpBaseConnectionClass.connected or TpBaseConnectionClass.disconnected as appropriate;
- Call the channel factories' status change callbacks;
- If the new state is TP_CONNECTION_STATUS_DISCONNECTED, call the subclass' TpBaseConnectionClass.shut_down callback.
To provide more details about what happened when moving to status
TP_CONNECTION_STATUS_DISCONNECTED due to an error, consider calling
tp_base_connection_disconnect_with_dbus_error()
instead of this function.
Changed in 0.7.35: the self_handle
member of TpBaseConnection was
previously set to 0 at this stage. It now remains non-zero until the object
is disposed.
|
The connection |
|
The new status |
|
The reason for the status change |
tp_base_connection_disconnect_with_dbus_error ()
void tp_base_connection_disconnect_with_dbus_error (TpBaseConnection *self
,const gchar *error_name
,GHashTable *details
,TpConnectionStatusReason reason
);
Changes the TpBaseConnection.status of self
to
TP_CONNECTION_STATUS_DISCONNECTED
, as if by a call to
tp_base_connection_change_status()
, but additionally emits the
ConnectionError
D-Bus signal to provide more details about the
error.
Well-known keys for details
are documented in the Telepathy specification's
definition
of the ConnectionError signal, and include:
-
"debug-message"
, whose value should have type G_TYPE_STRING, for debugging information about the disconnection which should not be shown to the user -
"server-message"
, whose value should also have type G_TYPE_STRING, for a human-readable error message from the server (in an unspecified language) explaining why the user was disconnected.
|
The connection |
|
The D-Bus error with which the connection changed status to Disconnected |
|
Further details of the error, as a hash table where the keys
are strings as defined in the Telepathy specification, and the
values are GValues. NULL is allowed, and treated as
an empty hash table. |
|
The reason code to use in the StatusChanged signal
(a less specific, non-extensible version of error_name ) |
Since 0.7.24
tp_base_connection_disconnect_with_dbus_error_vardict ()
void tp_base_connection_disconnect_with_dbus_error_vardict (TpBaseConnection *self
,const gchar *error_name
,GVariant *details
,TpConnectionStatusReason reason
);
Changes the TpBaseConnection.status of self
to
TP_CONNECTION_STATUS_DISCONNECTED
, as if by a call to
tp_base_connection_change_status()
, but additionally emits the
ConnectionError
D-Bus signal to provide more details about the
error.
Well-known keys for details
are documented in the Telepathy specification's
definition
of the ConnectionError signal, and include:
-
"debug-message"
, whose value should have type G_TYPE_STRING, for debugging information about the disconnection which should not be shown to the user -
"server-message"
, whose value should also have type G_TYPE_STRING, for a human-readable error message from the server (in an unspecified language) explaining why the user was disconnected.
|
The connection |
|
The D-Bus error with which the connection changed status to Disconnected |
|
Further details of the error, as a variant of
type G_VARIANT_TYPE_VARDICT . The keys
are strings as defined in the Telepathy specification, and the
values are of type G_VARIANT_TYPE_VARIANT .
NULL is allowed, and treated as an empty dictionary. |
|
The reason code to use in the StatusChanged signal
(a less specific, non-extensible version of error_name ) |
Since 0.7.24
tp_base_connection_finish_shutdown ()
void tp_base_connection_finish_shutdown (TpBaseConnection *self
);
Tell the connection manager that this Connection has been disconnected, has emitted StatusChanged and is ready to be removed from D-Bus.
|
The connection |
tp_base_connection_add_interfaces ()
void tp_base_connection_add_interfaces (TpBaseConnection *self
,const gchar **interfaces
);
Add some interfaces to the list supported by this Connection. If you're
going to call this function at all, you must do so before moving to state
CONNECTED (or DISCONNECTED); if you don't call it, only the set of
interfaces always present (get_interfaces_always_present
in
TpBaseConnectionClass) will be supported.
|
A TpBaseConnection in state TP_INTERNAL_CONNECTION_STATUS_NEW or TP_CONNECTION_STATUS_CONNECTING |
|
A NULL -terminated array of D-Bus interface names, which
must remain valid at least until the connection enters state
TP_CONNECTION_STATUS_DISCONNECTED (in practice, you should either
use static strings, or use strdup'd strings and free them in the dispose
callback). |
tp_base_connection_dbus_request_handles ()
void tp_base_connection_dbus_request_handles (TpSvcConnection *iface
,guint handle_type
,const gchar **names
,DBusGMethodInvocation *context
);
Warning
tp_base_connection_dbus_request_handles
is deprecated and should not be used in newly-written code. 0.19.0
Implements D-Bus method RequestHandles on interface org.freedesktop.Telepathy.Connection.
This was exported so subclasses could use it as a basis for their reimplementations, but reimplementing the method is now deprecated.
|
A pointer to TpBaseConnection, cast to a pointer to TpSvcConnection |
|
The handle type (TpHandleType) as a guint |
|
A strv of handle names |
|
The dbus-glib method invocation context |
TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED()
#define TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED(conn, context)
If conn
is not in state TP_CONNECTION_STATUS_CONNECTED, complete the
D-Bus method invocation context
by raising the Telepathy error
TP_ERROR_DISCONNECTED, and return from the current function (which
must be void). For use in D-Bus method implementations.
|
A TpBaseConnection |
|
A DBusGMethodInvocation |
tp_base_connection_register_with_contacts_mixin ()
void tp_base_connection_register_with_contacts_mixin
(TpBaseConnection *self
);
Register the Connection interface with the Contacts interface to make it inspectable. The Contacts mixin should be initialized before this function is called
|
An instance of the TpBaseConnections that uses the Contacts mixin |
tp_base_connection_add_possible_client_interest ()
void tp_base_connection_add_possible_client_interest (TpBaseConnection *self
,GQuark token
);
Add token
to the set of tokens for which this connection will emit
"clients-interested" and
"clients-uninterested".
This method must be called from the GObjectClass.constructed or GObjectClass.constructor callback (otherwise, it will run too late to be useful).
|
a connection |
|
a quark corresponding to a D-Bus interface, or a token representing part of a D-Bus interface, for which this connection wishes to be notified when clients register an interest |
tp_base_connection_add_client_interest ()
void tp_base_connection_add_client_interest (TpBaseConnection *self
,const gchar *unique_name
,const gchar *token
,gboolean only_if_uninterested
);
Add a "client interest" for token
on behalf of the given client.
This emits "clients-interested" if this was the first time a client expressed an interest in this token.
|
a TpBaseConnection |
|
the unique bus name of a D-Bus client |
|
a D-Bus interface or a token representing part of an interface,
added with tp_base_connection_add_possible_client_interest()
|
|
only add to the interest count if the client is not already interested (appropriate for APIs that implicitly subscribe on first use if this has not been done already, like Location) |
tp_base_connection_get_account_path_suffix ()
const gchar * tp_base_connection_get_account_path_suffix
(TpBaseConnection *self
);
|
the connection |
Returns : |
the same value has the "account-path-suffix" property. |
Since 0.23.2
struct TpChannelManagerIter
struct TpChannelManagerIter { };
An iterator over the TpChannelManager objects known to a TpBaseConnection. It has no public fields.
Use tp_base_connection_channel_manager_iter_init()
to start iteration and
tp_base_connection_channel_manager_iter_next()
to continue.
Since 0.7.15
tp_base_connection_channel_manager_iter_init ()
void tp_base_connection_channel_manager_iter_init (TpChannelManagerIter *iter
,TpBaseConnection *self
);
Initializes an iterator over the TpChannelManager objects known to
self
. It is intended to be used as followed:
1 2 3 4 5 6 7 8 |
TpChannelManagerIter iter; TpChannelManager *manager; tp_base_connection_channel_manager_iter_init (&iter, base_conn); while (tp_base_connection_channel_manager_iter_next (&iter, &manager)) { ...do something with manager... } |
|
an uninitialized TpChannelManagerIter |
|
a connection |
Since 0.7.15
tp_base_connection_channel_manager_iter_next ()
gboolean tp_base_connection_channel_manager_iter_next (TpChannelManagerIter *iter
,TpChannelManager **manager_out
);
Advances iter
, and retrieves the TpChannelManager it now points to. If
there are no more channel managers, manager_out
is not set and FALSE
is
returned.
|
an initialized TpChannelManagerIter |
|
a location to store the channel manager, or NULL . |
Returns : |
FALSE if there are no more channel managers; else TRUE . |
Since 0.7.15
Property Details
The "account-path-suffix"
property
"account-path-suffix" gchar* : Read / Write / Construct Only
The suffix of the account object path such as
"gabble/jabber/chris_40example_2ecom0" for the account whose object path is
TP_ACCOUNT_OBJECT_PATH_BASE
+ "gabble/jabber/chris_40example_2ecom0".
The same as returned by tp_account_get_path_suffix()
.
It is given by the AccountManager in the connection parameters. Or NULL
if
the ConnectionManager or the AccountManager are too old.
Default value: NULL
Since 0.23.2
The "dbus-daemon"
property
"dbus-daemon" TpDBusDaemon* : Read / Write / Construct Only
TpDBusDaemon object encapsulating this object's connection to D-Bus. Read-only except during construction.
If this property is NULL
or omitted during construction, the object will
automatically attempt to connect to the starter or session bus with
tp_dbus_daemon_dup()
just after it is constructed; if this fails, this
property will remain NULL
, and tp_base_connection_register()
will fail.
Since 0.11.3
The "dbus-status"
property
"dbus-status" guint : Read
The Connection.Status as visible on D-Bus, which is the same as
TpBaseConnection.status except that
TP_INTERNAL_CONNECTION_STATUS_NEW
is replaced by
TP_CONNECTION_STATUS_DISCONNECTED
.
The "notify" signal is not currently emitted for this property.
Allowed values: <= 2
Default value: 2
Since 0.11.3
The "has-immortal-handles"
property
"has-immortal-handles" gboolean : Read
This property is not useful to use directly. Its value is TRUE
, to
indicate that this version of telepathy-glib never unreferences handles
until the connection becomes disconnected.
Default value: TRUE
Since 0.13.8
The "interfaces"
property
"interfaces" GStrv : Read
The set of D-Bus interfaces available on this Connection, other than Connection itself.
Since 0.11.3
The "protocol"
property
"protocol" gchar* : Read / Write / Construct Only
Identifier used in the Telepathy protocol when this connection's protocol name is required.
Default value: NULL
The "self-handle"
property
"self-handle" guint : Read / Write
The handle of type TP_HANDLE_TYPE_CONTACT
representing the local user.
Must be set nonzero by the subclass before moving to state CONNECTED.
Default value: 0
Since 0.7.15
The "self-id"
property
"self-id" gchar* : Read
The identifier representing the local user. This is the result of inspecting "self-handle".
Default value: ""
Since 0.21.2
Signal Details
The "clients-interested"
signal
void user_function (TpBaseConnection *connection,
gchar *token,
gpointer user_data) : Has Details
Emitted when a client becomes interested in any token that was added with
tp_base_connection_add_possible_client_interest()
.
The "signal detail" is a GQuark representing token
. Modules implementing
an interface (Location, say) should typically connect to a detailed signal
like
"clients-interested::org.freedesktop.Telepathy.Connection.Interface.Location"
rather than receiving all emissions of this signal.
|
the TpBaseConnection |
|
the interface or part of an interface in which clients are newly interested |
|
user data set when the signal handler was connected. |
The "clients-uninterested"
signal
void user_function (TpBaseConnection *connection,
gchar *token,
gpointer user_data) : Has Details
Emitted when no more clients are interested in an interface added with
tp_base_connection_add_possible_client_interest()
, for which
"clients-interested" was previously emitted.
As with "clients-interested", the "signal detail" is a
GQuark representing token
. Modules implementing an interface (Location,
say) should typically connect to a detailed signal like
"clients-uninterested::org.freedesktop.Telepathy.Connection.Interface.Location"
rather than receiving all emissions of this signal.
|
the TpBaseConnection |
|
the interface or part of an interface in which clients are no longer interested |
|
user data set when the signal handler was connected. |
The "shutdown-finished"
signal
void user_function (TpBaseConnection *connection,
gpointer user_data) : Has Details
Emitted by tp_base_connection_finish_shutdown()
when the underlying
network connection has been closed; TpBaseConnectionManager listens
for this signal and removes connections from its table of active
connections when it is received.
|
the TpBaseConnection |
|
user data set when the signal handler was connected. |