## TpProtocol

TpProtocol — proxy for a Telepathy Protocol object

## Synopsis

    #include <telepathy-glib/protocol.h>

                        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);
    void                tp_protocol_init_known_interfaces   (void);

    #define             TP_PROTOCOL_FEATURE_PARAMETERS
    GStrv               tp_protocol_dup_param_names         (TpProtocol *self);
    const TpConnectionManagerParam * tp_protocol_get_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);

    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);
    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);
    void                (*tp_cli_protocol_callback_for_identify_account)
                                                            (TpProxy *proxy,
                                                             const gchar *out_Account_ID,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    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);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpProtocol

## Properties

      "capabilities"             TpCapabilities*       : Read
      "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

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

## Details

### TpProtocol

    typedef struct _TpProtocol 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_new ()

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

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

`self` : | a protocol object
Returns : | the value of the "protocol-name" property

Since 0.11.11

### 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_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_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()`.

`self` : | a protocol
Returns : | a copy of "param-names". [type GObject.Strv][transfer full]

Since 0.11.11

### tp_protocol_get_param ()

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

`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_has_param ()

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

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

`self` : | a protocol
Returns : | `TRUE` if `protocol` supports the parameter "register"

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

### tp_protocol_get_capabilities ()

    TpCapabilities *    tp_protocol_get_capabilities        (TpProtocol *self);

`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);

`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);

`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);

`self` : | a protocol object
Returns : | the value of "vcard-field"

Since 0.11.11

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

`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 alice`example.com`/Empathy should normalize to alice`example.com`, but the in-MUC JID wonderland`conference.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>

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

`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 'me`example.com`' with 'server' set to either jabber1.example.com or jabber2.example.com. Both of these should result in me`example.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.

`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

## Property Details

### The `"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

### The `"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

### The `"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 "name".

Default value: NULL

Since 0.11.11

### The `"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

### The `"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

### The `"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

### The `"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

## See Also

TpConnectionManager