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;
TpConnection *      tp_connection_new                   (TpDBusDaemon *dbus,
                                                         const gchar *bus_name,
                                                         const gchar *object_path,
                                                         GError **error);
#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
gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                         gboolean connect,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*TpConnectionWhenReadyCb)          (TpConnection *connection,
                                                         const GError *error,
                                                         gpointer user_data);
void                tp_connection_call_when_ready       (TpConnection *self,
                                                         TpConnectionWhenReadyCb callback,
                                                         gpointer user_data);
gboolean            tp_connection_is_ready              (TpConnection *self);
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_connection_manager_name
                                                        (TpConnection *self);
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);
TpHandle            tp_connection_get_self_handle       (TpConnection *self);
gboolean            tp_connection_has_immortal_handles  (TpConnection *self);
void                (*TpConnectionRequestHandlesCb)     (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *ids,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_connection_request_handles       (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         const gchar * const *ids,
                                                         TpConnectionRequestHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*TpConnectionHoldHandlesCb)        (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_connection_get_contact_attributes
                                                        (TpConnection *self,
                                                         gint timeout_ms,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *interfaces,
                                                         gboolean hold,
                                                         tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                tp_connection_get_contact_list_attributes
                                                        (TpConnection *self,
                                                         gint timeout_ms,
                                                         const gchar * const *interfaces,
                                                         gboolean hold,
                                                         tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                tp_connection_hold_handles          (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         TpConnectionHoldHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                tp_connection_unref_handles         (TpConnection *self,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles);
void                tp_connection_init_known_interfaces (void);
gint                tp_connection_presence_type_cmp_availability
                                                        (TpConnectionPresenceType p1,
                                                         TpConnectionPresenceType p2);
gboolean            tp_connection_parse_object_path     (TpConnection *self,
                                                         gchar **protocol,
                                                         gchar **cm_name);
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_get_contact_info_supported_fields
                                                        (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);

void                (*tp_cli_connection_callback_for_connect)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_connect     (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_connect callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_connect       (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_disconnect)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_disconnect  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_disconnect callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_disconnect    (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_interfaces)
                                                        (TpConnection *proxy,
                                                         const gchar **out_Interfaces,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_get_interfaces
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_interfaces callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_interfaces
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         gchar ***out_Interfaces,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_protocol)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Protocol,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_get_protocol
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_protocol callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_protocol  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         gchar **out_Protocol,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_self_handle)
                                                        (TpConnection *proxy,
                                                         guint out_Self_Handle,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_get_self_handle
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_self_handle callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_self_handle
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint *out_Self_Handle,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_get_status)
                                                        (TpConnection *proxy,
                                                         guint out_Status,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_get_status  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_status callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_get_status    (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint *out_Status,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_hold_handles)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_hold_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_hold_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_hold_handles  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_inspect_handles)
                                                        (TpConnection *proxy,
                                                         const gchar **out_Identifiers,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_inspect_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_inspect_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_inspect_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         gchar ***out_Identifiers,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_list_channels)
                                                        (TpConnection *proxy,
                                                         const GPtrArray *out_Channel_Info,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_list_channels
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_list_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_list_channels (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GPtrArray **out_Channel_Info,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_release_handles)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_release_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_release_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_release_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_request_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Object_Path,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_request_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Type,
                                                         guint in_Handle_Type,
                                                         guint in_Handle,
                                                         gboolean in_Suppress_Handler,
                                                         tp_cli_connection_callback_for_request_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_request_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Type,
                                                         guint in_Handle_Type,
                                                         guint in_Handle,
                                                         gboolean in_Suppress_Handler,
                                                         gchar **out_Object_Path,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_callback_for_request_handles)
                                                        (TpConnection *proxy,
                                                         const GArray *out_Handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_request_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const gchar **in_Identifiers,
                                                         tp_cli_connection_callback_for_request_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_cli_connection_run_request_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const gchar **in_Identifiers,
                                                         GArray **out_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_signal_callback_new_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Object_Path,
                                                         const gchar *arg_Channel_Type,
                                                         guint arg_Handle_Type,
                                                         guint arg_Handle,
                                                         gboolean arg_Suppress_Handler,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_connect_to_new_channel
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_new_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_self_handle_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Self_Handle,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_connect_to_self_handle_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_self_handle_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_self_contact_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Self_Handle,
                                                         const gchar *arg_Self_ID,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_connect_to_self_contact_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_self_contact_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_status_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Status,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_connect_to_status_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_status_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_signal_callback_connection_error)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Error,
                                                         GHashTable *arg_Details,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_connect_to_connection_error
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_connection_error callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxyPendingCall * tp_cli_connection_call_add_client_interest
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar **in_Tokens,
                                                         tp_cli_connection_callback_for_add_client_interest callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_call_remove_client_interest
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar **in_Tokens,
                                                         tp_cli_connection_callback_for_remove_client_interest callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_connection_callback_for_add_client_interest)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_callback_for_remove_client_interest)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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
  "connection-manager-name"  gchar*                : Read
  "connection-ready"         gboolean              : 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
  "self-handle"              guint                 : 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_new ()

TpConnection *      tp_connection_new                   (TpDBusDaemon *dbus,
                                                         const gchar *bus_name,
                                                         const gchar *object_path,
                                                         GError **error);

Warning

tp_connection_new is deprecated and should not be used in newly-written code. Use tp_simple_client_factory_ensure_connection() instead.

dbus :

a D-Bus daemon; may not be NULL

bus_name :

the well-known or unique name of the connection process; if well-known, this function will make a blocking call to the bus daemon to resolve the unique name. May be NULL if object_path is not, in which case a well-known name will be derived from object_path. [allow-none]

object_path :

the object path of the connection process. May be NULL if bus_name is a well-known name, in which case the object path will be derived from bus_name. [allow-none]

error :

used to indicate the error if NULL is returned

Returns :

a new connection proxy, or NULL if unique-name resolution fails or on invalid arguments

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

Unlike the older "connection-ready" mechanism, 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. TP_CONNECTION_FEATURE_CONNECTED is the closest equivalent of "connection-ready".

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_simple_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_run_until_ready ()

gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                         gboolean connect,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_connection_run_until_ready has been deprecated since version 0.11.0 and should not be used in newly-written code. Use tp_proxy_prepare_async() and re-enter the main loop yourself, or restructure your program in such a way as to avoid re-entering the main loop.

If self is connected and ready for use, return immediately. Otherwise, call Connect() (unless connect is FALSE) and re-enter the main loop until the connection becomes invalid, the connection connects successfully and is introspected, or the main loop stored via loop is cancelled.

self :

a connection

connect :

if TRUE, call Connect() if it appears to be necessary; if FALSE, rely on Connect() to be called by another client

error :

if not NULL and FALSE is returned, used to raise an error

loop :

if not NULL, a GMainLoop is placed here while it is being run (so calling code can call g_main_loop_quit() to abort), and NULL is placed here after the loop has been run

Returns :

TRUE if the connection is now connected and ready for use, FALSE if the connection has become invalid.

Since 0.7.1


TpConnectionWhenReadyCb ()

void                (*TpConnectionWhenReadyCb)          (TpConnection *connection,
                                                         const GError *error,
                                                         gpointer user_data);

Warning

TpConnectionWhenReadyCb is deprecated and should not be used in newly-written code. 0.17.6

Signature of a callback passed to tp_connection_call_when_ready(), which will be called exactly once, when the connection becomes ready or invalid (whichever happens first)

connection :

the connection (which may be in the middle of being disposed, if error is non-NULL, error->domain is TP_DBUS_ERRORS and error->code is TP_DBUS_ERROR_PROXY_UNREFERENCED)

error :

NULL if the connection is ready for use, or the error with which it was invalidated if it is now invalid

user_data :

whatever was passed to tp_connection_call_when_ready()

tp_connection_call_when_ready ()

void                tp_connection_call_when_ready       (TpConnection *self,
                                                         TpConnectionWhenReadyCb callback,
                                                         gpointer user_data);

Warning

tp_connection_call_when_ready has been deprecated since version 0.17.6 and should not be used in newly-written code. Use tp_proxy_prepare_async()

If self is ready for use or has been invalidated, call callback immediately, then return. Otherwise, arrange for callback to be called when self either becomes ready for use or becomes invalid.

Note that if the connection is not in state CONNECTED, the callback will not be called until the connection either goes to state CONNECTED or is invalidated (e.g. by going to state DISCONNECTED or by becoming unreferenced). In particular, this method does not call Connect(). Call tp_cli_connection_call_connect() too, if you want to do that.

self :

a connection

callback :

called when the connection becomes ready or invalidated, whichever happens first

user_data :

arbitrary user-supplied data passed to the callback

Since 0.7.7


tp_connection_is_ready ()

gboolean            tp_connection_is_ready              (TpConnection *self);

Warning

tp_connection_is_ready has been deprecated since version 0.17.6 and should not be used in newly-written code. use tp_proxy_is_prepared() with TP_CONNECTION_FEATURE_CONNECTED

Returns the same thing as the "connection-ready" property.

self :

a connection

Returns :

TRUE if introspection has completed

Since 0.7.17


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

const gchar *       tp_connection_get_connection_manager_name
                                                        (TpConnection *self);

Warning

tp_connection_get_connection_manager_name is deprecated and should not be used in newly-written code. Use tp_connection_get_cm_name() instead.

self :

a TpConnection

Returns :

the same as the "connection-manager-name" property

Since 0.13.16


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

TpHandle            tp_connection_get_self_handle       (TpConnection *self);

Warning

tp_connection_get_self_handle is deprecated and should not be used in newly-written code. Use tp_connection_get_self_contact() instead.

Return the TP_HANDLE_TYPE_CONTACT handle of the local user on this connection, or 0 if the self-handle is not known yet or the connection has become invalid (the TpProxy::invalidated signal).

The returned handle is not necessarily valid forever (the notify::self-handle signal will be emitted if it changes, which can happen on protocols such as IRC). Construct a TpContact object if you want to track the local user's identifier in the protocol, or other information like their presence status, over time.

self :

a connection

Returns :

the value of the TpConnection:self-handle property

Since 0.7.26


tp_connection_has_immortal_handles ()

gboolean            tp_connection_has_immortal_handles  (TpConnection *self);

Return TRUE if this connection is known to not destroy handles (TpHandle) until it disconnects.

On such connections, if you know that a handle maps to a particular identifier now, then you can rely on that handle mapping to that identifier for the whole lifetime of the connection.

self :

a connection

Returns :

TRUE if handles last as long as the connection itself

TpConnectionRequestHandlesCb ()

void                (*TpConnectionRequestHandlesCb)     (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *ids,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Warning

TpConnectionRequestHandlesCb is deprecated and should not be used in newly-written code. See tp_connection_request_handles().

Signature of the callback called when tp_connection_request_handles() succeeds or fails.

On success, the caller has a reference to each handle in handles.

Since telepathy-glib version 0.13.8, the handles will remain valid until connection becomes invalid (signalled by "invalidated"). In earlier versions, they could be released with tp_connection_unref_handles().

For convenience, the handle type and IDs requested by the caller are passed through to this callback, so the caller does not have to include them in user_data.

connection :

the connection

handle_type :

the handle type that was passed to tp_connection_request_handles()

n_handles :

the number of IDs that were passed to tp_connection_request_handles() on success, or 0 on failure

handles :

the n_handles handles corresponding to ids, in the same order, or NULL on failure. [element-type uint][array length=n_handles]

ids :

a copy of the array of n_handles IDs that was passed to tp_connection_request_handles() on success, or NULL on failure. [element-type utf8][array length=n_handles]

error :

NULL on success, or an error on failure

user_data :

the same arbitrary pointer that was passed to tp_connection_request_handles()

weak_object :

the same object that was passed to tp_connection_request_handles()

tp_connection_request_handles ()

void                tp_connection_request_handles       (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         const gchar * const *ids,
                                                         TpConnectionRequestHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_connection_request_handles is deprecated and should not be used in newly-written code. If handle_type is TP_HANDLE_TYPE_CONTACT, use tp_connection_dup_contact_by_id_async() instead. For channel requests, use tp_account_channel_request_set_target_id() instead.

Request the handles corresponding to the given identifiers, and if they are valid, hold (ensure a reference to) the corresponding handles.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

self :

a connection

timeout_ms :

the timeout in milliseconds, or -1 to use the default

handle_type :

the handle type

ids :

an array of string identifiers for which handles are required, terminated by NULL (must not be NULL or empty). [array zero-terminated=1]

callback :

called on success or failure (unless weak_object has become unreferenced)

user_data :

arbitrary user-supplied data

destroy :

called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)

weak_object :

if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

TpConnectionHoldHandlesCb ()

void                (*TpConnectionHoldHandlesCb)        (TpConnection *connection,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Warning

TpConnectionHoldHandlesCb is deprecated and should not be used in newly-written code. See tp_connection_hold_handles().

Signature of the callback called when tp_connection_hold_handles() succeeds or fails.

On success, the caller has a reference to each handle in handles.

Since telepathy-glib version 0.13.8, the handles will remain valid until connection becomes invalid (signalled by "invalidated"). In earlier versions, they could be released with tp_connection_unref_handles().

For convenience, the handle type and handles requested by the caller are passed through to this callback on success, so the caller does not have to include them in user_data.

connection :

the connection

handle_type :

the handle type that was passed to tp_connection_hold_handles()

n_handles :

the number of handles that were passed to tp_connection_hold_handles() on success, or 0 on failure

handles :

a copy of the array of n_handles handles that was passed to tp_connection_hold_handles() on success, or NULL on failure

error :

NULL on success, or an error on failure

user_data :

the same arbitrary pointer that was passed to tp_connection_hold_handles()

weak_object :

the same object that was passed to tp_connection_hold_handles()

tp_connection_get_contact_attributes ()

void                tp_connection_get_contact_attributes
                                                        (TpConnection *self,
                                                         gint timeout_ms,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         const gchar * const *interfaces,
                                                         gboolean hold,
                                                         tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_connection_get_contact_attributes is deprecated and should not be used in newly-written code. Use tp_simple_client_factory_ensure_contact() instead.

Return (via a callback) any number of attributes of the given handles.

Since telepathy-glib version 0.13.8, the handles will remain valid until connection becomes invalid (signalled by "invalidated"). In earlier versions, if hold was TRUE, the callback would hold a reference to them which could be released with tp_connection_unref_handles().

This is a thin wrapper around the GetContactAttributes D-Bus method, and should be used in preference to tp_cli_connection_interface_contacts_call_get_contact_attributes(); mixing this function, tp_connection_hold_handles(), tp_connection_unref_handles(), and TpContact with direct use of the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods is unwise, as TpConnection and TpContact perform client-side reference counting of handles. The TpContact API provides a higher-level abstraction which should usually be used instead.

callback will later be called with the attributes of those of the given handles that were valid. Invalid handles are simply omitted from the parameter to the callback.

If hold is TRUE, the callback is given one reference to each handle that appears as a key in the callback's attributes parameter.

self :

a connection

timeout_ms :

the timeout in milliseconds, or -1 to use the default

n_handles :

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

handles :

an array of handles. [array length=n_handles]

interfaces :

a GStrv of interfaces

hold :

if TRUE, the callback will hold one reference to each valid handle

callback :

called on success or failure (unless weak_object has become unreferenced). [type GObject.Callback]

user_data :

arbitrary user-supplied data

destroy :

called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)

weak_object :

if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

tp_connection_get_contact_list_attributes ()

void                tp_connection_get_contact_list_attributes
                                                        (TpConnection *self,
                                                         gint timeout_ms,
                                                         const gchar * const *interfaces,
                                                         gboolean hold,
                                                         tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_connection_get_contact_list_attributes is deprecated and should not be used in newly-written code. Use tp_connection_dup_contact_list() instead.

Return (via a callback) the contacts on the contact list and any number of their attributes.

Since telepathy-glib version 0.13.8, the handles will remain valid until connection becomes invalid (signalled by "invalidated"). In earlier versions, if hold was TRUE, the callback would hold a reference to them which could be released with tp_connection_unref_handles().

This is a thin wrapper around the RequestContactList D-Bus method, and should be used in preference to lower-level functions; it is similar to tp_connection_get_contact_attributes().

The TpContact API provides a higher-level abstraction which should usually be used instead.

If hold is TRUE, the callback is given a reference to each handle that appears as a key in the callback's attributes parameter.

self :

a connection

timeout_ms :

the timeout in milliseconds (using a large timeout is recommended)

interfaces :

a GStrv of interfaces

hold :

if TRUE, the callback will hold one reference to each handle it receives

callback :

called on success or failure (unless weak_object has become unreferenced). [type GObject.Callback]

user_data :

arbitrary user-supplied data

destroy :

called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)

weak_object :

if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

tp_connection_hold_handles ()

void                tp_connection_hold_handles          (TpConnection *self,
                                                         gint timeout_ms,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles,
                                                         TpConnectionHoldHandlesCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_connection_hold_handles is deprecated and should not be used in newly-written code. Holding handles is not needed with Connection Managers having immortal handles (any Connection Manager using telepathy-glib >= 0.13.8). Other Connection Managers are considered deprecated, clients wanting to still support them should continue using this deprecated function.

Hold (ensure a reference to) the given handles, if they are valid.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

This function, along with tp_connection_unref_handles(), tp_connection_get_contact_attributes() and TpContact, keeps a client-side reference count of handles; you should not use the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods directly as well as these functions.

self :

a connection

timeout_ms :

the timeout in milliseconds, or -1 to use the default

handle_type :

the handle type

n_handles :

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

handles :

an array of handles. [array length=n_handles]

callback :

called on success or failure (unless weak_object has become unreferenced)

user_data :

arbitrary user-supplied data

destroy :

called to destroy user_data after calling callback, or when weak_object becomes unreferenced (whichever occurs sooner)

weak_object :

if not NULL, an object to be weakly referenced: if it is destroyed, callback will not be called

tp_connection_unref_handles ()

void                tp_connection_unref_handles         (TpConnection *self,
                                                         TpHandleType handle_type,
                                                         guint n_handles,
                                                         const TpHandle *handles);

Warning

tp_connection_unref_handles is deprecated and should not be used in newly-written code. This is no-op so can be safely removed.

Do nothing. In versions of telepathy-glib prior to 0.13.8, this released a reference to the handles in handles.

self :

a connection

handle_type :

a handle type

n_handles :

the number of handles in handles

handles :

an array of n_handles handles. [array length=n_handles]

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

gboolean            tp_connection_parse_object_path     (TpConnection *self,
                                                         gchar **protocol,
                                                         gchar **cm_name);

Warning

tp_connection_parse_object_path is deprecated and should not be used in newly-written code. Use tp_connection_get_protocol_name() and tp_connection_get_connection_manager_name() instead.

If the object path of connection is in the correct form, set protocol and cm_name, return TRUE. Otherwise leave them unchanged and return FALSE.

self :

a connection

protocol :

If not NULL, used to return the protocol of the connection. [out][transfer full]

cm_name :

If not NULL, used to return the connection manager name of the connection. [out][transfer full]

Returns :

TRUE if the object path was correctly parsed, FALSE otherwise.

Since 0.7.27


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

GList *             tp_connection_get_contact_info_supported_fields
                                                        (TpConnection *self);

Warning

tp_connection_get_contact_info_supported_fields is deprecated and should not be used in newly-written code. Since 0.19.9. New code should use tp_connection_dup_contact_info_supported_fields() instead.

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

Note that the TpContactInfoFieldSpecs in the returned GList are not dupped before returning from this function. One could copy every item in the list using tp_contact_info_field_spec_copy().

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

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.

list :

a GList of TpContactInfoFieldSpec

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


tp_cli_connection_callback_for_connect ()

void                (*tp_cli_connection_callback_for_connect)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a Connect method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_connect ()

TpProxyPendingCall * tp_cli_connection_call_connect     (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_connect callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Connect method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the connection be established. This will be done asynchronously and errors will be returned by emitting <tp:member-ref>StatusChanged</tp:member-ref> signals.</p> <p>Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_connect ()

gboolean            tp_cli_connection_run_connect       (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_connect is deprecated and should not be used in newly-written code.

Call the method Connect and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the connection be established. This will be done asynchronously and errors will be returned by emitting <tp:member-ref>StatusChanged</tp:member-ref> signals.</p> <p>Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_disconnect ()

void                (*tp_cli_connection_callback_for_disconnect)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a Disconnect method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_disconnect ()

TpProxyPendingCall * tp_cli_connection_call_disconnect  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_disconnect callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a Disconnect method call.

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_disconnect ()

gboolean            tp_cli_connection_run_disconnect    (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_disconnect is deprecated and should not be used in newly-written code.

Call the method Disconnect and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_get_interfaces ()

void                (*tp_cli_connection_callback_for_get_interfaces)
                                                        (TpConnection *proxy,
                                                         const gchar **out_Interfaces,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a GetInterfaces method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Interfaces :

Used to return an 'out' argument if error is NULL: The value of the <tp:member-ref>Interfaces</tp:member-ref> property

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_get_interfaces ()

TpProxyPendingCall * tp_cli_connection_call_get_interfaces
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_interfaces callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a GetInterfaces method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Returns the set of optional interfaces supported by this connection. See <tp:member-ref>Interfaces</tp:member-ref> for more details.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_get_interfaces ()

gboolean            tp_cli_connection_run_get_interfaces
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         gchar ***out_Interfaces,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_get_interfaces is deprecated and should not be used in newly-written code.

Call the method GetInterfaces and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Returns the set of optional interfaces supported by this connection. See <tp:member-ref>Interfaces</tp:member-ref> for more details.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

out_Interfaces :

Used to return an 'out' argument if TRUE is returned: The value of the <tp:member-ref>Interfaces</tp:member-ref> property

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_get_protocol ()

void                (*tp_cli_connection_callback_for_get_protocol)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Protocol,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a GetProtocol method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Protocol :

Used to return an 'out' argument if error is NULL: A string identifier for the protocol

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_get_protocol ()

TpProxyPendingCall * tp_cli_connection_call_get_protocol
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_protocol callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a GetProtocol method call.

Get the protocol this connection is using.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_get_protocol ()

gboolean            tp_cli_connection_run_get_protocol  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         gchar **out_Protocol,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_get_protocol is deprecated and should not be used in newly-written code.

Call the method GetProtocol and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Get the protocol this connection is using.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

out_Protocol :

Used to return an 'out' argument if TRUE is returned: A string identifier for the protocol

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_get_self_handle ()

void                (*tp_cli_connection_callback_for_get_self_handle)
                                                        (TpConnection *proxy,
                                                         guint out_Self_Handle,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Warning

tp_cli_connection_callback_for_get_self_handle is deprecated and should not be used in newly-written code. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

Signature of the callback called when a GetSelfHandle method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Self_Handle :

Used to return an 'out' argument if error is NULL: The value of the <tp:member-ref>SelfHandle</tp:member-ref> property (TpContactHandle)

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_get_self_handle ()

TpProxyPendingCall * tp_cli_connection_call_get_self_handle
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_self_handle callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_cli_connection_call_get_self_handle is deprecated and should not be used in newly-written code. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

Start a GetSelfHandle method call.

Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged signal.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_get_self_handle ()

gboolean            tp_cli_connection_run_get_self_handle
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint *out_Self_Handle,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_get_self_handle is deprecated and should not be used in newly-written code. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

Call the method GetSelfHandle and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged signal.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

out_Self_Handle :

Used to return an 'out' argument if TRUE is returned: The value of the <tp:member-ref>SelfHandle</tp:member-ref> property

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_get_status ()

void                (*tp_cli_connection_callback_for_get_status)
                                                        (TpConnection *proxy,
                                                         guint out_Status,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a GetStatus method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Status :

Used to return an 'out' argument if error is NULL: The value of the <tp:member-ref>Status</tp:member-ref> property (TpConnectionStatus)

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_get_status ()

TpProxyPendingCall * tp_cli_connection_call_get_status  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_get_status callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a GetStatus method call.

Get the current status as defined in the <tp:member-ref>StatusChanged</tp:member-ref> signal.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_get_status ()

gboolean            tp_cli_connection_run_get_status    (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint *out_Status,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_get_status is deprecated and should not be used in newly-written code.

Call the method GetStatus and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Get the current status as defined in the <tp:member-ref>StatusChanged</tp:member-ref> signal.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

out_Status :

Used to return an 'out' argument if TRUE is returned: The value of the <tp:member-ref>Status</tp:member-ref> property

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_hold_handles ()

void                (*tp_cli_connection_callback_for_hold_handles)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a HoldHandles method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_hold_handles ()

TpProxyPendingCall * tp_cli_connection_call_hold_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_hold_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a HoldHandles method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method notifies the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the <tp:member-ref>RequestHandles</tp:member-ref> method. For example, a handle observed in an emitted signal, or displayed somewhere in the UI that is not associated with a channel. The connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the <tp:member-ref>ReleaseHandles</tp:member-ref> method is called, or the clients disappear from the bus.</p> <p>Note that HoldHandles is idempotent - calling it multiple times is equivalent to calling it once. If a handle is &quot;referenced&quot; by several components which share a D-Bus unique name, the client should perform reference counting internally, and only call ReleaseHandles when none of the cooperating components need the handle any longer.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Handle_Type :

Used to pass an 'in' argument: The type of handle to be held (TpHandleType)

in_Handles :

Used to pass an 'in' argument: A array of integer handles to hold

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_hold_handles ()

gboolean            tp_cli_connection_run_hold_handles  (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_hold_handles is deprecated and should not be used in newly-written code.

Call the method HoldHandles and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method notifies the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the <tp:member-ref>RequestHandles</tp:member-ref> method. For example, a handle observed in an emitted signal, or displayed somewhere in the UI that is not associated with a channel. The connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the <tp:member-ref>ReleaseHandles</tp:member-ref> method is called, or the clients disappear from the bus.</p> <p>Note that HoldHandles is idempotent - calling it multiple times is equivalent to calling it once. If a handle is &quot;referenced&quot; by several components which share a D-Bus unique name, the client should perform reference counting internally, and only call ReleaseHandles when none of the cooperating components need the handle any longer.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Handle_Type :

Used to pass an 'in' argument: The type of handle to be held (TpHandleType)

in_Handles :

Used to pass an 'in' argument: A array of integer handles to hold

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_inspect_handles ()

void                (*tp_cli_connection_callback_for_inspect_handles)
                                                        (TpConnection *proxy,
                                                         const gchar **out_Identifiers,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a InspectHandles method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Identifiers :

Used to return an 'out' argument if error is NULL: An array of identifiers corresponding to the given handles, in the same order.

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_inspect_handles ()

TpProxyPendingCall * tp_cli_connection_call_inspect_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_inspect_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a InspectHandles method call.

Return a string representation for a number of handles of a given type.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Handle_Type :

Used to pass an 'in' argument: The type of handle to be inspected (TpHandleType)

in_Handles :

Used to pass an 'in' argument: An array of integer handles of this type

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_inspect_handles ()

gboolean            tp_cli_connection_run_inspect_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         gchar ***out_Identifiers,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_inspect_handles is deprecated and should not be used in newly-written code.

Call the method InspectHandles and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Return a string representation for a number of handles of a given type.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Handle_Type :

Used to pass an 'in' argument: The type of handle to be inspected (TpHandleType)

in_Handles :

Used to pass an 'in' argument: An array of integer handles of this type

out_Identifiers :

Used to return an 'out' argument if TRUE is returned: An array of identifiers corresponding to the given handles, in the same order.

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_list_channels ()

void                (*tp_cli_connection_callback_for_list_channels)
                                                        (TpConnection *proxy,
                                                         const GPtrArray *out_Channel_Info,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Warning

tp_cli_connection_callback_for_list_channels is deprecated and should not be used in newly-written code. Use the Requests.Channels property instead.

Signature of the callback called when a ListChannels method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Channel_Info :

Used to return an 'out' argument if error is NULL: An array of structs representing channels.

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_list_channels ()

TpProxyPendingCall * tp_cli_connection_call_list_channels
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_callback_for_list_channels callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_cli_connection_call_list_channels is deprecated and should not be used in newly-written code. Use the Requests.Channels property instead.

Start a ListChannels method call.

List all the channels which currently exist on this connection.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_list_channels ()

gboolean            tp_cli_connection_run_list_channels (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         GPtrArray **out_Channel_Info,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_list_channels is deprecated and should not be used in newly-written code. Use the Requests.Channels property instead.

Call the method ListChannels and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

List all the channels which currently exist on this connection.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

out_Channel_Info :

Used to return an 'out' argument if TRUE is returned: An array of structs representing channels.

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_release_handles ()

void                (*tp_cli_connection_callback_for_release_handles)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a ReleaseHandles method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_release_handles ()

TpProxyPendingCall * tp_cli_connection_call_release_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         tp_cli_connection_callback_for_release_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a ReleaseHandles method call.

<p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method explicitly notifies the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Handle_Type :

Used to pass an 'in' argument: An integer handle type (as defined in RequestHandle) (TpHandleType)

in_Handles :

Used to pass an 'in' argument: An array of integer handles being held by the client

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_release_handles ()

gboolean            tp_cli_connection_run_release_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const GArray *in_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_release_handles is deprecated and should not be used in newly-written code.

Call the method ReleaseHandles and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method explicitly notifies the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Handle_Type :

Used to pass an 'in' argument: An integer handle type (as defined in RequestHandle) (TpHandleType)

in_Handles :

Used to pass an 'in' argument: An array of integer handles being held by the client

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_request_channel ()

void                (*tp_cli_connection_callback_for_request_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Object_Path,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Warning

tp_cli_connection_callback_for_request_channel is deprecated and should not be used in newly-written code. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

Signature of the callback called when a RequestChannel method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Object_Path :

Used to return an 'out' argument if error is NULL: The D-Bus object path for the channel created or retrieved

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_request_channel ()

TpProxyPendingCall * tp_cli_connection_call_request_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Type,
                                                         guint in_Handle_Type,
                                                         guint in_Handle,
                                                         gboolean in_Suppress_Handler,
                                                         tp_cli_connection_callback_for_request_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Warning

tp_cli_connection_call_request_channel is deprecated and should not be used in newly-written code. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

Start a RequestChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given handle_type and handle. The handle_type and handle may both be zero to request the creation of a new, empty channel, which may or may not be possible, depending on the protocol and channel type.</p> <p>On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).</p> <p>If a new, empty channel is requested, on success the returned channel will always be an &quot;anonymous&quot; channel for which the type and handle are both zero.</p> <p>If a channel to a contact, room etc. is requested, on success, the returned channel may either be a new or existing channel to the requested entity (i.e. its <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> properties are the requested handle type and handle), or a newly created &quot;anonymous&quot; channel associated with the requested handle in some implementation-specific way.</p> <p>For example, for a contact handle, the returned channel might be &quot;anonymous&quot;, but implement the groups interface and have the requested contact already present among the members.</p> <p>If the request cannot be satisfied, an error is raised and no channel is created.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Type :

Used to pass an 'in' argument: A D-Bus interface name representing base channel type

in_Handle_Type :

Used to pass an 'in' argument: An integer representing the handle type, or Handle_Type_None if no handle is specified (TpHandleType)

in_Handle :

Used to pass an 'in' argument: A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is Handle_Type_None (TpHandle)

in_Suppress_Handler :

Used to pass an 'in' argument: <p>Clients SHOULD always set this to true.</p> <tp:rationale> <p>The historical meaning was that clients that did not intend to take responsibility for displaying the channel to the user could set this to FALSE, in which case the channel dispatcher would launch an appropriate channel handler.</p> <p>However, clients whose functionality relies on having a working channel dispatcher should obtain that functionality by calling methods on the channel dispatcher, so that they will get an appropriate error if the channel dispatcher is missing or not working.</p> <p>The channel dispatcher itself should set this to true too, so that it will ignore the <tp:member-ref>NewChannel</tp:member-ref> signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler.</p> <p>So, there is no sensible use-case for setting this to false, and setting it to false can result in unhandled channels (in the case where clients assume that a channel dispatcher is present, but it isn't).</p> </tp:rationale>

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_request_channel ()

gboolean            tp_cli_connection_run_request_channel
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Type,
                                                         guint in_Handle_Type,
                                                         guint in_Handle,
                                                         gboolean in_Suppress_Handler,
                                                         gchar **out_Object_Path,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_request_channel is deprecated and should not be used in newly-written code. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

Call the method RequestChannel and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given handle_type and handle. The handle_type and handle may both be zero to request the creation of a new, empty channel, which may or may not be possible, depending on the protocol and channel type.</p> <p>On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).</p> <p>If a new, empty channel is requested, on success the returned channel will always be an &quot;anonymous&quot; channel for which the type and handle are both zero.</p> <p>If a channel to a contact, room etc. is requested, on success, the returned channel may either be a new or existing channel to the requested entity (i.e. its <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> properties are the requested handle type and handle), or a newly created &quot;anonymous&quot; channel associated with the requested handle in some implementation-specific way.</p> <p>For example, for a contact handle, the returned channel might be &quot;anonymous&quot;, but implement the groups interface and have the requested contact already present among the members.</p> <p>If the request cannot be satisfied, an error is raised and no channel is created.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Type :

Used to pass an 'in' argument: A D-Bus interface name representing base channel type

in_Handle_Type :

Used to pass an 'in' argument: An integer representing the handle type, or Handle_Type_None if no handle is specified (TpHandleType)

in_Handle :

Used to pass an 'in' argument: A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is Handle_Type_None (TpHandle)

in_Suppress_Handler :

Used to pass an 'in' argument: <p>Clients SHOULD always set this to true.</p> <tp:rationale> <p>The historical meaning was that clients that did not intend to take responsibility for displaying the channel to the user could set this to FALSE, in which case the channel dispatcher would launch an appropriate channel handler.</p> <p>However, clients whose functionality relies on having a working channel dispatcher should obtain that functionality by calling methods on the channel dispatcher, so that they will get an appropriate error if the channel dispatcher is missing or not working.</p> <p>The channel dispatcher itself should set this to true too, so that it will ignore the <tp:member-ref>NewChannel</tp:member-ref> signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler.</p> <p>So, there is no sensible use-case for setting this to false, and setting it to false can result in unhandled channels (in the case where clients assume that a channel dispatcher is present, but it isn't).</p> </tp:rationale>

out_Object_Path :

Used to return an 'out' argument if TRUE is returned: The D-Bus object path for the channel created or retrieved

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_callback_for_request_handles ()

void                (*tp_cli_connection_callback_for_request_handles)
                                                        (TpConnection *proxy,
                                                         const GArray *out_Handles,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a RequestHandles method call succeeds or fails.

proxy :

the proxy on which the call was made

out_Handles :

Used to return an 'out' argument if error is NULL: An array of integer handle numbers in the same order as the given identifiers.

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_call_request_handles ()

TpProxyPendingCall * tp_cli_connection_call_request_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const gchar **in_Identifiers,
                                                         tp_cli_connection_callback_for_request_handles callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a RequestHandles method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service.</p> <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, the handles remain valid until the connection disconnects.</p> <p>The implementation of this method in older connection managers must record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the <tp:member-ref>ReleaseHandles</tp:member-ref> method. Where the identifier refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager.</p>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Handle_Type :

Used to pass an 'in' argument: The type of handle required (TpHandleType)

in_Identifiers :

Used to pass an 'in' argument: An array of identifiers of entities to request handles for

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_run_request_handles ()

gboolean            tp_cli_connection_run_request_handles
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         guint in_Handle_Type,
                                                         const gchar **in_Identifiers,
                                                         GArray **out_Handles,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_connection_run_request_handles is deprecated and should not be used in newly-written code.

Call the method RequestHandles and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service.</p> <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, the handles remain valid until the connection disconnects.</p> <p>The implementation of this method in older connection managers must record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the <tp:member-ref>ReleaseHandles</tp:member-ref> method. Where the identifier refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Handle_Type :

Used to pass an 'in' argument: The type of handle required (TpHandleType)

in_Identifiers :

Used to pass an 'in' argument: An array of identifiers of entities to request handles for

out_Handles :

Used to return an 'out' argument if TRUE is returned: An array of integer handle numbers in the same order as the given identifiers.

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_signal_callback_new_channel ()

void                (*tp_cli_connection_signal_callback_new_channel)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Object_Path,
                                                         const gchar *arg_Channel_Type,
                                                         guint arg_Handle_Type,
                                                         guint arg_Handle,
                                                         gboolean arg_Suppress_Handler,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal NewChannel.

proxy :

The proxy on which tp_cli_connection_connect_to_new_channel() was called

arg_Object_Path :

A D-Bus object path for the channel object on this service

arg_Channel_Type :

A D-Bus interface name representing the channel type

arg_Handle_Type :

An integer representing the type of handle this channel communicates with, or Handle_Type_None if no handle is specified (TpHandleType)

arg_Handle :

A handle indicating the specific contact, room or list this channel communicates with, or zero if no handle is specified (TpHandle)

arg_Suppress_Handler :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, the channel was requested by a client that intends to present it to the user itself (i.e. it passed suppress_handler=TRUE to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no other handler should be launched. Clients MAY assume that channels where this is true were created by a user request.</p> <p>If false, either the channel was created due to incoming information from the service, or the channel was requested by a local client that does not intend to handle the channel itself (this usage is deprecated).</p> <p>Clients MUST NOT assume that only incoming channels will have this flag set to false.</p>

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_connection_connect_to_new_channel ()

TpProxySignalConnection * tp_cli_connection_connect_to_new_channel
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_new_channel callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal NewChannel.

Emitted when a new Channel object is created, either through user request or incoming information from the service.

proxy :

A TpConnection or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_signal_callback_self_handle_changed ()

void                (*tp_cli_connection_signal_callback_self_handle_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Self_Handle,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal SelfHandleChanged.

proxy :

The proxy on which tp_cli_connection_connect_to_self_handle_changed() was called

arg_Self_Handle :

The new value of the SelfHandle property. (TpContactHandle)

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_connection_connect_to_self_handle_changed ()

TpProxySignalConnection * tp_cli_connection_connect_to_self_handle_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_self_handle_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal SelfHandleChanged.

Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted.

proxy :

A TpConnection or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_signal_callback_self_contact_changed ()

void                (*tp_cli_connection_signal_callback_self_contact_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Self_Handle,
                                                         const gchar *arg_Self_ID,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal SelfContactChanged.

proxy :

The proxy on which tp_cli_connection_connect_to_self_contact_changed() was called

arg_Self_Handle :

The new value of the SelfHandle property. (TpContactHandle)

arg_Self_ID :

The new value of the SelfID property.

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_connection_connect_to_self_contact_changed ()

TpProxySignalConnection * tp_cli_connection_connect_to_self_contact_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_self_contact_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal SelfContactChanged.

Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> and <tp:member-ref>SelfID</tp:member-ref> property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted.

proxy :

A TpConnection or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_signal_callback_status_changed ()

void                (*tp_cli_connection_signal_callback_status_changed)
                                                        (TpConnection *proxy,
                                                         guint arg_Status,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal StatusChanged.

proxy :

The proxy on which tp_cli_connection_connect_to_status_changed() was called

arg_Status :

An integer indicating the new status, as defined by ConnectionStatus (TpConnectionStatus)

arg_Reason :

An integer indicating the reason for the status change, as defined by ConnectionStatusReason (TpConnectionStatusReason)

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_connection_connect_to_status_changed ()

TpProxySignalConnection * tp_cli_connection_connect_to_status_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_status_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal StatusChanged.

Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason.

proxy :

A TpConnection or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_signal_callback_connection_error ()

void                (*tp_cli_connection_signal_callback_connection_error)
                                                        (TpConnection *proxy,
                                                         const gchar *arg_Error,
                                                         GHashTable *arg_Details,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal ConnectionError.

proxy :

The proxy on which tp_cli_connection_connect_to_connection_error() was called

arg_Error :

The name of a D-Bus error describing the error that occurred, which may correspond to a <tp:type>Connection_Status_Reason</tp:type>, or may be a more specific Telepathy error (such as <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code> for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. <tp:rationale> For instance, a SIP connection manager could signal &quot;402 Payment Required&quot; as an error in a connection-manager-specific namespace, or a link-local XMPP implementation that used Avahi could provide the error given to it by the avahi-daemon. </tp:rationale>

arg_Details :

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Additional information about the error, which may include the following well-known keys:</p> <dl> <dt>debug-message (s)</dt> <dd>Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances</dd> <dt>server-message (s)</dt> <dd>A human-readable message from the server explaining what happened. This may be in the user's native language, or in the server operator's native language, or even in Lojban.</dd> <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt> <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd> </dl>

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_connection_connect_to_connection_error ()

TpProxySignalConnection * tp_cli_connection_connect_to_connection_error
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_signal_callback_connection_error callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal ConnectionError.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when an error occurs that renders this connection unusable. </p> <p>Whenever this signal is emitted, it MUST immediately be followed by a <tp:member-ref>StatusChanged</tp:member-ref> signal with status Connection_Status_Disconnected and an appropriate reason code.</p> <p>Connection managers SHOULD emit this signal on disconnection, but need not do so. Clients MUST support connection managers that emit StatusChanged(Disconnected, ...) without first emitting ConnectionError.</p> <tp:rationale> <p>This signal provides additional information about the reason for disconnection. The reason for connection is always straightforward - it was requested - so it does not need further explanation. However, on errors, it can be useful to provide additional information.</p> <p>The <tp:type>Connection_Status_Reason</tp:type> is not given here, since it will be signalled in <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client implementation would be to store the information given by this signal until StatusChanged is received, at which point the information given by this signal can be used to supplement the StatusChanged signal.</p> </tp:rationale>

proxy :

A TpConnection or subclass

callback :

Callback to be called when the signal is received

user_data :

User-supplied data for the callback

destroy :

Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

If not NULL, used to raise an error if NULL is returned

Returns :

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_call_add_client_interest ()

TpProxyPendingCall * tp_cli_connection_call_add_client_interest
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar **in_Tokens,
                                                         tp_cli_connection_callback_for_add_client_interest callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a AddClientInterest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Register a client's interest in notifications related to one or more interfaces.</p> <p>Groups of notifications are identified by a token which is either a D-Bus interface name, or a string that starts with a D-Bus interface name. The meaning of each token is given by that D-Bus interface, which MUST define it in its documentation.</p> <tp:rationale> <p>Initially, all interests are in entire interface, but allowing other strings allows subscription to part of an interface; for instance, an interest in ...MailNotification/count could track the number of messages without caring about their detailed content.</p> </tp:rationale> <p>For each token with which this method interacts, the Connection tracks an &quot;interest count&quot; (like a reference count) for each unique bus name that has called this method. When a client calls this method, for each token, the interest count for its unique bus name is incremented; when <tp:member-ref>RemoveClientInterest</tp:member-ref> is called, all interest counts for that unique bus name are decremented. If the unique bus name leaves the bus (for instance, if the client crashes or exits), all interest counts for that unique bus name are set to zero.</p> <p>The Connection can then use these reference counts to avoid subscribing to protocol-level notifications unless at least one client has a non-zero interest count for the relevant token.</p> <tp:rationale> <p>This method exists to reduce memory and network overhead when there is no active subscription.</p> <p>One situation where this is useful is <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>: on XMPP, location updates are received over PEP. If the Connection advertises the <code>geoloc+notify</code> capability, it will be sent location updates for all contacts. To avoid consuming resources for this, the connection should avoid advertising that capability until a client has expressed an interest in contacts' locations.</p> <p>Another example of a protocol that benefits from this method is the Google XMPP Mail Notification extension, which can be used to implement <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">MailNotification</tp:dbus-ref>. In this protocol, the CM receives a notification that something has changed, but to get more information, the CM must request this information. Knowing that nobody is currently interested in this information, the CM can avoid generating useless network traffic. Similarly, the CM may free the list of unread messages to reduce memory overhead.</p> </tp:rationale> <p>If this method is called for an interface that might require protocol-level subscription, but the connection cannot set up that subscription yet (for instance because the <tp:member-ref>Status</tp:member-ref> is not Connected yet), the Connection MUST remember the client's interest, and attempt to subscribe to the appropriate protocol feature when this becomes possible.</p> <p>Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.</p> <tp:rationale> <p>The only reason it could fail is if it's unimplemented, in which case the only thing the client can usefully do is to proceed as if it had succeeded.</p> </tp:rationale>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Tokens :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Interfaces or parts of interfaces in which to register an interest, represented by either a <tp:type>DBus_Interface</tp:type>, or a string prefixed with a <tp:type>DBus_Interface</tp:type>.</p> <p>If the Connection does not support one of these tokens, this is not considered to be an error; the unsupported token is simply ignored.</p>

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_call_remove_client_interest ()

TpProxyPendingCall * tp_cli_connection_call_remove_client_interest
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar **in_Tokens,
                                                         tp_cli_connection_callback_for_remove_client_interest callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a RemoveClientInterest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Release an interest registered using <tp:member-ref>AddClientInterest</tp:member-ref>. See that method's documentation for details.</p> <p>Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.</p> <tp:rationale> <p>The only reasons it could fail are if it's unimplemented, or if the client's reference-counting is wrong and it has tried to remove a client interest that it did not add. In both cases, there's nothing the client could do about it.</p> </tp:rationale>

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Tokens :

Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Interfaces or parts of interfaces that were previously passed to <tp:member-ref>AddClientInterest</tp:member-ref>.</p>

callback :

called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_callback_for_add_client_interest ()

void                (*tp_cli_connection_callback_for_add_client_interest)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a AddClientInterest method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_callback_for_remove_client_interest ()

void                (*tp_cli_connection_callback_for_remove_client_interest)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a RemoveClientInterest method call succeeds or fails.

proxy :

the proxy on which the call was made

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

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_simple_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 "connection-manager-name" property

  "connection-manager-name"  gchar*                : Read

Warning

TpConnection:connection-manager-name is deprecated and should not be used in newly-written code. Use "cm-name" instead.

This connection's connection manager name.

Default value: NULL

Since 0.13.16


The "connection-ready" property

  "connection-ready"         gboolean              : Read

Warning

TpConnection:connection-ready has been deprecated since version 0.17.6 and should not be used in newly-written code. use tp_proxy_is_prepared() with TP_CHANNEL_FEATURE_CONNECTED for checks, or tp_proxy_prepare_async() for notification

Initially FALSE; changes to TRUE when the connection has gone to CONNECTED status, introspection has finished and it's ready for use.

By the time this property becomes TRUE, any extra interfaces will have been set up and the "interfaces" property will have been populated.

This is similar to TP_CONNECTION_FEATURE_CONNECTED, except that once it has changed to TRUE, it remains TRUE even if the connection has been invalidated.

Default value: FALSE


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_simple_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 "self-handle" property

  "self-handle"              guint                 : Read

Warning

TpConnection:self-handle is deprecated and should not be used in newly-written code. Use "self-contact" instead.

The TP_HANDLE_TYPE_CONTACT handle of the local user on this connection, or 0 if we don't know yet or if the connection has become invalid.

This may change if the local user's unique identifier changes (for instance by using /nick on IRC), in which case "notify" will be emitted.

To wait for a valid self-handle (and other properties), call tp_proxy_prepare_async() with the feature TP_CONNECTION_FEATURE_CONNECTED.

Default value: 0


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