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

TpBaseConnectionClass

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.

TpBaseConnectionCreateChannelFactoriesImpl ()

GPtrArray *         (*TpBaseConnectionCreateChannelFactoriesImpl)
                                                        (TpBaseConnection *self);

Signature of an implementation of the create_channel_factories method of TpBaseConnection.

TpBaseConnectionCreateChannelManagersImpl ()

GPtrArray *         (*TpBaseConnectionCreateChannelManagersImpl)
                                                        (TpBaseConnection *self);

Signature of an implementation of the create_channel_managers method of TpBaseConnection.

TpBaseConnectionCreateHandleReposImpl ()

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

Signature of an implementation of the create_handle_repos method of TpBaseConnection.

TpBaseConnectionGetUniqueConnectionNameImpl ()

gchar *             (*TpBaseConnectionGetUniqueConnectionNameImpl)
                                                        (TpBaseConnection *self);

Signature of the get_unique_connection_name virtual method on TpBaseConnection.

TpBaseConnectionProc ()

void                (*TpBaseConnectionProc)             (TpBaseConnection *self);

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

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

tp_base_connection_get_handles ()

TpHandleRepoIface * tp_base_connection_get_handles      (TpBaseConnection *self,
                                                         TpHandleType handle_type);

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.

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.

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:

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:

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.

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

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.

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.

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 (interfaces_always_present in TpBaseConnectionClass) will be supported.

tp_base_connection_dbus_request_handles ()

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

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.

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

TpChannelManagerIter

typedef struct {
} TpChannelManagerIter;

An iterator over the TpChannelManager objects known to a TpBaseConnection. It has no public fields.

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

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.

Since 0.7.15

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 "shutdown-finished" signal

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