TpBaseProtocol: telepathy-glib API Reference Manual

## TpBaseProtocol TpBaseProtocol — base class for TpSvcProtocol implementations |

## Functions

const gchar * | tp_base_protocol_get_name ()
GHashTable * | tp_base_protocol_get_immutable_properties ()
const TpCMParamSpec * | tp_base_protocol_get_parameters ()
const TpPresenceStatusSpec * | tp_base_protocol_get_statuses ()
TpBaseConnection * | tp_base_protocol_new_connection ()
const TpCMParamSpec * | (*TpBaseProtocolGetParametersFunc) ()
TpBaseConnection * | (*TpBaseProtocolNewConnectionFunc) ()
gchar * | (*TpBaseProtocolNormalizeContactFunc) ()
gchar * | (*TpBaseProtocolIdentifyAccountFunc) ()
GStrv | (*TpBaseProtocolGetInterfacesFunc) ()
void | (*TpBaseProtocolGetConnectionDetailsFunc) ()
void | (*TpBaseProtocolGetAvatarDetailsFunc) ()
GPtrArray * | (*TpBaseProtocolGetInterfacesArrayFunc) ()
GStrv | (*TpBaseProtocolDupSupportedVCardFieldsFunc) ()
GStrv | (*TpBaseProtocolDupSupportedURISchemesFunc) ()
gchar * | (*TpBaseProtocolNormalizeVCardAddressFunc) ()
gchar * | (*TpBaseProtocolNormalizeURIFunc) ()

## Properties

GHashTable_gchararray+GValue_* | immutable-properties | Read
char * | name | Read / Write / Construct Only

## Types and Values

struct | TpBaseProtocol
struct | TpBaseProtocolClass
struct | TpProtocolAddressingInterface

## Object Hierarchy

        GObject
        ╰── TpBaseProtocol

## Implemented Interfaces

TpBaseProtocol implements TpSvcDBusProperties, TpSvcProtocol, TpSvcProtocolInterfacePresence, TpSvcProtocolInterfaceAvatars and TpSvcProtocolInterfaceAddressing.

## Includes

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

## Description

Base class for Telepathy Protocol objects.

## Functions

### tp_base_protocol_get_name ()

    const gchar *
    tp_base_protocol_get_name (TpBaseProtocol *self);

[skip]

#### Parameters

self | a Protocol |

#### Returns

the value of “name”.

[transfer none]

Since: 0.11.11

### tp_base_protocol_get_immutable_properties ()

    GHashTable *
    tp_base_protocol_get_immutable_properties
                                   (TpBaseProtocol *self);

Return a basic set of immutable properties for this Protocol object, by using `tp_dbus_properties_mixin_make_properties_hash()`.

Additional keys and values can be inserted into the returned hash table; if this is done, the inserted keys and values will be freed when the hash table is destroyed. The keys must be allocated with `g_strdup()` or equivalent, and the values must be slice-allocated (for instance with `tp_g_value_slice_new_string()` or a similar function).

Note that in particular, `tp_asv_set_string()` and similar functions should not be used with this hash table.

#### Parameters

self | a Protocol |

#### Returns

a hash table mapping (gchar *) fully-qualified property names to GValues, which must be freed by the caller (at which point its contents will also be freed).

Since: 0.11.11

### tp_base_protocol_get_parameters ()

    const TpCMParamSpec *
    tp_base_protocol_get_parameters (TpBaseProtocol *self);

Returns the parameters supported by this protocol, as an array of structs which must remain valid at least as long as `self` exists (it will typically be a global static array).

#### Parameters

self | a Protocol object |

#### Returns

a description of the parameters supported by this protocol.

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

Since: 0.11.11

### tp_base_protocol_get_statuses ()

    const TpPresenceStatusSpec *
    tp_base_protocol_get_statuses (TpBaseProtocol *self);

Get the statuses supported by this object. Subclasses implement this via the TpBaseProtocolClass.get_statuses virtual method.

If the object does not implement the Protocol.Interface.Presences interface, it need not implement this virtual method.

#### Parameters

self | a Protocol object |

#### Returns

an array of TpPresenceStatusSpec structs describing the standard statuses supported by this protocol, with a final element whose name element is guaranteed to be `NULL`. The array must remain valid at least as long as `self` does.

Since: 0.13.5

### tp_base_protocol_new_connection ()

    TpBaseConnection *
    tp_base_protocol_new_connection (TpBaseProtocol *self,
                                     GHashTable *asv,
                                     GError **error);

Create a new connection using the TpBaseProtocolClass.get_parameters and TpBaseProtocolClass.new_connection implementations provided by a subclass. This is used to implement the `RequestConnection()` D-Bus method.

If the parameters in `asv` do not fit the result of `get_parameters` (unknown parameters are given, types are inappropriate, required parameters are not given, or a TpCMParamSpec.filter fails), then this method raises an error and `new_connection` is not called.

Otherwise, `new_connection` is called. Its `asv` argument is a copy of the `asv` given to this method, with default values for missing parameters filled in where available, and parameters' types converted to the GType specified by TpCMParamSpec.gtype.

#### Parameters

self | a Protocol object |
asv | the parameters provided via D-Bus. | [transfer none][element-type utf8 GObject.Value]
error | used to return an error if `NULL` is returned |

#### Returns

a new connection, or `NULL` on error

Since: 0.11.11

### TpBaseProtocolGetParametersFunc ()

    const TpCMParamSpec *
    (*TpBaseProtocolGetParametersFunc) (TpBaseProtocol *self);

Signature of a virtual method to get the allowed parameters for connections to a protocol.

Returns the parameters supported by this protocol, as an array of structs which must remain valid at least as long as `self` exists (it will typically be a global static array).

#### Parameters

self | a protocol |

#### Returns

a description of the parameters supported by this protocol.

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

Since: 0.11.11

### TpBaseProtocolNewConnectionFunc ()

    TpBaseConnection *
    (*TpBaseProtocolNewConnectionFunc) (TpBaseProtocol *self,
                                        GHashTable *asv,
                                        GError **error);

Signature of a virtual method to create a new connection to this protocol. This is used to implement the RequestConnection D-Bus method.

Implementations of TpBaseProtocolClass.new_connection may assume that the parameters in `asv` conform to the specifications given by TpBaseProtocolClass.get_parameters.

#### Parameters

self | a protocol |
asv | the parameters provided via D-Bus. | [transfer none][element-type utf8 GObject.Value]
error | used to return an error if `NULL` is returned |

#### Returns

a new connection, or `NULL` on error.

[transfer full]

Since: 0.11.11

### TpBaseProtocolNormalizeContactFunc ()

    gchar *
    (*TpBaseProtocolNormalizeContactFunc) (TpBaseProtocol *self,
                                           const gchar *contact,
                                           GError **error);

Signature of a virtual method to perform best-effort offline normalization of a contact's identifier. It must either return a newly allocated string that is the normalized form of `contact` , or raise an error and return `NULL`.

#### Parameters

self | a protocol |
contact | a contact's identifier |
error | used to return an error if `NULL` is returned |

#### Returns

a normalized identifier, or `NULL` on error.

[transfer full]

Since: 0.11.11

### TpBaseProtocolIdentifyAccountFunc ()

    gchar *
    (*TpBaseProtocolIdentifyAccountFunc) (TpBaseProtocol *self,
                                          GHashTable *asv,
                                          GError **error);

Signature of a virtual method to choose a unique name for an account whose connection parameters are `asv` . This will typically return a copy of the 'account' parameter from `asv` , but may do something more complex (for instance, on IRC it could combine the nickname and the IRC network).

Implementations of TpBaseProtocolClass.identify_account may assume that the parameters in `asv` conform to the specifications given by TpBaseProtocolClass.get_parameters.

#### Parameters

self | a protocol |
asv | parameters that might be passed to the RequestConnection D-Bus method |
error | used to return an error if `NULL` is returned |

#### Returns

a unique name for the account, or `NULL` on error.

[transfer full]

Since: 0.11.11

### TpBaseProtocolGetInterfacesFunc ()

    GStrv
    (*TpBaseProtocolGetInterfacesFunc) (TpBaseProtocol *self);

Signature of a virtual method to get the D-Bus interfaces implemented by `self` , in addition to the Protocol interface.

If you implement TpBaseProtocolClass.get_statuses, you should include `TP_IFACE_PROTOCOL_INTERFACE_PRESENCE` in the returned array.

#### Parameters

self | a protocol |

#### Returns

a `NULL`-terminated array of D-Bus interface names.

[transfer full]

Since: 0.11.11

### TpBaseProtocolGetConnectionDetailsFunc ()

    void
    (*TpBaseProtocolGetConnectionDetailsFunc)
                                   (TpBaseProtocol *self,
                                    GStrv *connection_interfaces,
                                    GType **channel_manager_types,
                                    gchar **icon_name,
                                    gchar **english_name,
                                    gchar **vcard_field);

Signature of a virtual method to get the D-Bus interfaces implemented by `self` , in addition to the Protocol interface.

#### Parameters

self | a protocol |
connection_interfaces | used to return a `NULL`-terminated array of interfaces which might be implemented on connections to this protocol. | [out][transfer full]
channel_manager_types | used to return a `G_TYPE_INVALID`-terminated array of types that implement TpChannelManager, which must include all channel managers that might be present on connections to this protocol; the channel managers should all implement TpChannelManagerIface.type_foreach_channel_class. The array will be freed with `g_free()` by the caller. | [out][transfer full][array zero-terminated=1]
icon_name | used to return the name of an icon for this protocol, such as "im-icq", or an empty string. | [out][transfer full]
english_name | used to return a human-readable but non-localized name for this protocol, or an empty string. | [out][transfer full]
vcard_field | used to return the name of the vCard field typically used with this protocol, or an empty string. | [out][transfer full]

Since: 0.11.11

### TpBaseProtocolGetAvatarDetailsFunc ()

    void
    (*TpBaseProtocolGetAvatarDetailsFunc) (TpBaseProtocol *self,
                                           GStrv *supported_mime_types,
                                           guint *min_height,
                                           guint *min_width,
                                           guint *rec_height,
                                           guint *rec_width,
                                           guint *max_height,
                                           guint *max_width,
                                           guint *max_bytes);

Signature of a virtual method to get the supported avatar details for the protocol implemented by `self` .

#### Parameters

self | a protocol |
supported_mime_types | used to return a `NULL`-terminated array of supported avatar mime types. | [out][transfer full]
min_height | used to return the minimum height in pixels of an avatar on this protocol, which may be 0. | [out]
min_width | used to return the minimum width in pixels of an avatar on this protocol, which may be 0. | [out]
rec_height | used to return the rec height in pixels of an avatar on this protocol, or 0 if there is no preferred height. | [out]
rec_width | used to return the rec width in pixels of an avatar on this protocol, or 0 if there is no preferred width. | [out]
max_height | used to return the maximum height in pixels of an avatar on this protocol, or 0 if there is no limit. | [out]
max_width | used to return the maximum width in pixels of an avatar on this protocol, or 0 if there is no limit. | [out]
max_bytes | used to return the maximum size in bytes of an avatar on this protocol, or 0 if there is no limit. | [out]

Since: 0.13.7

### TpBaseProtocolGetInterfacesArrayFunc ()

    GPtrArray *
    (*TpBaseProtocolGetInterfacesArrayFunc)
                                   (TpBaseProtocol *self);

Signature of an implementation of TpBaseProtocolClass.get_interfaces_array virtual function.

Implementation must first chainup on parent class implementation and then add extra interfaces into the GPtrArray.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    static GPtrArray *
    my_protocol_get_interfaces_array (TpBaseProtocol *self)
    {
      GPtrArray *interfaces;

      interfaces = TP_BASE_PROTOCOL_CLASS (
          my_protocol_parent_class)->get_interfaces_array (self);

      g_ptr_array_add (interfaces, TP_IFACE_BADGERS);

      return interfaces;
    }

#### Parameters

self | a TpBaseProtocol |

#### Returns

a GPtrArray of static strings for D-Bus interfaces implemented by this client.

[transfer container]

Since: 0.19.4

### TpBaseProtocolDupSupportedVCardFieldsFunc ()

    GStrv
    (*TpBaseProtocolDupSupportedVCardFieldsFunc)
                                   (TpBaseProtocol *self);

Signature of a virtual method to get the supported vCard fields supported by self.

#### Parameters

self | a protocol |

#### Returns

a list of vCard fields in lower case, e.g. [x-sip, tel].

[allow-none][out][transfer full]

Since: 0.17.2

### TpBaseProtocolDupSupportedURISchemesFunc ()

    GStrv
    (*TpBaseProtocolDupSupportedURISchemesFunc)
                                   (TpBaseProtocol *self);

Signature of a virtual method to get the supported URI schemes supported by self.

#### Parameters

self | a protocol |

#### Returns

a list of uri schemes, e.g. [sip, sips, tel].

[allow-none][out][transfer full]

Since: 0.17.2

### TpBaseProtocolNormalizeVCardAddressFunc ()

    gchar *
    (*TpBaseProtocolNormalizeVCardAddressFunc)
                                   (TpBaseProtocol *self,
                                    const gchar *vcard_field,
                                    const gchar *vcard_address,
                                    GError **error);

Signature of a virtual method to perform best-effort offline normalization of a vCard address. It must either return a newly allocated string that is the normalized form of `vcard_address` , or raise an error and return `NULL`.

#### Parameters

self | a protocol |
vcard_field | The vCard field of the address to be normalized. |
vcard_address | The address to normalize. |
error | used to return an error if `NULL` is returned |

#### Returns

a normalized identifier, or `NULL` on error.

[transfer full]

Since: 0.17.2

### TpBaseProtocolNormalizeURIFunc ()

    gchar *
    (*TpBaseProtocolNormalizeURIFunc) (TpBaseProtocol *self,
                                       const gchar *uri,
                                       GError **error);

Signature of a virtual method to perform best-effort offline normalization of a URI. It must either return a newly allocated string that is the normalized form of `uri` , or raise an error and return `NULL`.

#### Parameters

self | a protocol |
uri | The URI to normalize. |
error | used to return an error if `NULL` is returned |

#### Returns

a normalized identifier, or `NULL` on error.

[transfer full]

Since: 0.13.11

## Types and Values

### struct TpBaseProtocol

    struct TpBaseProtocol;

An object providing static details of the implementation of one real-time communications protocol.

Since: 0.11.11

### struct TpBaseProtocolClass

    struct TpBaseProtocolClass {
      GObjectClass parent_class;
      TpDBusPropertiesMixinClass dbus_properties_class;

      gboolean is_stub;
      const TpCMParamSpec *(*get_parameters) (TpBaseProtocol *self);
      TpBaseConnection *(*new_connection) (TpBaseProtocol *self,
          GHashTable *asv,
          GError **error);

      gchar *(*normalize_contact) (TpBaseProtocol *self,
          const gchar *contact,
          GError **error);
      gchar *(*identify_account) (TpBaseProtocol *self,
          GHashTable *asv,
          GError **error);

      void (*get_connection_details) (TpBaseProtocol *self,
          GStrv *connection_interfaces,
          GType **channel_manager_types,
          gchar **icon_name,
          gchar **english_name,
          gchar **vcard_field);

      const TpPresenceStatusSpec * (*get_statuses) (TpBaseProtocol *self);

      TpBaseProtocolGetAvatarDetailsFunc get_avatar_details;

      GStrv (*dup_authentication_types) (TpBaseProtocol *self);

      TpBaseProtocolGetInterfacesArrayFunc get_interfaces_array;
    };

The class of a TpBaseProtocol.

#### Members

TpDBusPropertiesMixinClass `dbus_properties_class`; | a D-Bus properties mixin |
gboolean `is_stub`; | if `TRUE`, this protocol will not be advertised on D-Bus (for internal use by TpBaseConnection) |
`get_parameters` () | a callback used to implement `tp_base_protocol_get_parameters()`, which all subclasses must provide; see the documentation of that method for details |
`new_connection` () | a callback used to implement `tp_base_protocol_new_connection()`, which all subclasses must provide; see the documentation of that method for details |
`normalize_contact` () | a callback used to implement the NormalizeContact D-Bus method; it must either return a newly allocated string that is the normalized version of `contact` , or raise an error via `error` and return `NULL`. If not implemented, `TP_ERROR_NOT_IMPLEMENTED` will be raised instead. |
`identify_account` () | a callback used to implement the IdentifyAccount D-Bus method; it takes as input a map from strings to GValues, and must either return a newly allocated string that represents the "identity" of the parameters in `asv` (usually the "account" parameter), or `NULL` with an error raised via `error` |
`get_connection_details` () | a callback used to implement the Protocol D-Bus properties that represent details of the connections provided by this protocol |
`get_statuses` () | a callback used to implement the Protocol.Interface.Presence interface's Statuses property. Since 0.13.5 |
TpBaseProtocolGetAvatarDetailsFunc `get_avatar_details`; | a callback used to implement the Protocol.Interface.Avatars interface's properties. Since 0.13.7 |
`dup_authentication_types` () | a callback used to implement the AuthenticationTypes D-Bus property; it must return a newly allocated GStrv containing D-Bus interface names. Since 0.13.9 |
TpBaseProtocolGetInterfacesArrayFunc `get_interfaces_array`; | a callback used to implement the Interfaces D-Bus property; The implementation must first chainup to parent class implementation and then add extra interfaces to the GPtrArray. Replaces `get_interfaces` |

Since: 0.11.11

### struct TpProtocolAddressingInterface

    struct TpProtocolAddressingInterface {
      GTypeInterface parent;

      TpBaseProtocolDupSupportedVCardFieldsFunc dup_supported_vcard_fields;

      TpBaseProtocolDupSupportedURISchemesFunc dup_supported_uri_schemes;

      TpBaseProtocolNormalizeVCardAddressFunc normalize_vcard_address;

      TpBaseProtocolNormalizeURIFunc normalize_contact_uri;
    };

The interface vtable for a `TP_TYPE_PROTOCOL_ADDRESSING`.

#### Members

GTypeInterface `parent`; | the parent interface |
TpBaseProtocolDupSupportedVCardFieldsFunc `dup_supported_vcard_fields`; | provides the supported vCard fields. Must always be implemented. |
TpBaseProtocolDupSupportedURISchemesFunc `dup_supported_uri_schemes`; | provides the supported URI schemes. Must always be implemented. |
TpBaseProtocolNormalizeVCardAddressFunc `normalize_vcard_address`; | protocol-specific implementation for normalizing vCard addresses. |
TpBaseProtocolNormalizeURIFunc `normalize_contact_uri`; | protocol-specific implementation for normalizing contact URIs. |

Since: 0.17.2

## Property Details

### The `“immutable-properties”` property

      “immutable-properties”     GHashTable_gchararray+GValue_*

The D-Bus properties to be announced in the ConnectionManager interface's Protocols property, as a map from interface.name.propertyname to GValue.

A protocol's immutable properties are constant for its lifetime on the bus, so this property should never change. All of the D-Bus properties mentioned here should also be exposed through the D-Bus properties interface.

The TpBaseProtocol base class implements this property to be correct for the basic set of properties. It can be reimplemented by subclasses to have more immutable properties; if so, the subclass should use `tp_base_protocol_get_immutable_properties()`, then augment the result using `tp_dbus_properties_mixin_fill_properties_hash()`.

Owner: TpBaseProtocol

Flags: Read

Since: 0.11.11

### The `“name”` property

      “name”                     char *

The Protocol from telepathy-spec, such as 'jabber' or 'local-xmpp'.

Owner: TpBaseProtocol

Flags: Read / Write / Construct Only

Default value: NULL

## See Also

TpBaseConnectionManager, TpSvcProtocol