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.

TpBaseConnectionCreateChannelManagersImpl ()

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

Signature of an implementation of the create_channel_managers method of TpBaseConnection.

TpBaseConnectionCreateHandleReposImpl ()

void
(*TpBaseConnectionCreateHandleReposImpl)
                               (TpBaseConnection *self,
                                TpHandleRepoIface *repos[TP_NUM_ENTITY_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.

Subclasses may call g_dbus_object_skeleton_add_interface() at any time before the status reaches CONNECTED. It is considered to be an error to do so after CONNECTED status has been reached.

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.

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.

Since 0.19.1

tp_base_connection_get_dbus_connection ()

GDBusConnection *
tp_base_connection_get_dbus_connection
                               (TpBaseConnection *self);

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.

tp_base_connection_get_handles ()

TpHandleRepoIface *
tp_base_connection_get_handles (TpBaseConnection *self,
                                TpEntityType entity_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_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.

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.

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.

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:

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:

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.

tp_base_connection_disconnect_with_dbus_error ()

void
tp_base_connection_disconnect_with_dbus_error
                               (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

error.

Well-known keys for details are documented in the Telepathy specification's

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_dup_contact_attributes ()

GVariant *
tp_base_connection_dup_contact_attributes
                               (TpBaseConnection *self,
                                const GArray *handles,
                                const gchar * const *interfaces,
                                const gchar * const *assumed_interfaces);

Get contact attributes for the given contacts. Provide attributes for all requested interfaces. If contact attributes are not immediately known, the behaviour is defined by the interface; the attribute should either be omitted from the result or replaced with a default value.

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

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.

tp_base_connection_get_account_path_suffix ()

const gchar *
tp_base_connection_get_account_path_suffix
                               (TpBaseConnection *self);

Since 0.23.2

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

TpBaseConnection

typedef struct _TpBaseConnection TpBaseConnection;

Data structure representing a generic connection implementation.

struct TpBaseConnectionClass

struct TpBaseConnectionClass {
    GDBusObjectSkeletonClass parent_class;

#ifdef __GI_SCANNER__
#else
    TpBaseConnectionCreateHandleReposImpl create_handle_repos;
#endif

    TpBaseConnectionGetUniqueConnectionNameImpl get_unique_connection_name;

    TpBaseConnectionProc connecting;
    TpBaseConnectionProc connected;
    TpBaseConnectionProc disconnected;

    TpBaseConnectionProc shut_down;

    TpBaseConnectionStartConnectingImpl start_connecting;

    TpBaseConnectionCreateChannelManagersImpl create_channel_managers;

    void (*fill_contact_attributes) (TpBaseConnection *self,
        const gchar *dbus_interface,
        TpHandle contact,
        GVariantDict *attributes);
};

The class of a TpBaseConnection. Many members are virtual methods etc. to be filled in in the subclass' class_init function.

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

The “account-path-suffix” property

  “account-path-suffix”      gchar *

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.

Flags: Read / Write / Construct Only

Default value: NULL

Since 0.23.2

The “dbus-connection” property

  “dbus-connection”          GDBusConnection *

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 session bus with g_bus_get_sync() just after it is constructed; if this fails, this property will remain NULL, and tp_base_connection_register() will fail.

Flags: Read / Write / Construct Only

Since 0.99.10

The “interfaces” property

  “interfaces”               GStrv

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

Flags: Read

Since 0.11.3

The “protocol” property

  “protocol”                 gchar *

Identifier used in the Telepathy protocol when this connection's protocol name is required.

Flags: Read / Write / Construct Only

Default value: NULL

The “self-handle” property

  “self-handle”              guint

The handle of type TP_ENTITY_TYPE_CONTACT representing the local user. Must be set nonzero by the subclass before moving to state CONNECTED.

Flags: Read / Write

Default value: 0

Since 0.7.15

The “self-id” property

  “self-id”                  gchar *

The identifier representing the local user. This is the result of inspecting “self-handle”.

Flags: Read

Default value: ""

Since 0.21.2

The “clients-interested” signal

void
user_function (TpBaseConnection *connection,
               gchar            *token,
               gpointer          user_data)

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::im.telepathy.v1.Connection.Interface.Location" rather than receiving all emissions of this signal.

Flags: Has Details

The “clients-uninterested” signal

void
user_function (TpBaseConnection *connection,
               gchar            *token,
               gpointer          user_data)

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::im.telepathy.v1.Connection.Interface.Location" rather than receiving all emissions of this signal.

Flags: Has Details

The “shutdown-finished” signal

void
user_function (TpBaseConnection *connection,
               gpointer          user_data)

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.

Flags: Has Details

The “status-changed” signal

void
user_function (TpBaseConnection *connection,
               guint             status,
               guint             reason,
               gpointer          user_data)

Emitted when the status of this connection changes. Mainly for compatibility since TpBaseConnection doesn't implement TpSvcConnection interface anymore.

Flags: Has Details

Since 0.99.11