TpConnection

TpConnection — proxy object for a Telepathy connection

Synopsis

#include <telepathy-glib/telepathy-glib.h>

void                (*TpConnectionNameListCb)           (const gchar * const *names,
                                                         gsize n,
                                                         const gchar * const *cms,
                                                         const gchar * const *protocols,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_list_connection_names            (TpDBusDaemon *bus_daemon,
                                                         TpConnectionNameListCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
                    TpConnection;
struct              TpConnectionClass;
#define             TP_CONNECTION_FEATURE_CORE
#define             TP_CONNECTION_FEATURE_CONNECTED
#define             TP_CONNECTION_FEATURE_CAPABILITIES
#define             TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS
#define             TP_CONNECTION_FEATURE_CONTACT_INFO
#define             TP_CONNECTION_FEATURE_BALANCE
#define             TP_CONNECTION_FEATURE_CONTACT_LIST
#define             TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES
#define             TP_CONNECTION_FEATURE_CONTACT_GROUPS
#define             TP_CONNECTION_FEATURE_CONTACT_BLOCKING
#define             TP_CONNECTION_FEATURE_ALIASING
void                tp_connection_disconnect_async      (TpConnection *self,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_disconnect_finish     (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
TpAccount *         tp_connection_get_account           (TpConnection *self);
TpConnectionStatus  tp_connection_get_status            (TpConnection *self,
                                                         TpConnectionStatusReason *reason);
const gchar *       tp_connection_get_cm_name           (TpConnection *self);
const gchar *       tp_connection_get_protocol_name     (TpConnection *self);
TpContact *         tp_connection_get_self_contact      (TpConnection *self);
void                tp_connection_init_known_interfaces (void);
gint                tp_connection_presence_type_cmp_availability
                                                        (TpConnectionPresenceType p1,
                                                         TpConnectionPresenceType p2);
TpCapabilities *    tp_connection_get_capabilities      (TpConnection *self);
TpAvatarRequirements * tp_connection_get_avatar_requirements
                                                        (TpConnection *self);
TpContactInfoFlags  tp_connection_get_contact_info_flags
                                                        (TpConnection *self);
GList *             tp_connection_dup_contact_info_supported_fields
                                                        (TpConnection *self);
void                tp_connection_set_contact_info_async
                                                        (TpConnection *self,
                                                         GList *info,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_set_contact_info_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
#define             TP_UNKNOWN_CONNECTION_STATUS
#define             TP_ERRORS_DISCONNECTED
const gchar *       tp_connection_get_detailed_error    (TpConnection *self,
                                                         const GHashTable **details);
gchar *             tp_connection_dup_detailed_error_vardict
                                                        (TpConnection *self,
                                                         GVariant **details);
void                tp_connection_add_client_interest   (TpConnection *self,
                                                         const gchar *interested_in);
void                tp_connection_add_client_interest_by_id
                                                        (TpConnection *self,
                                                         GQuark interested_in);
GBinding *          tp_connection_bind_connection_status_to_property
                                                        (TpConnection *self,
                                                         gpointer target,
                                                         const char *target_property,
                                                         gboolean invert);
gboolean            tp_connection_get_balance           (TpConnection *self,
                                                         gint *balance,
                                                         guint *scale,
                                                         const gchar **currency);
const gchar *       tp_connection_get_balance_uri       (TpConnection *self);


#define             TP_TYPE_AVATAR_REQUIREMENTS
struct              TpAvatarRequirements;
TpAvatarRequirements * tp_avatar_requirements_new       (GStrv supported_mime_types,
                                                         guint minimum_width,
                                                         guint minimum_height,
                                                         guint recommended_width,
                                                         guint recommended_height,
                                                         guint maximum_width,
                                                         guint maximum_height,
                                                         guint maximum_bytes);
TpAvatarRequirements * tp_avatar_requirements_copy      (const TpAvatarRequirements *self);
void                tp_avatar_requirements_destroy      (TpAvatarRequirements *self);

struct              TpContactInfoFieldSpec;
#define             TP_TYPE_CONTACT_INFO_FIELD_SPEC
TpContactInfoFieldSpec * tp_contact_info_field_spec_copy
                                                        (const TpContactInfoFieldSpec *self);
void                tp_contact_info_field_spec_free     (TpContactInfoFieldSpec *self);
#define             TP_TYPE_CONTACT_INFO_SPEC_LIST
GList *             tp_contact_info_spec_list_copy      (GList *list);
void                tp_contact_info_spec_list_free      (GList *list);
struct              TpContactInfoField;
#define             TP_TYPE_CONTACT_INFO_FIELD
TpContactInfoField * tp_contact_info_field_new          (const gchar *field_name,
                                                         GStrv parameters,
                                                         GStrv field_value);
TpContactInfoField * tp_contact_info_field_copy         (const TpContactInfoField *self);
void                tp_contact_info_field_free          (TpContactInfoField *self);
#define             TP_TYPE_CONTACT_INFO_LIST
GList *             tp_contact_info_list_copy           (GList *list);
void                tp_contact_info_list_free           (GList *list);


TpContactListState  tp_connection_get_contact_list_state
                                                        (TpConnection *self);
gboolean            tp_connection_get_contact_list_persists
                                                        (TpConnection *self);
gboolean            tp_connection_get_can_change_contact_list
                                                        (TpConnection *self);
gboolean            tp_connection_get_request_uses_message
                                                        (TpConnection *self);
GPtrArray *         tp_connection_dup_contact_list      (TpConnection *self);
void                tp_connection_request_subscription_async
                                                        (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         const gchar *message,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_request_subscription_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_authorize_publication_async
                                                        (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_authorize_publication_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_remove_contacts_async (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_remove_contacts_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_unsubscribe_async     (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_unsubscribe_finish    (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_unpublish_async       (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_unpublish_finish      (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

gboolean            tp_connection_get_disjoint_groups   (TpConnection *self);
TpContactMetadataStorageType tp_connection_get_group_storage
                                                        (TpConnection *self);
const gchar * const * tp_connection_get_contact_groups  (TpConnection *self);
void                tp_connection_set_group_members_async
                                                        (TpConnection *self,
                                                         const gchar *group,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_set_group_members_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_add_to_group_async    (TpConnection *self,
                                                         const gchar *group,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_add_to_group_finish   (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_remove_from_group_async
                                                        (TpConnection *self,
                                                         const gchar *group,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_remove_from_group_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_remove_group_async    (TpConnection *self,
                                                         const gchar *group,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_remove_group_finish   (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_rename_group_async    (TpConnection *self,
                                                         const gchar *old_name,
                                                         const gchar *new_name,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_rename_group_finish   (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

void                tp_connection_block_contacts_async  (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         gboolean report_abusive,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_block_contacts_finish (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tp_connection_unblock_contacts_async
                                                        (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_connection_unblock_contacts_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            tp_connection_can_report_abusive    (TpConnection *self);
GPtrArray *         tp_connection_get_blocked_contacts  (TpConnection *self);

gboolean            tp_connection_can_set_contact_alias (TpConnection *self);

Object Hierarchy

  GObject
   +----TpProxy
         +----TpConnection
  GBoxed
   +----TpAvatarRequirements
  GBoxed
   +----TpContactInfoFieldSpec
  GBoxed
   +----TpContactInfoField

Properties

  "balance"                  gint                  : Read
  "balance-currency"         gchar*                : Read
  "balance-scale"            guint                 : Read
  "balance-uri"              gchar*                : Read
  "blocked-contacts"         GPtrArray*            : Read
  "can-change-contact-list"  gboolean              : Read
  "can-report-abusive"       gboolean              : Read
  "capabilities"             TpCapabilities*       : Read
  "cm-name"                  gchar*                : Read
  "contact-groups"           GStrv                 : Read
  "contact-list-persists"    gboolean              : Read
  "contact-list-state"       guint                 : Read
  "disjoint-groups"          gboolean              : Read
  "group-storage"            guint                 : Read
  "protocol-name"            gchar*                : Read
  "request-uses-message"     gboolean              : Read
  "self-contact"             TpContact*            : Read
  "status"                   guint                 : Read
  "status-reason"            guint                 : Read

Signals

  "balance-changed"                                : Has Details
  "blocked-contacts-changed"                       : Run Last
  "contact-list-changed"                           : Run Last
  "group-renamed"                                  : Run Last
  "groups-created"                                 : Run Last
  "groups-removed"                                 : Run Last

Description

TpConnection objects represent Telepathy instant messaging connections accessed via D-Bus.

TpConnection objects should be obtained from a TpAccount, unless you are implementing a lower-level Telepathy component (such as the account manager service itself).

Since 0.16, TpConnection always has a non-NULL "factory", and its "factory" will be propagated to its TpChannel objects (if any). Similarly, the "factory"'s features will be used for TpContact objects. If a TpConnection is created without going via the TpAccount or specifying a "factory", the default is to use a new TpAutomaticClientFactory.

Details

TpConnectionNameListCb ()

void                (*TpConnectionNameListCb)           (const gchar * const *names,
                                                         gsize n,
                                                         const gchar * const *cms,
                                                         const gchar * const *protocols,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback supplied to tp_list_connection_names().

names :

NULL-terminated array of n connection bus names, or NULL on error. [array zero-terminated=1]

n :

number of names (not including the final NULL), or 0 on error

cms :

NULL-terminated array of n connection manager names (e.g. "gabble") in the same order as names, or NULL on error. [array zero-terminated=1]

protocols :

NULL-terminated array of n protocol names as defined in the Telepathy spec (e.g. "jabber") in the same order as names, or NULL on error. [array zero-terminated=1]

error :

NULL on success, or an error that occurred

user_data :

user-supplied data

weak_object :

user-supplied weakly referenced object

Since 0.7.1


tp_list_connection_names ()

void                tp_list_connection_names            (TpDBusDaemon *bus_daemon,
                                                         TpConnectionNameListCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

List the bus names of all the connections that currently exist, together with the connection manager name and the protocol name for each connection. Call the callback when done.

The bus names passed to the callback can be used to construct TpConnection objects for any connections that are of interest.

bus_daemon :

proxy for the D-Bus daemon

callback :

callback to be called when listing the connections succeeds or fails; not called if the D-Bus connection fails completely or if the weak_object goes away

user_data :

user-supplied data for the callback

destroy :

callback to destroy the user-supplied data, called after callback, but also if the D-Bus connection fails or if the weak_object goes away

weak_object :

if not NULL, will be weakly referenced; the callback will not be called if the object has vanished. [allow-none]

Since 0.7.1


TpConnection

typedef struct _TpConnection TpConnection;

A proxy object for a Telepathy connection. There are no interesting public struct fields.

(Changed in 0.7.12: the layout of the structure is visible, allowing subclassing.)

Since 0.7.1


struct TpConnectionClass

struct TpConnectionClass {
    TpProxyClass parent_class;
};

The class of a TpConnection. In addition to parent_class there are four pointers reserved for possible future use.

(Changed in 0.7.12: the layout of the structure is visible, allowing subclassing.)

TpProxyClass parent_class;

the parent class

Since 0.7.1


TP_CONNECTION_FEATURE_CORE

#define             TP_CONNECTION_FEATURE_CORE

Expands to a call to a function that returns a quark for the "core" feature on a TpConnection.

When this feature is prepared, the basic properties of the Connection have been retrieved and are available for use, and change-notification has been set up for those that can change.

Specifically, this implies that:

prepared does not imply connected

This feature does not imply that the connection has successfully connected. It only implies that an initial status (disconnected, connecting or connected) has been discovered.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.11.3


TP_CONNECTION_FEATURE_CONNECTED

#define             TP_CONNECTION_FEATURE_CONNECTED

Expands to a call to a function that returns a GQuark representing the "connected" feature.

When this feature is prepared, it means that the connection has become connected to the appropriate real-time communications service, and all information requested via other features has been updated accordingly. In particular, the following aspects of TP_CONNECTION_FEATURE_CORE will be up to date:

Someone still has to call Connect()

Requesting this feature via tp_proxy_prepare_async() means that you want to wait for the connection to connect, but it doesn't actually start the process of connecting. For connections associated with a TpAccount, the account manager service is responsible for doing that, but if you are constructing connections directly (e.g. if you are implementing an account manager), you must tp_cli_connection_call_connect() separately.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.11.3


TP_CONNECTION_FEATURE_CAPABILITIES

#define             TP_CONNECTION_FEATURE_CAPABILITIES

Expands to a call to a function that returns a GQuark representing the "capabilities" feature.

When this feature is prepared, the Requests.RequestableChannelClasses property of the Connection has been retrieved. In particular, the TpConnection:capabilities property has been set.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.11.3


TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS

#define             TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS

Expands to a call to a function that returns a GQuark representing the "avatar-requirements" feature.

When this feature is prepared, the avatar requirements of the Connection has been retrieved. Use tp_connection_get_avatar_requirements() to get them once prepared.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.11.4


TP_CONNECTION_FEATURE_CONTACT_INFO

#define             TP_CONNECTION_FEATURE_CONTACT_INFO

Expands to a call to a function that returns a GQuark representing the "contact-info" feature.

When this feature is prepared, the ContactInfoFlags and SupportedFields of the Connection has been retrieved. Use tp_connection_get_contact_info_flags() and tp_connection_dup_contact_info_supported_fields() to get them once prepared.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.11.7


TP_CONNECTION_FEATURE_BALANCE

#define             TP_CONNECTION_FEATURE_BALANCE

Expands to a call to a function that returns a GQuark representing the "balance" feature.

When this feature is prepared, the Balance.AccountBalance and Balance.ManageCreditURI properties of the Connection have been retrieved. In particular, the TpConnection:balance, TpConnection:balance-scale, TpConnection:balance-currency and TpConnection:balance-uri properties have been set and the TpConnection::balance-changed: will be emitted when they are changed.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.15.1


TP_CONNECTION_FEATURE_CONTACT_LIST

#define             TP_CONNECTION_FEATURE_CONTACT_LIST

Expands to a call to a function that returns a GQuark representing the "contact-list" feature.

When this feature is prepared, the TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES has been prepared, so the contact list properties of the Connection has been retrieved. If "contact-list-state" is TP_CONTACT_LIST_STATE_SUCCESS, all TpContact objects will also be created and prepared with the desired features. See tp_connection_dup_contact_list() to get the list of contacts, and tp_client_factory_add_contact_features() to define which features needs to be prepared on them.

This feature will fail to prepare when using obsolete Telepathy connection managers which do not implement the ContactList interface.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.15.5


TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES

#define             TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES

Expands to a call to a function that returns a GQuark representing the "contact-list-properties" feature.

When this feature is prepared, the contact list properties of the Connection has been retrieved. This feature will fail to prepare when using obsolete Telepathy connection managers which do not implement the ContactList interface.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.17.0


TP_CONNECTION_FEATURE_CONTACT_GROUPS

#define             TP_CONNECTION_FEATURE_CONTACT_GROUPS

Expands to a call to a function that returns a GQuark representing the "contact-groups" feature.

When this feature is prepared, the contact groups properties of the Connection has been retrieved.

See "contact-groups" to get the list of groups a contact is member of.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.15.5


TP_CONNECTION_FEATURE_CONTACT_BLOCKING

#define             TP_CONNECTION_FEATURE_CONTACT_BLOCKING

Expands to a call to a function that returns a GQuark representing the "contact-blocking" feature.

When this feature is prepared, "blocked-contacts" will contain an up-to-date list of TpContacts the user has blocked, and "can-report-abusive" will indicate whether abusive contacts can be reported to the server administrator.

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.17.0


TP_CONNECTION_FEATURE_ALIASING

#define             TP_CONNECTION_FEATURE_ALIASING

Expands to a call to a function that returns a GQuark representing the "aliasing" feature.

This feature needs to be prepared in order to use tp_connection_can_set_contact_alias().

One can ask for a feature to be prepared using the tp_proxy_prepare_async() function, and waiting for it to callback.

Since 0.17.3


tp_connection_disconnect_async ()

void                tp_connection_disconnect_async      (TpConnection *self,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Disconnect the connection.

This method is intended for use by AccountManager implementations, such as Mission Control. To disconnect a connection managed by an AccountManager, either use tp_account_request_presence_async() or tp_account_set_enabled_async(), depending whether the intention is to put the account offline temporarily, or disable it longer-term.

self :

a TpConnection

callback :

a callback to call when the request is satisfied

user_data :

data to pass to callback

Since 0.17.5


tp_connection_disconnect_finish ()

gboolean            tp_connection_disconnect_finish     (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Interpret the result of tp_connection_disconnect_async().

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the call was successful, otherwise FALSE

Since 0.17.5


tp_connection_get_account ()

TpAccount *         tp_connection_get_account           (TpConnection *self);

Return the the TpAccount associated with this connection. Will return NULL if self was not acquired from a TpAccount via tp_account_get_connection(), or if the account object got finalized in the meantime (TpConnection does not keep a strong ref on its TpAccount).

self :

a connection

Returns :

the account associated with this connection, or NULL. [transfer none]

Since 0.15.5


tp_connection_get_status ()

TpConnectionStatus  tp_connection_get_status            (TpConnection *self,
                                                         TpConnectionStatusReason *reason);

If reason is not NULL it is set to the reason why "status" changed to its current value, or TP_CONNECTION_STATUS_REASON_NONE_SPECIFIED if unknown.

self :

a connection

reason :

a TpConnectionStatusReason, or NULL. [out]

Returns :

This connection's status, or TP_UNKNOWN_CONNECTION_STATUS if we don't know yet.

Since 0.7.14


tp_connection_get_cm_name ()

const gchar *       tp_connection_get_cm_name           (TpConnection *self);

self :

a TpConnection

Returns :

the same as the "cm-name" property

Since 0.19.3


tp_connection_get_protocol_name ()

const gchar *       tp_connection_get_protocol_name     (TpConnection *self);

self :

a TpConnection

Returns :

the same as the "protocol-name" property

Since 0.13.16


tp_connection_get_self_contact ()

TpContact *         tp_connection_get_self_contact      (TpConnection *self);

Return a TpContact representing the local user on this connection.

The returned object is not necessarily valid after the main loop is re-entered; ref it with g_object_ref() if you want to keep it.

self :

a connection

Returns :

the value of the TpConnection:self-contact property, which may be NULL. [transfer none]

Since 0.13.9


tp_connection_init_known_interfaces ()

void                tp_connection_init_known_interfaces (void);

Ensure that the known interfaces for TpConnection have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument TP_TYPE_CONNECTION.

Since 0.7.6


tp_connection_presence_type_cmp_availability ()

gint                tp_connection_presence_type_cmp_availability
                                                        (TpConnectionPresenceType p1,
                                                         TpConnectionPresenceType p2);

Compares p1 and p2 like strcmp(). p1 > p2 means p1 is more available than p2.

The order used is: available > busy > away > xa > hidden > offline > error > unknown > unset

p1 :

a TpConnectionPresenceType

p2 :

a TpConnectionPresenceType

Returns :

-1, 0 or 1, if p1 is <, == or > than p2.

Since 0.7.16


tp_connection_get_capabilities ()

TpCapabilities *    tp_connection_get_capabilities      (TpConnection *self);

self :

a connection

Returns :

the same TpCapabilities as the "capabilities" property. [transfer none]

Since 0.11.3


tp_connection_get_avatar_requirements ()

TpAvatarRequirements * tp_connection_get_avatar_requirements
                                                        (TpConnection *self);

To wait for valid avatar requirements, call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS.

This property cannot change after self goes to the Connected state.

self :

a connection

Returns :

a TpAvatarRequirements struct, or NULL if the feature is not yet prepared or the connection doesn't have the necessary properties. [transfer none]

Since 0.11.4


tp_connection_get_contact_info_flags ()

TpContactInfoFlags  tp_connection_get_contact_info_flags
                                                        (TpConnection *self);

Returns the flags describing how contact info (vCards) behaves on this connection

To wait for valid contact info flags, call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_INFO.

This property cannot change after self goes to the Connected state.

self :

a connection

Returns :

a set of TpContactInfoFlags

Since 0.11.7


tp_connection_dup_contact_info_supported_fields ()

GList *             tp_connection_dup_contact_info_supported_fields
                                                        (TpConnection *self);

Returns a newly allocated GList of supported contact info fields for this connection. The list must be freed with tp_contact_info_spec_list_free().

To wait for valid supported fields, call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_INFO.

This property cannot change after self goes to the Connected state.

self :

a connection

Returns :

a GList of TpContactInfoFieldSpec struct, or NULL if the feature is not yet prepared or the connection doesn't have the necessary properties. [element-type TelepathyGLib.ContactInfoFieldSpec][transfer full]

Since 0.19.9


tp_connection_set_contact_info_async ()

void                tp_connection_set_contact_info_async
                                                        (TpConnection *self,
                                                         GList *info,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Requests an asynchronous set of the contact info of self. When the operation is finished, callback will be called. You can then call tp_connection_set_contact_info_finish() to get the result of the operation.

This method should not be expected to succeed if the result of tp_connection_get_contact_info_flags() does not include TP_CONTACT_INFO_FLAG_CAN_SET.

self :

a TpConnection

info :

a GList of TpContactInfoField. [element-type TelepathyGLib.ContactInfoField]

callback :

a callback to call when the request is satisfied

user_data :

data to pass to callback

Since 0.11.7


tp_connection_set_contact_info_finish ()

gboolean            tp_connection_set_contact_info_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async set of self info.

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to be filled

Returns :

TRUE if the request call was successful, otherwise FALSE

Since 0.11.7


TP_UNKNOWN_CONNECTION_STATUS

#define TP_UNKNOWN_CONNECTION_STATUS ((TpConnectionStatus) -1)

An invalid connection status used in TpConnection to indicate that the status has not yet been discovered.

Since 0.7.1


TP_ERRORS_DISCONNECTED

#define TP_ERRORS_DISCONNECTED (tp_errors_disconnected_quark ())

GError domain representing a Telepathy connection becoming disconnected. The code in a GError with this domain must be a member of TpConnectionStatusReason.

This macro expands to a function call returning a GQuark.

Since 0.7.24, this error domain is only used if a connection manager emits a TpConnectionStatusReason not known to telepathy-glib.

Since 0.7.1


tp_connection_get_detailed_error ()

const gchar *       tp_connection_get_detailed_error    (TpConnection *self,
                                                         const GHashTable **details);

If the connection has disconnected, return the D-Bus error name with which it disconnected (in particular, this is TP_ERROR_STR_CANCELLED if it was disconnected by a user request).

Otherwise, return NULL, without altering details.

self :

a connection

details :

optionally used to return a map from string to GValue, which must not be modified or destroyed by the caller. [out][allow-none][element-type utf8 GObject.Value][transfer none]

Returns :

a D-Bus error name, or NULL. [transfer none][allow-none]

Since 0.11.4


tp_connection_dup_detailed_error_vardict ()

gchar *             tp_connection_dup_detailed_error_vardict
                                                        (TpConnection *self,
                                                         GVariant **details);

If the connection has disconnected, return the D-Bus error name with which it disconnected (in particular, this is TP_ERROR_STR_CANCELLED if it was disconnected by a user request).

Otherwise, return NULL, without altering details.

self :

a connection

details :

optionally used to return a G_VARIANT_TYPE_VARDICT with details of the error. [out][allow-none][transfer full]

Returns :

a D-Bus error name, or NULL. [transfer full][allow-none]

Since 0.19.0


tp_connection_add_client_interest ()

void                tp_connection_add_client_interest   (TpConnection *self,
                                                         const gchar *interested_in);

Subscribe to any opt-in change notifications for interested_in.

For contact information, use TpContact instead, which will call this automatically.

self :

a connection

interested_in :

a string identifying an interface or part of an interface to which this connection will subscribe

Since 0.11.3


tp_connection_add_client_interest_by_id ()

void                tp_connection_add_client_interest_by_id
                                                        (TpConnection *self,
                                                         GQuark interested_in);

Subscribe to any opt-in change notifications for interested_in.

Equivalent to, but a little more efficient than, calling tp_connection_add_client_interest() for the string value of interested_in.

self :

a connection

interested_in :

a quark identifying an interface or part of an interface to which this connection will subscribe

Since 0.11.3


tp_connection_bind_connection_status_to_property ()

GBinding *          tp_connection_bind_connection_status_to_property
                                                        (TpConnection *self,
                                                         gpointer target,
                                                         const char *target_property,
                                                         gboolean invert);

Binds the :status of self to the boolean property of another object using a GBinding such that the target_property will be set to TRUE when self is connected (and invert is FALSE).

target_property will be synchronised immediately (G_BINDING_SYNC_CREATE). invert can be interpreted as analogous to G_BINDING_INVERT_BOOLEAN.

For instance, this function can be used to bind the GtkWidget:sensitive property to only make a widget sensitive when the account is connected.

See g_object_bind_property() for more information.

self :

a TpConnection

target :

the target GObject

target_property :

the property on target to bind (must be G_TYPE_BOOLEAN)

invert :

TRUE if you wish to invert the value of target_property (i.e. FALSE if connected)

Returns :

the GBinding instance representing the binding between the self and the target. The binding is released whenever the GBinding reference count reaches zero. [transfer none]

Since 0.13.16


tp_connection_get_balance ()

gboolean            tp_connection_get_balance           (TpConnection *self,
                                                         gint *balance,
                                                         guint *scale,
                                                         const gchar **currency);

If self has a valid account balance, returns TRUE and sets the variables pointed to by balance, scale and currency to the appropriate fields of the Balance.AccountBalance property.

The monetary value of the balance is expressed as a fixed-point number, balance, with a decimal scale defined by scale; for instance a balance of 1234 with scale of 2 represents a value of "12.34" in the currency represented by currency.

Requires TP_CONNECTION_FEATURE_BALANCE to be prepared.

self :

a TpConnection

balance :

a pointer to store the account balance (or NULL). [out]

scale :

a pointer to store the balance scale (or NULL). [out]

currency :

a pointer to store the balance currency (or NULL). [out][transfer none]

Returns :

TRUE if the balance is valid (and the values set), FALSE if the balance is invalid.

Since 0.15.1


tp_connection_get_balance_uri ()

const gchar *       tp_connection_get_balance_uri       (TpConnection *self);

The value of Balance.ManageCreditURI.

Requires TP_CONNECTION_FEATURE_BALANCE to be prepared.

self :

a TpConnection

Returns :

the "balance-uri" property. [transfer none]

Since 0.15.1


TP_TYPE_AVATAR_REQUIREMENTS

#define TP_TYPE_AVATAR_REQUIREMENTS (tp_avatar_requirements_get_type ())

The boxed type of a TpAvatarRequirements.

Since 0.11.4


struct TpAvatarRequirements

struct TpAvatarRequirements {
  GStrv supported_mime_types;
  guint minimum_width;
  guint minimum_height;
  guint recommended_width;
  guint recommended_height;
  guint maximum_width;
  guint maximum_height;
  guint maximum_bytes;
};

The requirements for setting an avatar on a particular protocol.

GStrv supported_mime_types;

An array of supported MIME types (e.g. "image/jpeg") Clients MAY assume that the first type in this array is preferred

guint minimum_width;

The minimum width in pixels of an avatar, which MAY be 0

guint minimum_height;

The minimum height in pixels of an avatar, which MAY be 0

guint recommended_width;

The recommended width in pixels of an avatar, or 0 if there is no preferred width.

guint recommended_height;

The recommended height in pixels of an avatar, or 0 if there is no preferred height

guint maximum_width;

The maximum width in pixels of an avatar on this protocol, or 0 if there is no limit.

guint maximum_height;

The maximum height in pixels of an avatar, or 0 if there is no limit.

guint maximum_bytes;

he maximum size in bytes of an avatar, or 0 if there is no limit.

Since 0.11.4


tp_avatar_requirements_new ()

TpAvatarRequirements * tp_avatar_requirements_new       (GStrv supported_mime_types,
                                                         guint minimum_width,
                                                         guint minimum_height,
                                                         guint recommended_width,
                                                         guint recommended_height,
                                                         guint maximum_width,
                                                         guint maximum_height,
                                                         guint maximum_bytes);

supported_mime_types :

An array of supported MIME types (e.g. "image/jpeg") Clients MAY assume that the first type in this array is preferred

minimum_width :

The minimum width in pixels of an avatar, which MAY be 0

minimum_height :

The minimum height in pixels of an avatar, which MAY be 0

recommended_width :

The recommended width in pixels of an avatar, or 0 if there is no preferred width.

recommended_height :

The recommended height in pixels of an avatar, or 0 if there is no preferred height

maximum_width :

The maximum width in pixels of an avatar on this protocol, or 0 if there is no limit.

maximum_height :

The maximum height in pixels of an avatar, or 0 if there is no limit.

maximum_bytes :

he maximum size in bytes of an avatar, or 0 if there is no limit.

Returns :

a newly allocated TpAvatarRequirements, free it with tp_avatar_requirements_destroy()

Since 0.11.4


tp_avatar_requirements_copy ()

TpAvatarRequirements * tp_avatar_requirements_copy      (const TpAvatarRequirements *self);

self :

a TpAvatarRequirements

Returns :

a newly allocated TpAvatarRequirements, free it with tp_avatar_requirements_destroy()

Since 0.11.4


tp_avatar_requirements_destroy ()

void                tp_avatar_requirements_destroy      (TpAvatarRequirements *self);

Free all memory used by the TpAvatarRequirements.

Since 0.11.4


struct TpContactInfoFieldSpec

struct TpContactInfoFieldSpec {
  gchar *name;
  GStrv parameters;
  TpContactInfoFieldFlags flags;
  guint max;
};

A struct describing a vCard field.

gchar *name;

The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".

GStrv parameters;

The set of vCard type parameters which may be set on this field. If this list is empty and the TP_CONTACT_INFO_FIELD_FLAG_PARAMETERS_EXACT flag is not set, any vCard type parameters may be used. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.

TpContactInfoFieldFlags flags;

Flags describing the behaviour of this field.

guint max;

Maximum number of instances of this field which may be set. G_MAXUINT32 is used to indicate that there is no limit.

Since 0.11.7


TP_TYPE_CONTACT_INFO_FIELD_SPEC

#define TP_TYPE_CONTACT_INFO_FIELD_SPEC (tp_contact_info_field_spec_get_type ())

The boxed type of a TpContactInfoFieldSpec.

Since 0.11.7


tp_contact_info_field_spec_copy ()

TpContactInfoFieldSpec * tp_contact_info_field_spec_copy
                                                        (const TpContactInfoFieldSpec *self);

self :

a TpContactInfoFieldSpec

Returns :

a newly allocated TpContactInfoFieldSpec, free it with tp_contact_info_field_spec_free()

Since 0.11.7


tp_contact_info_field_spec_free ()

void                tp_contact_info_field_spec_free     (TpContactInfoFieldSpec *self);

Free all memory used by the TpContactInfoFieldSpec.

Since 0.11.7


TP_TYPE_CONTACT_INFO_SPEC_LIST

#define TP_TYPE_CONTACT_INFO_SPEC_LIST (tp_contact_info_spec_list_get_type ())

The boxed type of a GList of TpContactInfoFieldSpec.

Since 0.11.7


tp_contact_info_spec_list_copy ()

GList *             tp_contact_info_spec_list_copy      (GList *list);

list :

a GList of TpContactInfoFieldSpec

Returns :

a new GList of newly allocated TpContactInfoFieldSpec, free it with tp_contact_info_spec_list_free()

Since 0.11.7


tp_contact_info_spec_list_free ()

void                tp_contact_info_spec_list_free      (GList *list);

Free all memory used by the GList and its elements.

Since 0.11.7


struct TpContactInfoField

struct TpContactInfoField {
  gchar *field_name;
  GStrv parameters;
  GStrv field_value;
};

A structure representing an information about a contact. Similar to a vCard field.

gchar *field_name;

The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".

GStrv parameters;

A list of vCard type parameters applicable to this field, with their values. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.

GStrv field_value;

For unstructured vCard fields (such as 'fn', a formatted name field), a single-element array containing the field's value. For structured fields (such as 'adr', an address field), an array corresponding to the semicolon-separated elements of the field (with empty strings for empty elements).

Since 0.11.7


TP_TYPE_CONTACT_INFO_FIELD

#define TP_TYPE_CONTACT_INFO_FIELD (tp_contact_info_field_get_type ())

The boxed type of a TpContactInfoField.

Since 0.11.7


tp_contact_info_field_new ()

TpContactInfoField * tp_contact_info_field_new          (const gchar *field_name,
                                                         GStrv parameters,
                                                         GStrv field_value);

field_name :

The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".

parameters :

A list of vCard type parameters applicable to this field, with their values. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.

field_value :

For unstructured vCard fields (such as 'fn', a formatted name field), a single-element array containing the field's value. For structured fields (such as 'adr', an address field), an array corresponding to the semicolon-separated elements of the field (with empty strings for empty elements).

Returns :

a newly allocated TpContactInfoField, free it with tp_contact_info_field_free()

Since 0.11.7


tp_contact_info_field_copy ()

TpContactInfoField * tp_contact_info_field_copy         (const TpContactInfoField *self);

self :

a TpContactInfoField

Returns :

a newly allocated TpContactInfoField, free it with tp_contact_info_field_free()

Since 0.11.7


tp_contact_info_field_free ()

void                tp_contact_info_field_free          (TpContactInfoField *self);

Free all memory used by the TpContactInfoField.

self :

a TpContactInfoField

Since 0.11.7


TP_TYPE_CONTACT_INFO_LIST

#define TP_TYPE_CONTACT_INFO_LIST (tp_contact_info_list_get_type ())

The boxed type of a GList of TpContactInfoField.

Since 0.11.7


tp_contact_info_list_copy ()

GList *             tp_contact_info_list_copy           (GList *list);

list :

a GList of TpContactInfoField

Returns :

a new GList of newly allocated TpContactInfoField, free it with tp_contact_info_list_free()

Since 0.11.7


tp_contact_info_list_free ()

void                tp_contact_info_list_free           (GList *list);

Free all memory used by the GList and its elements.

list :

a GList of TpContactInfoField

Since 0.11.7


tp_connection_get_contact_list_state ()

TpContactListState  tp_connection_get_contact_list_state
                                                        (TpConnection *self);

self :

a TpConnection

Returns :

the value of "contact-list-state" property

Since 0.15.5


tp_connection_get_contact_list_persists ()

gboolean            tp_connection_get_contact_list_persists
                                                        (TpConnection *self);

self :

a TpConnection

Returns :

the value of "contact-list-persists" property

Since 0.15.5


tp_connection_get_can_change_contact_list ()

gboolean            tp_connection_get_can_change_contact_list
                                                        (TpConnection *self);

self :

a TpConnection

Returns :

the value of "can-change-contact-list" property

Since 0.15.5


tp_connection_get_request_uses_message ()

gboolean            tp_connection_get_request_uses_message
                                                        (TpConnection *self);

self :

a TpConnection

Returns :

the value of "request-uses-message" property

Since 0.15.5


tp_connection_dup_contact_list ()

GPtrArray *         tp_connection_dup_contact_list      (TpConnection *self);

Retrieves the user's contact list. In general, blocked contacts are not included in this list. The TpContact objects returned are guaranteed to have all of the features previously passed to tp_client_factory_add_contact_features() prepared.

Before calling this method, you must first call tp_proxy_prepare_async() with the TP_CONNECTION_FEATURE_CONTACT_LIST feature, and verify that "contact-list-state" is set to TP_CONTACT_LIST_STATE_SUCCESS.

self :

a TpConnection

Returns :

a new GPtrArray of TpContact. Use g_ptr_array_unref() when done. [transfer container][type GLib.PtrArray][element-type TelepathyGLib.Contact]

Since 0.15.5


tp_connection_request_subscription_async ()

void                tp_connection_request_subscription_async
                                                        (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         const gchar *message,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Request that the given contacts allow the local user to subscribe to their presence, i.e. that their "subscribe-state" property becomes TP_SUBSCRIPTION_STATE_YES.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

self :

a TpConnection

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to whom requests are to be sent. [array length=n_contacts]

message :

an optional plain-text message from the user, to send to those contacts with the subscription request.

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_request_subscription_finish ()

gboolean            tp_connection_request_subscription_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_request_subscription_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_authorize_publication_async ()

void                tp_connection_authorize_publication_async
                                                        (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

For each of the given contacts, request that the local user's presence is sent to that contact, i.e. that their "publish-state" property becomes TP_SUBSCRIPTION_STATE_YES.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

self :

a TpConnection

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to authorize. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_authorize_publication_finish ()

gboolean            tp_connection_authorize_publication_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_authorize_publication_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_remove_contacts_async ()

void                tp_connection_remove_contacts_async (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Remove the given contacts from the contact list entirely. It is protocol-dependent whether this works, and under which circumstances.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

self :

a TpConnection

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to remove. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_remove_contacts_finish ()

gboolean            tp_connection_remove_contacts_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_remove_contacts_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_unsubscribe_async ()

void                tp_connection_unsubscribe_async     (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Attempt to set the given contacts' "subscribe-state" property to TP_SUBSCRIPTION_STATE_NO, i.e. stop receiving their presence.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

self :

a TpConnection

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to remove. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_unsubscribe_finish ()

gboolean            tp_connection_unsubscribe_finish    (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_unsubscribe_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_unpublish_async ()

void                tp_connection_unpublish_async       (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Attempt to set the given contacts' "publish-state" property to TP_SUBSCRIPTION_STATE_NO, i.e. stop sending presence to them.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

self :

a TpConnection

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to remove. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_unpublish_finish ()

gboolean            tp_connection_unpublish_finish      (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_unpublish_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_get_disjoint_groups ()

gboolean            tp_connection_get_disjoint_groups   (TpConnection *self);

self :

a TpConnection

Returns :

the value of "disjoint-groups"

Since 0.15.5


tp_connection_get_group_storage ()

TpContactMetadataStorageType tp_connection_get_group_storage
                                                        (TpConnection *self);

self :

a TpConnection

Returns :

the value of "group-storage"

Since 0.15.5


tp_connection_get_contact_groups ()

const gchar * const * tp_connection_get_contact_groups  (TpConnection *self);

self :

a TpConnection

Returns :

the value of "contact-groups". [array zero-terminated=1][transfer none]

Since 0.15.5


tp_connection_set_group_members_async ()

void                tp_connection_set_group_members_async
                                                        (TpConnection *self,
                                                         const gchar *group,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Add the given contacts to the given group (creating it if necessary), and remove all other members.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

self :

a TpConnection

group :

the group to alter.

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects members for the group. If this set is empty, this method MAY remove the group. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_set_group_members_finish ()

gboolean            tp_connection_set_group_members_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_set_group_members_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_add_to_group_async ()

void                tp_connection_add_to_group_async    (TpConnection *self,
                                                         const gchar *group,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Add the given contacts to the given group, creating it if necessary.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

self :

a TpConnection

group :

the group to alter.

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to include in the group. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_add_to_group_finish ()

gboolean            tp_connection_add_to_group_finish   (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_add_to_group_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_remove_from_group_async ()

void                tp_connection_remove_from_group_async
                                                        (TpConnection *self,
                                                         const gchar *group,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Remove the given contacts from the given group. If there are no members left in the group afterwards, the group MAY itself be removed.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

self :

a TpConnection

group :

the group to alter.

n_contacts :

The number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to remove from the group. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_remove_from_group_finish ()

gboolean            tp_connection_remove_from_group_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_remove_from_group_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_remove_group_async ()

void                tp_connection_remove_group_async    (TpConnection *self,
                                                         const gchar *group,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Remove all members from the given group, then remove the group itself.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

self :

a TpConnection

group :

the group to remove.

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_remove_group_finish ()

gboolean            tp_connection_remove_group_finish   (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_remove_group_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_rename_group_async ()

void                tp_connection_rename_group_async    (TpConnection *self,
                                                         const gchar *old_name,
                                                         const gchar *new_name,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Rename the given old_name.

On protocols where groups behave like tags, this is an API short-cut for adding all of the group's members to a group with the new name, then removing the old group.

For this to work properly self must have interface TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

self :

a TpConnection

old_name :

the group to rename

new_name :

the new name for the group

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.15.5


tp_connection_rename_group_finish ()

gboolean            tp_connection_rename_group_finish   (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_rename_group_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.15.5


tp_connection_block_contacts_async ()

void                tp_connection_block_contacts_async  (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         gboolean report_abusive,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Direct the server to block contacts.

self :

a TpConnection

n_contacts :

the number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to block. [array length=n_contacts]

report_abusive :

If TRUE, report these contacts as abusive to the server administrators as well as blocking them. See "can-report-abusive" to discover whether reporting abuse is supported. If "can-report-abusive" is FALSE, this parameter will be ignored.

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.17.0


tp_connection_block_contacts_finish ()

gboolean            tp_connection_block_contacts_finish (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_block_contacts_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.17.0


tp_connection_unblock_contacts_async ()

void                tp_connection_unblock_contacts_async
                                                        (TpConnection *self,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Direct the server to unblock contacts.

self :

a TpConnection

n_contacts :

the number of contacts in contacts (must be at least 1)

contacts :

An array of TpContact objects to block. [array length=n_contacts]

callback :

a callback to call when the operation finishes

user_data :

data to pass to callback

Since 0.17.0


tp_connection_unblock_contacts_finish ()

gboolean            tp_connection_unblock_contacts_finish
                                                        (TpConnection *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_connection_unblock_contacts_async()

self :

a TpConnection

result :

a GAsyncResult

error :

a GError to fill

Returns :

TRUE if the operation was successful, otherwise FALSE.

Since 0.17.0


tp_connection_can_report_abusive ()

gboolean            tp_connection_can_report_abusive    (TpConnection *self);

self :

a TpConnection

Returns :

the value of "can-report-abusive"

Since 0.17.0


tp_connection_get_blocked_contacts ()

GPtrArray *         tp_connection_get_blocked_contacts  (TpConnection *self);

self :

a TpConnection

Returns :

the value of "blocked-contacts". [transfer none][element-type TelepathyGLib.Contact]

Since 0.17.0


tp_connection_can_set_contact_alias ()

gboolean            tp_connection_can_set_contact_alias (TpConnection *self);

Check if the user can set aliases on his contacts. TP_CONNECTION_FEATURE_ALIASING needs to be prepared for this function to return a meaningful value.

self :

a TpConnection

Returns :

TRUE if the aliases of contacts on self may be changed by the user of the service, not just by the contacts themselves; FALSE otherwise.

Since 0.17.3

Property Details

The "balance" property

  "balance"                  gint                  : Read

The Amount field of the Balance.AccountBalance property.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_BALANCE.

See Also: tp_connection_get_balance()

Default value: 0


The "balance-currency" property

  "balance-currency"         gchar*                : Read

The Currency field of the Balance.AccountBalance property.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_BALANCE.

See Also: tp_connection_get_balance()

Default value: NULL


The "balance-scale" property

  "balance-scale"            guint                 : Read

The Scale field of the Balance.AccountBalance property.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_BALANCE.

See Also: tp_connection_get_balance()

Default value: 4294967295


The "balance-uri" property

  "balance-uri"              gchar*                : Read

The Balance.ManageCreditURI property.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_BALANCE.

Default value: NULL


The "blocked-contacts" property

  "blocked-contacts"         GPtrArray*            : Read

A GPtrArray of blocked TpContact. Changes are notified using the "blocked-contacts-changed" signal.

These TpContact objects have been prepared with the desired features. See tp_client_factory_add_contact_features() to define which features needs to be prepared on them.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_BLOCKING.

Since 0.17.0


The "can-change-contact-list" property

  "can-change-contact-list"  gboolean              : Read

If true, presence subscription and publication can be changed using the RequestSubscription, AuthorizePublication and RemoveContacts methods.

Rational: link-local XMPP, presence is implicitly published to everyone in the local subnet, so the user cannot control their presence publication.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or TP_CONNECTION_FEATURE_CONTACT_LIST.

Default value: FALSE

Since 0.15.5


The "can-report-abusive" property

  "can-report-abusive"       gboolean              : Read

If this property is TRUE, contacts may be reported as abusive to the server administrators by setting report_abusive to TRUE when calling tp_connection_block_contacts_async().

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_BLOCKING.

Default value: FALSE

Since 0.17.0


The "capabilities" property

  "capabilities"             TpCapabilities*       : Read

The TpCapabilities object representing the capabilities of this connection, or NULL if we don't know yet.

To wait for valid capability information, call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CAPABILITIES.


The "cm-name" property

  "cm-name"                  gchar*                : Read

This connection's connection manager name.

Default value: NULL

Since 0.19.3


The "contact-groups" property

  "contact-groups"           GStrv                 : Read

The names of all groups that currently exist. This may be a larger set than the union of all "contact-groups" properties, if the connection allows groups to be empty.

This property's value is not meaningful until the "contact-list-state" property has become TP_CONTACT_LIST_STATE_SUCCESS.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_GROUPS.

Since 0.15.5


The "contact-list-persists" property

  "contact-list-persists"    gboolean              : Read

If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.

If false, presence subscriptions on this connection are not stored.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or TP_CONNECTION_FEATURE_CONTACT_LIST.

Default value: FALSE

Since 0.15.5


The "contact-list-state" property

  "contact-list-state"       guint                 : Read

The progress made in retrieving the contact list.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or TP_CONNECTION_FEATURE_CONTACT_LIST.

Default value: 0

Since 0.15.5


The "disjoint-groups" property

  "disjoint-groups"          gboolean              : Read

True if each contact can be in at most one group; false if each contact can be in many groups.

This property cannot change after the connection has moved to the TP_CONNECTION_STATUS_CONNECTED state. Until then, its value is undefined, and it may change at any time, without notification.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_GROUPS.

Default value: FALSE

Since 0.15.5


The "group-storage" property

  "group-storage"            guint                 : Read

Indicates the extent to which contacts' groups can be set and stored.

This property cannot change after the connection has moved to the TP_CONNECTION_STATUS_CONNECTED state. Until then, its value is undefined, and it may change at any time, without notification.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_GROUPS.

Default value: 0

Since 0.15.5


The "protocol-name" property

  "protocol-name"            gchar*                : Read

The connection's machine-readable protocol name, such as "jabber", "msn" or "local-xmpp". Recommended names for most protocols can be found in the Telepathy D-Bus Interface Specification.

Default value: NULL

Since 0.13.16


The "request-uses-message" property

  "request-uses-message"     gboolean              : Read

If true, the Message parameter to RequestSubscription is likely to be significant, and user interfaces SHOULD prompt the user for a message to send with the request; a message such as "I would like to add you to my contact list", translated into the local user's language, might make a suitable default.

For this property to be valid, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or TP_CONNECTION_FEATURE_CONTACT_LIST.

Default value: FALSE

Since 0.15.5


The "self-contact" property

  "self-contact"             TpContact*            : Read

A TpContact representing the local user on this connection, or NULL if not yet available.

If the local user's unique identifier changes (for instance by using /nick on IRC), this property will change to a different TpContact object representing the new identifier, and "notify" will be emitted.

The TpContact object is guaranteed to have all of the features previously passed to tp_client_factory_add_contact_features() prepared.

To wait for a non-NULL self-contact (and other properties), call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONNECTED.

Since 0.13.9


The "status" property

  "status"                   guint                 : Read

This connection's status, or TP_UNKNOWN_CONNECTION_STATUS if we don't know yet.

To wait for a valid status (and other properties), call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CORE.

Since version 0.11.3, the change to status TP_CONNECTION_STATUS_CONNECTED is delayed slightly, until introspection of the connection has finished.

Default value: 4294967295


The "status-reason" property

  "status-reason"            guint                 : Read

To wait for a valid status (and other properties), call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CORE.

The reason why "status" changed to its current value, or TP_CONNECTION_STATUS_REASON_NONE_SPECIFIED if unknown. know yet.

Default value: 0

Signal Details

The "balance-changed" signal

void                user_function                      (TpConnection *self,
                                                        gint          balance,
                                                        guint         balance_scale,
                                                        gchar        *balance_currency,
                                                        gpointer      user_data)             : Has Details

Emitted when at least one of the "balance", "balance-scale" or "balance-currency" property is changed.

For this signal to be emitted, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_BALANCE.

self :

a channel

balance :

the value of the "balance" property

balance_scale :

the value of the "balance-scale" property

balance_currency :

the value of the "balance-currency" property

user_data :

user data set when the signal handler was connected.

Since 0.15.1


The "blocked-contacts-changed" signal

void                user_function                      (TpConnection *self,
                                                        GPtrArray    *added,
                                                        GPtrArray    *removed,
                                                        gpointer      user_data)      : Run Last

Notify of changes in "blocked-contacts". It is guaranteed that all contacts have desired features prepared. See tp_client_factory_add_contact_features() to define which features needs to be prepared.

This signal is also emitted for the initial set of blocked contacts once retrieved.

For this signal to be emitted, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_BLOCKING.

self :

a TpConnection

added :

a GPtrArray of TpContact which have been blocked. [type GLib.PtrArray][element-type TelepathyGLib.Contact]

removed :

a GPtrArray of TpContact which are no longer blocked. [type GLib.PtrArray][element-type TelepathyGLib.Contact]

user_data :

user data set when the signal handler was connected.

Since 0.17.0


The "contact-list-changed" signal

void                user_function                      (TpConnection *self,
                                                        GPtrArray    *added,
                                                        GPtrArray    *removed,
                                                        gpointer      user_data)      : Run Last

Notify of changes in the list of contacts as returned by tp_connection_dup_contact_list(). It is guaranteed that all contacts have desired features prepared. See tp_client_factory_add_contact_features() to define which features needs to be prepared.

This signal is also emitted for the initial set of contacts once retrieved.

For this signal to be emitted, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_LIST.

self :

a TpConnection

added :

a GPtrArray of TpContact added to contacts list. [type GLib.PtrArray][element-type TelepathyGLib.Contact]

removed :

a GPtrArray of TpContact removed from contacts list. [type GLib.PtrArray][element-type TelepathyGLib.Contact]

user_data :

user data set when the signal handler was connected.

Since 0.15.5


The "group-renamed" signal

void                user_function                      (TpConnection *self,
                                                        gchar        *old_name,
                                                        gchar        *new_name,
                                                        gpointer      user_data)      : Run Last

Emitted when a group is renamed, in protocols where this can be distinguished from group creation, removal and membership changes.

Immediately after this signal is emitted, "groups-created" signal the creation of a group with the new name, and "groups-removed" signal the removal of a group with the old name. If the group was not empty, immediately after those signals are emitted, "contact-groups-changed" signal that the members of that group were removed from the old name and added to the new name.

When this signal is emitted, "contact-groups" property is already updated.

For this signal to be emited, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_GROUPS.

self :

a TpConnection

old_name :

the old name of the group.

new_name :

the new name of the group.

user_data :

user data set when the signal handler was connected.

Since 0.15.5


The "groups-created" signal

void                user_function                      (TpConnection *self,
                                                        GStrv         added,
                                                        gpointer      user_data)      : Run Last

Emitted when new, empty groups are created. This will often be followed by "contact-groups-changed" signals that add some members. When this signal is emitted, "contact-groups" property is already updated.

For this signal to be emited, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_GROUPS.

self :

a TpConnection

added :

a GStrv with the names of the new groups.

user_data :

user data set when the signal handler was connected.

Since 0.15.5


The "groups-removed" signal

void                user_function                      (TpConnection *self,
                                                        GStrv         added,
                                                        gpointer      user_data)      : Run Last

Emitted when one or more groups are removed. If they had members at the time that they were removed, then immediately after this signal is emitted, "contact-groups-changed" signals that their members were removed. When this signal is emitted, "contact-groups" property is already updated.

For this signal to be emited, you must first call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONTACT_GROUPS.

self :

A TpConnection

added :

A GStrv with the names of the groups.

user_data :

user data set when the signal handler was connected.

Since 0.15.5

See Also

TpConnectionManager, TpChannel