TpBaseProtocol

TpBaseProtocol — base class for TpSvcProtocol implementations

Functions

Properties

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

Types and Values

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”                     gchar *

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