![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
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
); 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
); 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.
"dbus-daemon" TpDBusDaemon* : Read / Write / Construct Only "dbus-status" guint : Read "interfaces" GStrv* : Read "protocol" gchar* : Read / Write / Construct Only "self-handle" guint : Read / Write
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))
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 |
Fields shared by the superclass. |
gchar * |
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 * |
The object-path of this connection. Set by tp_base_connection_register; should be considered read-only by subclasses. |
TpConnectionStatus |
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 |
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; #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; 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 |
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 .
|
const gchar ** |
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 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.
|
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.
|
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]
);
|
|
|
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. |
void (*TpBaseConnectionProc) (TpBaseConnection *self
);
Signature of a virtual method on TpBaseConnection that takes no additional parameters and returns nothing.
|
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.
TpDBusDaemon * tp_base_connection_get_dbus_daemon (TpBaseConnection *self
);
|
|
Returns : |
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.
|
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. |
TpHandle tp_base_connection_get_self_handle (TpBaseConnection *self
);
|
|
Returns : |
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
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.
|
The connection |
|
The new status |
|
The reason for the status change |
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
);
|
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
);
|
|
|
|
Returns : |
"dbus-daemon"
property"dbus-daemon" TpDBusDaemon* : Read / Write / Construct Only
The D-Bus daemon used by this object.
"dbus-status"
property"dbus-status" guint : Read
The connection status as visible on D-Bus.
Allowed values: <= 2
Default value: 2
"interfaces"
property"interfaces" GStrv* : Read
The set of D-Bus interfaces available on this Connection, other than Connection itself.
"protocol"
property"protocol" gchar* : Read / Write / Construct Only
Identifier string used when the 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.
Default value: 0
"shutdown-finished"
signalvoid user_function (TpBaseConnection *tpbaseconnection, gpointer user_data) : Run Last / Has Details
|
the object which received the signal. |
|
user data set when the signal handler was connected. |