![]() |
![]() |
![]() |
telepathy-glib API Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#include <telepathy-glib/telepathy-glib.h> struct TpProtocol; TpProtocolClass; TpProtocol * tp_protocol_new (TpDBusDaemon *dbus
,const gchar *cm_name
,const gchar *protocol_name
,const GHashTable *immutable_properties
,GError **error
); const gchar * tp_protocol_get_name (TpProtocol *self
); const gchar * tp_protocol_get_cm_name (TpProtocol *self
); void tp_protocol_init_known_interfaces (void
); #define TP_PROTOCOL_FEATURE_PARAMETERS GPtrArray * tp_protocol_get_params (TpProtocol *self
); GList * tp_protocol_dup_params (TpProtocol *self
); GStrv tp_protocol_dup_param_names (TpProtocol *self
); const TpConnectionManagerParam * tp_protocol_get_param (TpProtocol *self
,const gchar *param
); TpConnectionManagerParam * tp_protocol_dup_param (TpProtocol *self
,const gchar *param
); gboolean tp_protocol_has_param (TpProtocol *self
,const gchar *param
); gboolean tp_protocol_can_register (TpProtocol *self
); #define TP_PROTOCOL_FEATURE_CORE TpCapabilities * tp_protocol_get_capabilities (TpProtocol *self
); const gchar * tp_protocol_get_english_name (TpProtocol *self
); const gchar * tp_protocol_get_icon_name (TpProtocol *self
); const gchar * tp_protocol_get_vcard_field (TpProtocol *self
); const gchar * const * tp_protocol_get_authentication_types (TpProtocol *self
); void tp_protocol_identify_account_async (TpProtocol *self
,GVariant *vardict
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gchar * tp_protocol_identify_account_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
); void tp_protocol_normalize_contact_async (TpProtocol *self
,const gchar *contact
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gchar * tp_protocol_normalize_contact_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
); TpAvatarRequirements * tp_protocol_get_avatar_requirements (TpProtocol *self
); GList * tp_protocol_dup_presence_statuses (TpProtocol *self
); const gchar * const * tp_protocol_get_addressable_uri_schemes (TpProtocol *self
); const gchar * const * tp_protocol_get_addressable_vcard_fields (TpProtocol *self
); void tp_protocol_normalize_contact_uri_async (TpProtocol *self
,const gchar *uri
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gchar * tp_protocol_normalize_contact_uri_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
); void tp_protocol_normalize_vcard_address_async (TpProtocol *self
,const gchar *field
,const gchar *value
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gchar * tp_protocol_normalize_vcard_address_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
);
"addressable-uri-schemes" GStrv : Read "addressable-vcard-fields" GStrv : Read "authentication-types" GStrv : Read "avatar-requirements" gpointer : Read "capabilities" TpCapabilities* : Read "cm-name" gchar* : Read / Write / Construct Only "english-name" gchar* : Read "icon-name" gchar* : Read "param-names" GStrv : Read "protocol-name" gchar* : Read / Write / Construct Only "protocol-properties" GHashTable_gchararray+GValue_* : Read / Write / Construct Only "vcard-field" gchar* : Read
TpProtocol objects represent the protocols implemented by Telepathy connection managers. In modern connection managers, each protocol is represented by a D-Bus object; in older connection managers, the protocols are represented by data structures, and this object merely emulates a D-Bus object.
typedef struct _TpProtocolClass TpProtocolClass;
The class of a TpProtocol.
Since 0.11.11
TpProtocol * tp_protocol_new (TpDBusDaemon *dbus
,const gchar *cm_name
,const gchar *protocol_name
,const GHashTable *immutable_properties
,GError **error
);
|
proxy for the D-Bus daemon; may not be NULL
|
|
the connection manager name (such as "gabble") |
|
the protocol name (such as "jabber") |
|
the immutable D-Bus properties for this protocol |
|
used to indicate the error if NULL is returned |
Returns : |
a new protocol proxy, or NULL on invalid arguments |
Since 0.11.11
const gchar * tp_protocol_get_name (TpProtocol *self
);
Return the same thing as the protocol-name property, for convenient use
in C code. The returned string is valid for as long as self
exists.
|
a protocol object |
Returns : |
the value of the "protocol-name" property |
Since 0.11.11
const gchar * tp_protocol_get_cm_name (TpProtocol *self
);
Return the "cm-name" property.
|
a TpProtocol |
Returns : |
the value of "cm-name" |
Since 0.19.1
void tp_protocol_init_known_interfaces (void
);
Ensure that the known interfaces for TpProtocol 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_PROTOCOL
.
Since 0.11.11
#define TP_PROTOCOL_FEATURE_PARAMETERS
Expands to a call to a function that returns a quark for the parameters feature of a TpProtocol.
When this feature is prepared, the possible parameters for connections to this protocol have been retrieved and are available for use.
Unlike TP_PROTOCOL_FEATURE_CORE
, this feature can even be available on
connection managers that don't really have Protocol objects
(on these older connection managers, the TpProtocol uses information from
ConnectionManager methods to provide the list of parameters).
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.11
GPtrArray * tp_protocol_get_params (TpProtocol *self
);
Returns an array of parameters supported by this connection manager,
without additional memory allocations. The returned array is owned by
self
, and must not be used after self
has been freed.
|
a protocol |
Returns : |
a GPtrArray of TpConnectionManagerParam. [transfer none][type GLib.PtrArray][element-type TelepathyGLib.ConnectionManagerParam] |
Since 0.99.1
GList * tp_protocol_dup_params (TpProtocol *self
);
Returns a list of parameters supported by this connection manager.
The returned list must be freed by the caller, for instance with
g_list_free_full (l,
(GDestroyNotify) tp_connection_manager_param_free)
.
|
a protocol |
Returns : |
a list of TpConnectionManagerParam structures, owned by the caller. [transfer full][element-type TelepathyGLib.ConnectionManagerParam] |
Since 0.17.6
GStrv tp_protocol_dup_param_names (TpProtocol *self
);
Returns a list of parameter names supported by this connection manager for this protocol.
The result is copied and must be freed by the caller with g_strfreev()
.
|
a protocol |
Returns : |
a copy of "param-names". [array zero-terminated=1][transfer full] |
Since 0.11.11
const TpConnectionManagerParam * tp_protocol_get_param (TpProtocol *self
,const gchar *param
);
|
a protocol |
|
a parameter name |
Returns : |
a structure representing the parameter param , or NULL if not
supported |
Since 0.11.11
TpConnectionManagerParam * tp_protocol_dup_param (TpProtocol *self
,const gchar *param
);
|
a protocol |
|
a parameter name |
Returns : |
a structure representing the parameter param ,
or NULL if not supported. Free with tp_connection_manager_param_free() . [transfer full]
|
Since 0.17.6
gboolean tp_protocol_has_param (TpProtocol *self
,const gchar *param
);
|
a protocol |
|
a parameter name |
Returns : |
TRUE if self supports the parameter param . |
Since 0.11.11
gboolean tp_protocol_can_register (TpProtocol *self
);
Return whether a new account can be registered on this protocol, by setting
the special "register" parameter to TRUE
.
|
a protocol |
Returns : |
TRUE if protocol supports the parameter "register" |
Since 0.11.11
#define TP_PROTOCOL_FEATURE_CORE
Expands to a call to a function that returns a quark for the core feature of a TpProtocol.
When this feature is prepared, at least the following basic information about the protocol is available:
(This feature implies that TP_PROTOCOL_FEATURE_PARAMETERS
is also
available.)
Unlike TP_PROTOCOL_FEATURE_PARAMETERS
, this feature can only become
available on connection managers that implement Protocol objects.
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.11
TpCapabilities * tp_protocol_get_capabilities (TpProtocol *self
);
|
a protocol object |
Returns : |
"capabilities", which must be referenced
(if non-NULL ) if it will be kept. [transfer none]
|
Since 0.11.11
const gchar * tp_protocol_get_english_name (TpProtocol *self
);
|
a protocol object |
Returns : |
the non-NULL , non-empty value of "english-name"
|
Since 0.11.11
const gchar * tp_protocol_get_icon_name (TpProtocol *self
);
|
a protocol object |
Returns : |
the non-NULL , non-empty value of "icon-name"
|
Since 0.11.11
const gchar * tp_protocol_get_vcard_field (TpProtocol *self
);
|
a protocol object |
Returns : |
the value of "vcard-field" |
Since 0.11.11
const gchar * const * tp_protocol_get_authentication_types
(TpProtocol *self
);
|
a protocol object |
Returns : |
the value of "authentication-types". [transfer none] |
Since 0.13.9
void tp_protocol_identify_account_async (TpProtocol *self
,GVariant *vardict
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Return a string that could identify the account with the given parameters. In most protocols that string is a normalized 'account' parameter, but some protocols have more complex requirements; for instance, on IRC, the 'account' (nickname) is insufficient, and must be combined with a server or network name.
|
a protocol |
|
the account parameters as a GVariant of
type G_VARIANT_TYPE_VARDICT . If it is floating, ownership will
be taken, as if via g_variant_ref_sink() . |
|
may be used to cancel the async request. [allow-none] |
|
a callback to call when the request is satisfied. [scope async] |
|
data to pass to callback . [closure][allow-none]
|
Since 0.99.5
gchar * tp_protocol_identify_account_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
);
Interpret the result of tp_protocol_identify_account_async()
.
|
a protocol |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
a string identifying the account,
or NULL on error. [transfer full]
|
Since 0.99.5
void tp_protocol_normalize_contact_async (TpProtocol *self
,const gchar *contact
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Perform best-effort offline contact normalization. This does syntactic normalization (e.g. transforming case-insensitive text to lower-case), but does not query servers or anything similar.
|
a protocol |
|
a contact identifier, possibly invalid |
|
may be used to cancel the async request. [allow-none] |
|
a callback to call when the request is satisfied. [scope async] |
|
data to pass to callback . [closure][allow-none]
|
Since 0.99.5
gchar * tp_protocol_normalize_contact_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
);
Interpret the result of tp_protocol_normalize_contact_async()
.
|
a protocol |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
the normalized form of contact ,
or NULL on error. [transfer full]
|
Since 0.99.5
TpAvatarRequirements * tp_protocol_get_avatar_requirements
(TpProtocol *self
);
Return the "avatar-requirements" property
|
a TpProtocol |
Returns : |
the value of "avatar-requirements". [transfer none] |
Since 0.15.6
GList * tp_protocol_dup_presence_statuses (TpProtocol *self
);
Return the presence statuses that might be supported by connections to this protocol.
It is possible that some of these statuses will not actually be supported by a connection: for instance, an XMPP connection manager would include "hidden" in this list, even though not all XMPP servers allow users to be online-but-hidden.
|
a protocol object |
Returns : |
a
list of statuses, or NULL if unknown. [transfer full][element-type TelepathyGLib.PresenceStatusSpec]
|
const gchar * const * tp_protocol_get_addressable_uri_schemes
(TpProtocol *self
);
|
a protocol object |
Returns : |
the value of "addressable-uri-schemes". [transfer none] |
Since 0.99.5
const gchar * const * tp_protocol_get_addressable_vcard_fields
(TpProtocol *self
);
|
a protocol object |
Returns : |
the value of "addressable-vcard-fields". [transfer none] |
Since 0.99.5
void tp_protocol_normalize_contact_uri_async (TpProtocol *self
,const gchar *uri
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Perform best-effort offline contact normalization, for a contact in the form of a URI. This method will fail if the URI is not in a scheme supported by this protocol or connection manager.
|
a protocol |
|
a contact URI, possibly invalid |
|
may be used to cancel the async request. [allow-none] |
|
a callback to call when the request is satisfied. [scope async] |
|
data to pass to callback . [closure][allow-none]
|
Since 0.99.5
gchar * tp_protocol_normalize_contact_uri_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
);
Interpret the result of tp_protocol_normalize_contact_uri_async()
.
|
a protocol |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
the normalized form of uri ,
or NULL on error. [transfer full]
|
Since 0.99.5
void tp_protocol_normalize_vcard_address_async (TpProtocol *self
,const gchar *field
,const gchar *value
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Perform best-effort offline contact normalization, for a contact in the form of a vCard field. This method will fail if the vCard field is not supported by this protocol or connection manager.
|
a protocol |
|
a vCard field |
|
an address that is a value of field
|
|
may be used to cancel the async request. [allow-none] |
|
a callback to call when the request is satisfied. [scope async] |
|
data to pass to callback . [closure][allow-none]
|
Since 0.99.5
gchar * tp_protocol_normalize_vcard_address_finish (TpProtocol *self
,GAsyncResult *result
,GError **error
);
Interpret the result of tp_protocol_normalize_vcard_address_async()
.
|
a protocol |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
the normalized form of value ,
or NULL on error. [transfer full]
|
Since 0.99.5
"addressable-uri-schemes"
property"addressable-uri-schemes" GStrv : Read
A non-NULL
GStrv of URI schemes supported by this protocol.
If this protocol does not support addressing contacts by URI,
the list is empty.
For instance, a SIP connection manager that supports calling contacts by SIP URI (sip:alice@example.com, sips:bob@example.com) or telephone number (tel:+1-555-0123) might have { "sip", "sips", "tel", NULL }.
Since 0.99.5
"addressable-vcard-fields"
property"addressable-vcard-fields" GStrv : Read
A non-NULL
GStrv of vCard fields supported by this protocol.
If this protocol does not support addressing contacts by a vCard field,
the list is empty.
For instance, a SIP connection manager that supports calling contacts by SIP URI (vCard field SIP) or telephone number (vCard field TEL) might have { "sip", "tel", NULL }.
Since 0.99.5
"authentication-types"
property"authentication-types" GStrv : Read
A non-NULL
GStrv of interfaces which provide information as to
what kind of authentication channels can possibly appear before
the connection reaches the CONNECTED state, or NULL
if
TP_PROTOCOL_FEATURE_CORE
has not been prepared.
Since 0.13.9
"avatar-requirements"
property"avatar-requirements" gpointer : Read
A TpAvatarRequirements representing the avatar requirements on this
protocol, or NULL
if TP_PROTOCOL_FEATURE_CORE
has not been prepared or
if the protocol doesn't support avatars.
Since 0.15.6
"capabilities"
property"capabilities" TpCapabilities* : Read
The classes of channel that can be requested from connections to this
protocol, or NULL
if this is unknown or the TP_PROTOCOL_FEATURE_CORE
feature has not been prepared.
Since 0.11.11
"cm-name"
property"cm-name" gchar* : Read / Write / Construct Only
The name of the connection manager this protocol is on.
Default value: NULL
Since 0.19.1
"english-name"
property"english-name" gchar* : Read
The name of the protocol in a form suitable for display to users,
such as "AIM" or "Yahoo!", or a string based on "protocol-name"
(currently constructed by putting the first character in title case,
but this is not guaranteed) if no better name is available or the
TP_PROTOCOL_FEATURE_CORE
feature has not been prepared.
This is effectively in the C locale (international English); user interfaces requiring a localized protocol name should look one up in their own message catalog based on either "protocol-name" or "english-name", but should use this English version as a fallback if no translated version can be found.
Default value: NULL
Since 0.11.11
"icon-name"
property"icon-name" gchar* : Read
The name of an icon in the system's icon theme. If none was supplied
by the Protocol, or the TP_PROTOCOL_FEATURE_CORE
feature has not been
prepared, a default is used; currently, this is "im-" plus
"protocol-name".
Default value: NULL
Since 0.11.11
"param-names"
property"param-names" GStrv : Read
A list of parameter names supported by this connection manager
for this protocol, or NULL
if TP_PROTOCOL_FEATURE_PARAMETERS
has not
been prepared.
Since 0.11.11
"protocol-name"
property"protocol-name" gchar* : Read / Write / Construct Only
The machine-readable name of the protocol, taken from the Telepathy D-Bus Interface Specification, such as "jabber" or "local-xmpp".
Default value: NULL
Since 0.11.11
"protocol-properties"
property "protocol-properties" GHashTable_gchararray+GValue_* : Read / Write / Construct Only
The immutable properties of this Protocol, as provided at construction time. This is a map from string to GValue, which must not be modified.
If the immutable properties were not provided at construction time,
the TP_PROTOCOL_FEATURE_PARAMETERS
and TP_PROTOCOL_FEATURE_CORE
features
will both be unavailable, and this TpProtocol object will only be useful
as a way to access lower-level D-Bus calls.
Since 0.11.11
"vcard-field"
property"vcard-field" gchar* : Read
The most common vCard field used for this protocol's contact
identifiers, normalized to lower case, or NULL
if there is no such field
or the TP_PROTOCOL_FEATURE_CORE
feature has not been prepared.
Default value: NULL
Since 0.11.11