TpBaseConnection

TpBaseConnection — base class for TpSvcConnection implementations

Synopsis

#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);

Object Hierarchy

  GObject
   +----TpBaseConnection

Implemented Interfaces

TpBaseConnection implements TpSvcConnection, TpSvcDBusProperties and TpSvcConnectionInterfaceRequests.

Properties

  "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

Signals

  "shutdown-finished"                              : Run Last / 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))

TpBaseConnection

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.

TpBaseConnectionClass

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 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

TpBaseConnectionCreateChannelFactoriesImpl ()

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.

TpBaseConnectionCreateChannelManagersImpl ()

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.

TpBaseConnectionCreateHandleReposImpl ()

void                (*TpBaseConnectionCreateHandleReposImpl)
                                                        (TpBaseConnection *self,
                                                         TpHandleRepoIface *repos[NUM_TP_HANDLE_TYPES]);

self :

repos :

TpBaseConnectionGetUniqueConnectionNameImpl ()

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.

TpBaseConnectionProc ()

void                (*TpBaseConnectionProc)             (TpBaseConnection *self);

Signature of a virtual method on TpBaseConnection that takes no additional parameters and returns nothing.

self :

 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.

self :

 The connection object

error :

 Set to the error if FALSE is returned

Returns :

 FALSE if failure has already occurred, else TRUE.

tp_base_connection_get_dbus_daemon ()

TpDBusDaemon *      tp_base_connection_get_dbus_daemon  (TpBaseConnection *self);

self :

Returns :

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.

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. To be freed by the caller.. out.

object_path :

 Used to return the object path of the connection if TRUE is returned. To be freed by the caller.. out.

error :

 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);

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.. transfer none.

tp_base_connection_get_self_handle ()

TpHandle            tp_base_connection_get_self_handle  (TpBaseConnection *self);

self :

Returns :

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.

self :

 A connection

self_handle :

 The new self handle for the connection.

Since 0.7.15

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:

  • NEW -> CONNECTING
  • CONNECTING -> CONNECTED
  • NEW -> CONNECTED (equivalent to both of the above one after the other - see below)
  • (anything except DISCONNECTED) -> DISCONNECTED

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:

  • Update the status member of TpBaseConnection
  • If the new state is DISCONNECTED, call the close_all_channels callback on all channel factories
  • Emit the D-Bus StatusChanged signal
  • Call the subclass' status change callback
  • Call the channel factories' status change callbacks
  • If the new state is DISCONNECTED, call the subclass' 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

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);

self :

error_name :

details :

reason :

tp_base_connection_finish_shutdown ()

void                tp_base_connection_finish_shutdown  (TpBaseConnection *self);

self :

tp_base_connection_add_interfaces ()

void                tp_base_connection_add_interfaces   (TpBaseConnection *self,
                                                         const gchar **interfaces);

self :

interfaces :

tp_base_connection_dbus_request_handles ()

void                tp_base_connection_dbus_request_handles
                                                        (TpSvcConnection *iface,
                                                         guint handle_type,
                                                         const gchar **names,
                                                         DBusGMethodInvocation *context);

iface :

handle_type :

names :

context :

TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED()

#define             TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED(conn, context)

conn :

context :

tp_base_connection_register_with_contacts_mixin ()

void                tp_base_connection_register_with_contacts_mixin
                                                        (TpBaseConnection *self);

self :

TpChannelManagerIter

typedef struct {
} TpChannelManagerIter;

tp_base_connection_channel_manager_iter_init ()

void                tp_base_connection_channel_manager_iter_init
                                                        (TpChannelManagerIter *iter,
                                                         TpBaseConnection *self);

iter :

self :

tp_base_connection_channel_manager_iter_next ()

gboolean            tp_base_connection_channel_manager_iter_next
                                                        (TpChannelManagerIter *iter,
                                                         TpChannelManager **manager_out);

iter :

manager_out :

Returns :

Property Details

The "dbus-daemon" property

  "dbus-daemon"              TpDBusDaemon*         : Read / Write / Construct Only

The D-Bus daemon used by this object.

The "dbus-status" property

  "dbus-status"              guint                 : Read

The connection status as visible on D-Bus.

Allowed values: <= 2

Default value: 2

The "interfaces" property

  "interfaces"               GStrv*                : Read

The set of D-Bus interfaces available on this Connection, other than Connection itself.

The "protocol" property

  "protocol"                 gchar*                : Read / Write / Construct Only

Identifier string used when the 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.

Default value: 0

Signal Details

The "shutdown-finished" signal

void                user_function                      (TpBaseConnection *tpbaseconnection,
                                                        gpointer          user_data)             : Run Last / Has Details

tpbaseconnection :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

See Also

TpBaseConnectionManager, TpSvcConnection
Generated by GTK-Doc V1.14