## TpBaseProtocol TpBaseProtocol — base class for TpSvcProtocol implementations |

## Synopsis

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

                        TpBaseProtocol;
    const gchar *       tp_base_protocol_get_name           (TpBaseProtocol *self);
    GHashTable *        tp_base_protocol_get_immutable_properties
                                                            (TpBaseProtocol *self);
    const TpCMParamSpec * tp_base_protocol_get_parameters   (TpBaseProtocol *self);
    TpBaseConnection *  tp_base_protocol_new_connection     (TpBaseProtocol *self,
                                                             GHashTable *asv,
                                                             GError **error);

                        TpBaseProtocolClass;
    const TpCMParamSpec * (*TpBaseProtocolGetParametersFunc)
                                                            (TpBaseProtocol *self);
    TpBaseConnection *  (*TpBaseProtocolNewConnectionFunc)  (TpBaseProtocol *self,
                                                             GHashTable *asv,
                                                             GError **error);
    gchar *             (*TpBaseProtocolNormalizeContactFunc)
                                                            (TpBaseProtocol *self,
                                                             const gchar *contact,
                                                             GError **error);
    gchar *             (*TpBaseProtocolIdentifyAccountFunc)
                                                            (TpBaseProtocol *self,
                                                             GHashTable *asv,
                                                             GError **error);
    GStrv               (*TpBaseProtocolGetInterfacesFunc)  (TpBaseProtocol *self);
    void                (*TpBaseProtocolGetConnectionDetailsFunc)
                                                            (TpBaseProtocol *self,
                                                             GStrv *connection_interfaces,
                                                             GType **channel_manager_types,
                                                             gchar **icon_name,
                                                             gchar **english_name,
                                                             gchar **vcard_field);

## Object Hierarchy

      GObject
       +----TpBaseProtocol

## Implemented Interfaces

TpBaseProtocol implements TpSvcDBusProperties and TpSvcProtocol.

## Properties

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

## Description

Base class for Telepathy Protocol objects.

## Details

### TpBaseProtocol

    typedef struct _TpBaseProtocol TpBaseProtocol;

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

Since 0.11.11

### tp_base_protocol_get_name ()

    const gchar *       tp_base_protocol_get_name           (TpBaseProtocol *self);

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

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

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

`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

### TpBaseProtocolClass

    typedef struct {
      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);

      GStrv (*get_interfaces) (TpBaseProtocol *self);

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

The class of a TpBaseProtocol.

GObjectClass `parent_class`; | the parent class
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_interfaces` () | a callback used to implement the Interfaces D-Bus property; it must return a newly allocated GStrv containing D-Bus interface names
`get_connection_details` () | a callback used to implement the Protocol D-Bus properties that represent details of the connections provided by this protocol

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

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

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

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

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

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

`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

## Property Details

### The `"immutable-properties"` property

      "immutable-properties"     GHashTable_gchararray+GValue_*  : Read

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

Since 0.11.11

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

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

Default value: NULL

## See Also

TpBaseConnectionManager, TpSvcProtocol