![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
TpBaseConnectionTpBaseConnection — base class for TpSvcConnection implementations |
#include <telepathy-glib/base-connection.h> #define TP_INTERNAL_CONNECTION_STATUS_NEW TpBaseConnection; TpBaseConnectionClass; GPtrArray* (*TpBaseConnectionCreateChannelFactoriesImpl) (TpBaseConnection *self); GPtrArray* (*TpBaseConnectionCreateChannelManagersImpl) (TpBaseConnection *self); void (*TpBaseConnectionCreateHandleReposImpl) (TpBaseConnection *self, TpHandleRepoIface *repos[NUM_TP_HANDLE_TYPES]); gchar* (*TpBaseConnectionGetUniqueConnectionNameImpl) (TpBaseConnection *self); void (*TpBaseConnectionProc) (TpBaseConnection *self); gboolean (*TpBaseConnectionStartConnectingImpl) (TpBaseConnection *self, GError **error); 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); 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_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); 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);
TpBaseConnection implements TpSvcConnection, TpSvcDBusProperties and TpSvcConnectionInterfaceRequests.
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.
# 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.
typedef struct { GObject parent; gchar *bus_name; gchar *object_path; TpConnectionStatus status; TpHandle self_handle; } TpBaseConnection;
Data structure representing a generic TpSvcConnection implementation.
In addition to the fields documented here, there are four gpointer fields
which must currently be NULL
(a meaning may be defined for these in a
future version of telepathy-glib), and a pointer to opaque private data.
GObject parent ; |
Fields shared by the superclass. |
gchar *bus_name ; |
A D-Bus well-known bus name, owned by the connection manager process and associated with this connection. Set by tp_base_connection_register; should be considered read-only by subclasses. |
gchar *object_path ; |
The object-path of this connection. Set by tp_base_connection_register; should be considered read-only by subclasses. |
TpConnectionStatus status ; |
Connection status - may either be a valid TpConnectionStatus or
TP_INTERNAL_CONNECTION_STATUS_NEW. Should be considered read-only by
subclasses: use tp_base_connection_change_status() to set it.
|
TpHandle self_handle ; |
The handle of type TP_HANDLE_TYPE_CONTACT representing the
local user. Must be set nonzero by the subclass before moving to state
CONNECTED. Since 0.7.15, setting this property directly is
deprecated, in favour of tp_base_connection_set_self_handle() ; if this
property is set directly, the connection must ensure it holds a reference
to the handle. Changing this property directly having moved to state
CONNECTED is very strongly discouraged, as this will prevent the
SelfHandleChanged signal being emitted.
|
typedef struct { GObjectClass parent_class; TpBaseConnectionCreateHandleReposImpl create_handle_repos; TpBaseConnectionCreateChannelFactoriesImpl create_channel_factories; TpBaseConnectionGetUniqueConnectionNameImpl get_unique_connection_name; TpBaseConnectionProc connecting; TpBaseConnectionProc connected; TpBaseConnectionProc disconnected; TpBaseConnectionProc shut_down; TpBaseConnectionStartConnectingImpl start_connecting; const gchar **interfaces_always_present; TpBaseConnectionCreateChannelManagersImpl create_channel_managers; } TpBaseConnectionClass;
The class of a TpBaseConnection. Many members are virtual methods etc. to be filled in in the subclass' class_init function.
In addition to the fields documented here, there are three gpointer fields
which must currently be NULL
(a meaning may be defined for these in a
future version of telepathy-glib), and a pointer to opaque private data.
GObjectClass parent_class ; |
The superclass' structure |
TpBaseConnectionCreateHandleReposImpl create_handle_repos ; |
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_channel_factories ; |
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 get_unique_connection_name ; |
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 connecting ; |
If set by subclasses, will be called just after the state
changes to CONNECTING. May be NULL if nothing special needs to happen.
|
TpBaseConnectionProc connected ; |
If set by subclasses, will be called just after the state
changes to CONNECTED. May be NULL if nothing special needs to happen.
|
TpBaseConnectionProc disconnected ; |
If set by subclasses, will be called just after the state
changes to DISCONNECTED. May be NULL if nothing special needs to happen.
|
TpBaseConnectionProc shut_down ; |
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 start_connecting ; |
Asynchronously start connecting - called to implement
the Connect D-Bus method. See TpBaseConnectionStartConnectingImpl for
details. May not be left as NULL .
|
const gchar **interfaces_always_present ; |
A strv 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() .
|
TpBaseConnectionCreateChannelManagersImpl create_channel_managers ; |
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
|
GPtrArray* (*TpBaseConnectionCreateChannelFactoriesImpl) (TpBaseConnection *self);
Signature of an implementation of the create_channel_factories method of TpBaseConnection.
self : |
The implementation, a subclass of TpBaseConnection |
Returns : | a GPtrArray of objects implementing TpChannelFactoryIface which, between them, implement all channel types this Connection supports. |
GPtrArray* (*TpBaseConnectionCreateChannelManagersImpl) (TpBaseConnection *self);
Signature of an implementation of the create_channel_managers method of TpBaseConnection.
self : |
The implementation, a subclass of TpBaseConnection |
Returns : | a GPtrArray of objects implementing TpChannelManager which, between them, implement all channel types this Connection supports. |
void (*TpBaseConnectionCreateHandleReposImpl) (TpBaseConnection *self, TpHandleRepoIface *repos[NUM_TP_HANDLE_TYPES]);
Signature of an implementation of the create_handle_repos method of TpBaseConnection.
self : |
The connection object |
repos : |
An array of pointers to be filled in; the implementation may assume all are initially NULL. |
gchar* (*TpBaseConnectionGetUniqueConnectionNameImpl) (TpBaseConnection *self);
Signature of the get_unique_connection_name
virtual method
on TpBaseConnection.
self : |
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. |
void (*TpBaseConnectionProc) (TpBaseConnection *self);
Signature of a virtual method on TpBaseConnection that takes no additional parameters and returns nothing.
self : |
The connection object |
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.
self : |
The connection object |
error : |
Set to the error if FALSE is returned
|
Returns : | FALSE if failure has already occurred, else TRUE .
|
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.
self : |
A connection |
cm_name : |
The name of the connection manager in the Telepathy protocol |
bus_name : |
Used to return the bus name corresponding to the connection
if TRUE is returned; must not be NULL . To be freed by the caller.
|
object_path : |
Used to return the object path of the connection if
TRUE is returned; must not be NULL . To be freed by the caller.
|
error : |
Used to return an error if FALSE is returned; may be NULL
|
Returns : | TRUE on success, FALSE on error.
|
TpHandleRepoIface* tp_base_connection_get_handles (TpBaseConnection *self, TpHandleType handle_type);
self : |
A connection |
handle_type : |
The handle type |
Returns : | the handle repository corresponding to the given handle type, or NULL if it's unsupported or invalid. |
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.
self : |
A connection |
Returns : | the current self handle of the connection. |
Since 0.7.15
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.
self : |
A connection |
self_handle : |
The new self handle for the connection. |
Since 0.7.15
void tp_base_connection_change_status (TpBaseConnection *self, TpConnectionStatus status, TpConnectionStatusReason reason);
Change the status of the connection. The allowed state transitions are:
Before the transition to CONNECTED, the implementation must have discovered
the handle for the local user, obtained a reference to that handle and
stored it in the self_handle
member of TpBaseConnection.
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:
status
member of TpBaseConnection
shut_down
callback
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.
self : |
The connection |
status : |
The new status |
reason : |
The reason for the status change |
void tp_base_connection_disconnect_with_dbus_error (TpBaseConnection *self, const gchar *error_name, GHashTable *details, TpConnectionStatusReason reason);
Change the status of the connection to TP_CONNECTION_STATUS_DISCONNECTED
,
as if by a call to tp_base_connection_change_status()
. Before doing so,
emit the ConnectionError D-Bus signal to give more details of the error.
details
may contain, among other entries, the well-known key
"debug-message", whose value should have type G_TYPE_STRING.
self : |
The connection |
error_name : |
The D-Bus error with which the connection changed status to Disconnected |
details : |
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 empty.
|
reason : |
The reason code to use in the StatusChanged signal
(a less specific, non-extensible version of error_name )
|
Since 0.7.24
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.
self : |
The connection |
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 (interfaces_always_present
in
TpBaseConnectionClass) will be supported.
self : |
A TpBaseConnection in state TP_INTERNAL_CONNECTION_STATUS_NEW or TP_CONNECTION_STATUS_CONNECTING |
interfaces : |
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).
|
void tp_base_connection_dbus_request_handles (TpSvcConnection *iface, guint handle_type, const gchar **names, DBusGMethodInvocation *context);
Implements D-Bus method RequestHandles on interface org.freedesktop.Telepathy.Connection. Exported so subclasses can use it as a basis for their own implementations (for instance, at the time of writing Gabble's GabbleConnection does its own processing for room handles, in order to validate them asynchronously, but delegates to this implementation for all other types).
iface : |
A pointer to TpBaseConnection, cast to a pointer to TpSvcConnection |
handle_type : |
The handle type (TpHandleType) as a guint |
names : |
A strv of handle names |
context : |
The dbus-glib method invocation context |
#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.
conn : |
A TpBaseConnection |
context : |
A DBusGMethodInvocation |
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
self : |
An instance of the TpBaseConnections that uses the Contacts mixin |
typedef struct { } TpChannelManagerIter;
An iterator over the TpChannelManager objects known to a TpBaseConnection. It has no public fields.
Since 0.7.15
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:
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... }
iter : |
an uninitialized TpChannelManagerIter |
self : |
a connection |
Since 0.7.15
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.
iter : |
an initialized TpChannelManagerIter |
manager_out : |
a location to store the channel manager, or NULL .
|
Returns : | FALSE if there are no more channel managers; else TRUE .
|
Since 0.7.15
"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
"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
"shutdown-finished"
signalvoid user_function (TpBaseConnection *arg0, gpointer user_data) : Run Last / 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.
user_data : |
user data set when the signal handler was connected. |