TpProtocol

TpProtocol — proxy for a Telepathy Protocol object

Functions

TpProtocol * tp_protocol_new ()
TpProtocol * tp_protocol_new_vardict ()
const gchar * tp_protocol_get_name ()
const gchar * tp_protocol_get_cm_name ()
void tp_protocol_init_known_interfaces ()
const TpConnectionManagerParam * tp_protocol_borrow_params ()
GList * tp_protocol_dup_params ()
GStrv tp_protocol_dup_param_names ()
const TpConnectionManagerParam * tp_protocol_get_param ()
TpConnectionManagerParam * tp_protocol_dup_param ()
gboolean tp_protocol_has_param ()
gboolean tp_protocol_can_register ()
GVariant * tp_protocol_dup_immutable_properties ()
TpCapabilities * tp_protocol_get_capabilities ()
const gchar * tp_protocol_get_english_name ()
const gchar * tp_protocol_get_icon_name ()
const gchar * tp_protocol_get_vcard_field ()
const gchar * const * tp_protocol_get_authentication_types ()
void tp_protocol_identify_account_async ()
gchar * tp_protocol_identify_account_finish ()
void tp_protocol_normalize_contact_async ()
gchar * tp_protocol_normalize_contact_finish ()
TpAvatarRequirements * tp_protocol_get_avatar_requirements ()
GList * tp_protocol_dup_presence_statuses ()
const gchar * const * tp_protocol_get_addressable_uri_schemes ()
const gchar * const * tp_protocol_get_addressable_vcard_fields ()
void tp_protocol_normalize_contact_uri_async ()
gchar * tp_protocol_normalize_contact_uri_finish ()
void tp_protocol_normalize_vcard_address_async ()
gchar * tp_protocol_normalize_vcard_address_finish ()
TpProxyPendingCall * tp_cli_protocol_call_identify_account ()
TpProxyPendingCall * tp_cli_protocol_call_normalize_contact ()
void (*tp_cli_protocol_callback_for_identify_account) ()
void (*tp_cli_protocol_callback_for_normalize_contact) ()
TpProxyPendingCall * tp_cli_protocol_interface_addressing_call_normalize_contact_uri ()
TpProxyPendingCall * tp_cli_protocol_interface_addressing_call_normalize_vcard_address ()
void (*tp_cli_protocol_interface_addressing_callback_for_normalize_contact_uri) ()
void (*tp_cli_protocol_interface_addressing_callback_for_normalize_vcard_address) ()

Properties

GStrv addressable-uri-schemes Read
GStrv addressable-vcard-fields Read
GStrv authentication-types Read
gpointer avatar-requirements Read
TpCapabilities * capabilities Read
gchar * cm-name Read / Write / Construct Only
gchar * english-name Read
gchar * icon-name Read
GStrv param-names Read
gchar * protocol-name Read / Write / Construct Only
GHashTable_gchararray+GValue_* protocol-properties Read / Write / Construct Only
GVariant * protocol-properties-vardict Read
gchar * vcard-field Read

Types and Values

Object Hierarchy

    GObject
    ╰── TpProxy
        ╰── TpProtocol

Includes

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

Description

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.

Functions

tp_protocol_new ()

TpProtocol *
tp_protocol_new (TpDBusDaemon *dbus,
                 const gchar *cm_name,
                 const gchar *protocol_name,
                 const GHashTable *immutable_properties,
                 GError **error);

Parameters

dbus

proxy for the D-Bus daemon; may not be NULL

 

cm_name

the connection manager name (such as "gabble")

 

protocol_name

the protocol name (such as "jabber")

 

immutable_properties

the immutable D-Bus properties for this protocol

 

error

used to indicate the error if NULL is returned

 

Returns

a new protocol proxy, or NULL on invalid arguments

Since: 0.11.11


tp_protocol_new_vardict ()

TpProtocol *
tp_protocol_new_vardict (TpDBusDaemon *dbus,
                         const gchar *cm_name,
                         const gchar *protocol_name,
                         GVariant *immutable_properties,
                         GError **error);

Create a new protocol proxy.

If immutable_properties is a floating reference, this function will take ownership of it, much like g_variant_ref_sink(). See documentation of that function for details.

Parameters

dbus

proxy for the D-Bus daemon; may not be NULL

 

cm_name

the connection manager name (such as "gabble")

 

protocol_name

the protocol name (such as "jabber")

 

immutable_properties

the immutable D-Bus properties for this protocol

 

error

used to indicate the error if NULL is returned

 

Returns

a new protocol proxy, or NULL on invalid arguments

Since: 0.23.3


tp_protocol_get_name ()

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.

Parameters

self

a protocol object

 

Returns

the value of the “protocol-name” property

Since: 0.11.11


tp_protocol_get_cm_name ()

const gchar *
tp_protocol_get_cm_name (TpProtocol *self);

Return the “cm-name” property.

Parameters

self

a TpProtocol

 

Returns

the value of “cm-name”

Since: 0.19.1


tp_protocol_init_known_interfaces ()

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


tp_protocol_borrow_params ()

const TpConnectionManagerParam *
tp_protocol_borrow_params (TpProtocol *self);

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

Since 0.19.9. New code should use tp_protocol_dup_params() instead.

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.

[skip]

Parameters

self

a protocol

 

Returns

an array of TpConnectionManagerParam structures, terminated by one whose name is NULL.

[transfer none]

Since: 0.17.6


tp_protocol_dup_params ()

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

Parameters

self

a protocol

 

Returns

a list of TpConnectionManagerParam structures, owned by the caller.

[transfer full][element-type TelepathyGLib.ConnectionManagerParam]

Since: 0.17.6


tp_protocol_dup_param_names ()

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

Parameters

self

a protocol

 

Returns

a copy of “param-names”.

[array zero-terminated=1][transfer full]

Since: 0.11.11


tp_protocol_get_param ()

const TpConnectionManagerParam *
tp_protocol_get_param (TpProtocol *self,
                       const gchar *param);

Parameters

self

a protocol

 

param

a parameter name

 

Returns

a structure representing the parameter param , or NULL if not supported

Since: 0.11.11


tp_protocol_dup_param ()

TpConnectionManagerParam *
tp_protocol_dup_param (TpProtocol *self,
                       const gchar *param);

Parameters

self

a protocol

 

param

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


tp_protocol_has_param ()

gboolean
tp_protocol_has_param (TpProtocol *self,
                       const gchar *param);

Parameters

self

a protocol

 

param

a parameter name

 

Returns

TRUE if self supports the parameter param .

Since: 0.11.11


tp_protocol_can_register ()

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.

Parameters

self

a protocol

 

Returns

TRUE if protocol supports the parameter "register"

Since: 0.11.11


tp_protocol_dup_immutable_properties ()

GVariant *
tp_protocol_dup_immutable_properties (TpProtocol *self);

Return the “protocol-properties-vardict” property.

Parameters

self

a TpProtocol object

 

Returns

the value of “protocol-properties-vardict”.

[transfer full]

Since: 0.23.3


tp_protocol_get_capabilities ()

TpCapabilities *
tp_protocol_get_capabilities (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

“capabilities”, which must be referenced (if non-NULL) if it will be kept.

[transfer none]

Since: 0.11.11


tp_protocol_get_english_name ()

const gchar *
tp_protocol_get_english_name (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

the non-NULL, non-empty value of “english-name”

Since: 0.11.11


tp_protocol_get_icon_name ()

const gchar *
tp_protocol_get_icon_name (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

the non-NULL, non-empty value of “icon-name”

Since: 0.11.11


tp_protocol_get_vcard_field ()

const gchar *
tp_protocol_get_vcard_field (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

the value of “vcard-field”

Since: 0.11.11


tp_protocol_get_authentication_types ()

const gchar * const *
tp_protocol_get_authentication_types (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

the value of “authentication-types”.

[transfer none]

Since: 0.13.9


tp_protocol_identify_account_async ()

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.

Parameters

self

a protocol

 

vardict

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

 

cancellable

may be used to cancel the async request.

[allow-none]

callback

a callback to call when the request is satisfied.

[scope async]

user_data

data to pass to callback .

[closure][allow-none]

Since: 0.23.1


tp_protocol_identify_account_finish ()

gchar *
tp_protocol_identify_account_finish (TpProtocol *self,
                                     GAsyncResult *result,
                                     GError **error);

Interpret the result of tp_protocol_identify_account_async().

Parameters

self

a protocol

 

result

a GAsyncResult

 

error

a GError to fill

 

Returns

a string identifying the account, or NULL on error.

[transfer full]

Since: 0.23.1


tp_protocol_normalize_contact_async ()

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.

Parameters

self

a protocol

 

contact

a contact identifier, possibly invalid

 

cancellable

may be used to cancel the async request.

[allow-none]

callback

a callback to call when the request is satisfied.

[scope async]

user_data

data to pass to callback .

[closure][allow-none]

Since: 0.23.1


tp_protocol_normalize_contact_finish ()

gchar *
tp_protocol_normalize_contact_finish (TpProtocol *self,
                                      GAsyncResult *result,
                                      GError **error);

Interpret the result of tp_protocol_normalize_contact_async().

Parameters

self

a protocol

 

result

a GAsyncResult

 

error

a GError to fill

 

Returns

the normalized form of contact , or NULL on error.

[transfer full]

Since: 0.23.1


tp_protocol_get_avatar_requirements ()

TpAvatarRequirements *
tp_protocol_get_avatar_requirements (TpProtocol *self);

Return the “avatar-requirements” property

Parameters

self

a TpProtocol

 

Returns

the value of “avatar-requirements”.

[transfer none]

Since: 0.15.6


tp_protocol_dup_presence_statuses ()

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.

Parameters

self

a protocol object

 

Returns

a list of statuses, or NULL if unknown.

[transfer full][element-type TelepathyGLib.PresenceStatusSpec]


tp_protocol_get_addressable_uri_schemes ()

const gchar * const *
tp_protocol_get_addressable_uri_schemes
                               (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

the value of “addressable-uri-schemes”.

[transfer none]

Since: 0.23.1


tp_protocol_get_addressable_vcard_fields ()

const gchar * const *
tp_protocol_get_addressable_vcard_fields
                               (TpProtocol *self);

Parameters

self

a protocol object

 

Returns

the value of “addressable-vcard-fields”.

[transfer none]

Since: 0.23.1


tp_protocol_normalize_contact_uri_async ()

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.

Parameters

self

a protocol

 

uri

a contact URI, possibly invalid

 

cancellable

may be used to cancel the async request.

[allow-none]

callback

a callback to call when the request is satisfied.

[scope async]

user_data

data to pass to callback .

[closure][allow-none]

Since: 0.23.1


tp_protocol_normalize_contact_uri_finish ()

gchar *
tp_protocol_normalize_contact_uri_finish
                               (TpProtocol *self,
                                GAsyncResult *result,
                                GError **error);

Interpret the result of tp_protocol_normalize_contact_uri_async().

Parameters

self

a protocol

 

result

a GAsyncResult

 

error

a GError to fill

 

Returns

the normalized form of uri , or NULL on error.

[transfer full]

Since: 0.23.1


tp_protocol_normalize_vcard_address_async ()

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.

Parameters

self

a protocol

 

field

a vCard field

 

value

an address that is a value of field

 

cancellable

may be used to cancel the async request.

[allow-none]

callback

a callback to call when the request is satisfied.

[scope async]

user_data

data to pass to callback .

[closure][allow-none]

Since: 0.23.1


tp_protocol_normalize_vcard_address_finish ()

gchar *
tp_protocol_normalize_vcard_address_finish
                               (TpProtocol *self,
                                GAsyncResult *result,
                                GError **error);

Interpret the result of tp_protocol_normalize_vcard_address_async().

Parameters

self

a protocol

 

result

a GAsyncResult

 

error

a GError to fill

 

Returns

the normalized form of value , or NULL on error.

[transfer full]

Since: 0.23.1


tp_cli_protocol_call_identify_account ()

TpProxyPendingCall *
tp_cli_protocol_call_identify_account (gpointer proxy,
                                       gint timeout_ms,
                                       GHashTable *in_Parameters,
                                       tp_cli_protocol_callback_for_identify_account callback,
                                       gpointer user_data,
                                       GDestroyNotify destroy,
                                       GObject *weak_object);

Start a IdentifyAccount method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Return a string which uniquely identifies the account to which the given parameters would connect.</p> <tp:rationale> <p>For many protocols, this would return the well-known 'account' parameter. However, for IRC the returned string would be composed from the 'account' (i.e. nickname) and 'server' parameters. AccountManager implementations can use this to form the account-specific part of an Account's object path.</p> </tp:rationale>

Parameters

proxy

the TpProxy

 

timeout_ms

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

 

in_Parameters

Used to pass an 'in' argument: A set of parameters as would be provided to <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>

 

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

TpProxyPendingCall *
tp_cli_protocol_call_normalize_contact
                               (gpointer proxy,
                                gint timeout_ms,
                                const gchar *in_Contact_ID,
                                tp_cli_protocol_callback_for_normalize_contact callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a NormalizeContact method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Attempt to normalize the given contact ID. Where possible, this SHOULD return the same thing that would be returned by InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.</p> <p>If full normalization requires network activity or is otherwise impossible to do without a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization.</p> <tp:rationale> <p>One common example of a best-effort offline normalization differing from the ideal normalization is XMPP.</p> <p>On XMPP, contacts' JIDs should normally have the resource removed during normalization, but for contacts in a MUC (chatroom), the resource is an integral part of the JID - so the contact JID aliceexample.com /Empathy should normalize to aliceexample.com , but the in-MUC JID wonderlandconference.example.com /Alice should normalize to itself.</p> <p>While online, the connection manager has enough context to know which chatrooms the user is in, and can infer from that whether to remove resources, but the best-effort normalization performed while offline does not have this context, so the best that can be done is to remove the resource from all JIDs.</p> </tp:rationale> <p>This method MAY simply raise NotImplemented on some protocols.</p> <tp:rationale> <p>In link-local XMPP, you can't talk to someone who isn't present on your local network, so normalizing identifiers in advance is meaningless.</p> </tp:rationale>

Parameters

proxy

the TpProxy

 

timeout_ms

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

 

in_Contact_ID

Used to pass an 'in' argument: The identifier of a contact in this protocol

 

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

void
(*tp_cli_protocol_callback_for_identify_account)
                               (TpProxy *proxy,
                                const gchar *out_Account_ID,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy

the proxy on which the call was made

 

out_Account_ID

Used to return an 'out' argument if error is NULL: <p>An opaque string suitable for use as the account-specific part of an <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>'s object path. This is not necessarily globally unique, but should represent a &quot;best-effort&quot; identification of the account.</p> <tp:rationale> <p>For a pathological case, consider a user signing in as 'meexample.com ' with 'server' set to either jabber1.example.com or jabber2.example.com. Both of these should result in meexample.com being returned from this method, even if the user can actually be signed in to those two servers simultaneously.</p> </tp:rationale>

 

error

NULL on success, or an error on failure

 

user_data

user-supplied data

 

weak_object

user-supplied object

 

tp_cli_protocol_callback_for_normalize_contact ()

void
(*tp_cli_protocol_callback_for_normalize_contact)
                               (TpProxy *proxy,
                                const gchar *out_Normalized_Contact_ID,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy

the proxy on which the call was made

 

out_Normalized_Contact_ID

Used to return an 'out' argument if error is NULL: The identifier of a contact in this protocol, normalized as much as possible

 

error

NULL on success, or an error on failure

 

user_data

user-supplied data

 

weak_object

user-supplied object

 

tp_cli_protocol_interface_addressing_call_normalize_contact_uri ()

TpProxyPendingCall *
tp_cli_protocol_interface_addressing_call_normalize_contact_uri
                               (gpointer proxy,
                                gint timeout_ms,
                                const gchar *in_URI,
                                tp_cli_protocol_interface_addressing_callback_for_normalize_contact_uri callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a NormalizeContactURI method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Attempt to normalize the given contact URI. Where possible, this SHOULD return an address that would appear in the <code>org.freedesktop.Telepathy.Connection.Interface.Addressing1/uris</code> attribute for a contact on a connected <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. </p> <p>If full normalization requires network activity or is otherwise impossible to do without a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization.</p> <p>If the URI has extra information beyond what's necessary to identify a particular contact, such as an XMPP resource or an action to carry out, this extra information SHOULD be removed. If all URIs in a scheme contain a verb or action (like <code>aim</code>, <code>ymsgr</code> and <code>msnim</code> URIs), then the verb SHOULD be replaced with the one specified in <tp:member-ref>AddressableURISchemes</tp:member-ref>.</p> <tp:rationale> <p>This method is intended to normalize URIs stored in address books, for instance. In protocols like XMPP, if you vary the resource or action (query string), the URI still refers to the same high-level contact.</p> </tp:rationale> <p>For instance, <code>xmpp:romeoExample.Com /Empathy?message;body=Hello</code> would be normalized to <code>xmpp:romeoexample.com </code>, and <code>aim:goim?screenname=Romeo20M&amp;message=Hello</code> would be normalized to <code>aim:addbuddy?screenname=romeom</code>.</p> <p>This method MAY simply raise NotImplemented on some protocols, if it has no use.</p>

Parameters

proxy

the TpProxy

 

timeout_ms

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

 

in_URI

Used to pass an 'in' argument: <p>The URI to normalize, which is assumed to refer to a contact (as opposed to, for instance, a chatroom or a server).</p> <tp:rationale> <p>In some protocols, like XMPP, there is no way to tell whether a given URI refers to a contact or a chatroom by looking at its syntax.</p> </tp:rationale> <p>The URI's scheme (i.e. the part before the first colon) MUST appear in <tp:member-ref>AddressableURISchemes</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_protocol_interface_addressing_call_normalize_vcard_address ()

TpProxyPendingCall *
tp_cli_protocol_interface_addressing_call_normalize_vcard_address
                               (gpointer proxy,
                                gint timeout_ms,
                                const gchar *in_VCard_Field,
                                const gchar *in_VCard_Address,
                                tp_cli_protocol_interface_addressing_callback_for_normalize_vcard_address callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a NormalizeVCardAddress method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Attempt to normalize the given vCard address. Where possible, this SHOULD return an address that would appear in the <code>org.freedesktop.Telepathy.Connection.Interface.Addressing1/addresses</code> attribute for a contact on a connected <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. </p> <p>If full normalization requires network activity or is otherwise impossible to do without a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, this method SHOULD perform a best-effort normalization.</p> <p>An example would be a vCard TEL field with a formatted number in the form of <code>+1 (206) 555 1234</code>, this would be normalized to <code>+12065551234</code>.</p> <p>This method MAY simply raise NotImplemented on some protocols, if it has no use.</p>

Parameters

proxy

the TpProxy

 

timeout_ms

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

 

in_VCard_Field

Used to pass an 'in' argument: The vCard field of the address we are normalizing. The field name SHOULD be in lower case, and MUST appear in <tp:member-ref>AddressableVCardFields</tp:member-ref>.

 

in_VCard_Address

Used to pass an 'in' argument: The address to normalize, which is assumed to belong to a contact (and not, for instance, a chatroom or server).

 

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

void
(*tp_cli_protocol_interface_addressing_callback_for_normalize_contact_uri)
                               (TpProxy *proxy,
                                const gchar *out_Normalized_URI,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy

the proxy on which the call was made

 

out_Normalized_URI

Used to return an 'out' argument if error is NULL: A URI, normalized as much as possible.

 

error

NULL on success, or an error on failure

 

user_data

user-supplied data

 

weak_object

user-supplied object

 

tp_cli_protocol_interface_addressing_callback_for_normalize_vcard_address ()

void
(*tp_cli_protocol_interface_addressing_callback_for_normalize_vcard_address)
                               (TpProxy *proxy,
                                const gchar *out_Normalized_VCard_Address,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

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

Parameters

proxy

the proxy on which the call was made

 

out_Normalized_VCard_Address

Used to return an 'out' argument if error is NULL: The vCard address, normalized as much as possible.

 

error

NULL on success, or an error on failure

 

user_data

user-supplied data

 

weak_object

user-supplied object

 

Types and Values

struct TpProtocol

struct TpProtocol;

A base class for connection managers' protocols.

Since: 0.11.11


TpProtocolClass

typedef struct _TpProtocolClass TpProtocolClass;

The class of a TpProtocol.

Since: 0.11.11


TP_PROTOCOL_FEATURE_PARAMETERS

#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


TP_PROTOCOL_FEATURE_CORE

#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:

  • possible parameters for connections to this protocol
  • interfaces expected on connections to this protocol
  • classes of channel that could be requested from connections to this protocol

(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

Property Details

The “addressable-uri-schemes” property

  “addressable-uri-schemes”  GStrv

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

Owner: TpProtocol

Flags: Read

Since: 0.23.1


The “addressable-vcard-fields” property

  “addressable-vcard-fields” GStrv

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

Owner: TpProtocol

Flags: Read

Since: 0.23.1


The “authentication-types” property

  “authentication-types”     GStrv

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.

Owner: TpProtocol

Flags: Read

Since: 0.13.9


The “avatar-requirements” property

  “avatar-requirements”      gpointer

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.

Owner: TpProtocol

Flags: Read

Since: 0.15.6


The “capabilities” property

  “capabilities”             TpCapabilities *

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.

Owner: TpProtocol

Flags: Read

Since: 0.11.11


The “cm-name” property

  “cm-name”                  gchar *

The name of the connection manager this protocol is on.

Owner: TpProtocol

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.19.1


The “english-name” property

  “english-name”             gchar *

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.

Owner: TpProtocol

Flags: Read

Default value: NULL

Since: 0.11.11


The “icon-name” property

  “icon-name”                gchar *

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

Owner: TpProtocol

Flags: Read

Default value: NULL

Since: 0.11.11


The “param-names” property

  “param-names”              GStrv

A list of parameter names supported by this connection manager for this protocol, or NULL if TP_PROTOCOL_FEATURE_PARAMETERS has not been prepared.

Owner: TpProtocol

Flags: Read

Since: 0.11.11


The “protocol-name” property

  “protocol-name”            gchar *

The machine-readable name of the protocol, taken from the Telepathy D-Bus Interface Specification, such as "jabber" or "local-xmpp".

Owner: TpProtocol

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.11.11


The “protocol-properties” property

  “protocol-properties”      GHashTable_gchararray+GValue_*

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.

Owner: TpProtocol

Flags: Read / Write / Construct Only

Since: 0.11.11


The “protocol-properties-vardict” property

  “protocol-properties-vardict” GVariant *

The immutable properties of this Protocol, as provided at construction time. This is a G_VARIANT_TYPE_VARDICT GVariant, 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.

Owner: TpProtocol

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

Since: 0.23.3


The “vcard-field” property

  “vcard-field”              gchar *

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.

Owner: TpProtocol

Flags: Read

Default value: NULL

Since: 0.11.11

See Also

TpConnectionManager