|  |  |  | telepathy-glib API Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Implemented Interfaces | Properties | ||||
| TpBaseProtocolTpBaseProtocol — base class for TpSvcProtocol implementations | 
#include <telepathy-glib/telepathy-glib.h> struct 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); const TpPresenceStatusSpec * tp_base_protocol_get_statuses (TpBaseProtocol *self); TpBaseConnection * tp_base_protocol_new_connection (TpBaseProtocol *self,GHashTable *asv,GError **error); struct 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); 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); GPtrArray * (*TpBaseProtocolGetInterfacesArrayFunc) (TpBaseProtocol *self); struct TpProtocolAddressingInterface; GStrv (*TpBaseProtocolDupSupportedVCardFieldsFunc) (TpBaseProtocol *self); GStrv (*TpBaseProtocolDupSupportedURISchemesFunc) (TpBaseProtocol *self); gchar * (*TpBaseProtocolNormalizeVCardAddressFunc) (TpBaseProtocol *self,const gchar *vcard_field,const gchar *vcard_address,GError **error); gchar * (*TpBaseProtocolNormalizeURIFunc) (TpBaseProtocol *self,const gchar *uri,GError **error);
TpBaseProtocol implements TpSvcDBusProperties, TpSvcProtocol, TpSvcProtocolInterfacePresence, TpSvcProtocolInterfaceAvatars and TpSvcProtocolInterfaceAddressing.
"immutable-properties" GHashTable_gchararray+GValue_* : Read "name" gchar* : Read / Write / Construct Only
struct TpBaseProtocol;
An object providing static details of the implementation of one real-time communications protocol.
Since 0.11.11
const gchar *       tp_base_protocol_get_name           (TpBaseProtocol *self);
| 
 | a Protocol | 
| Returns : | the value of "name". [transfer none] | 
Since 0.11.11
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.
| 
 | 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
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).
| 
 | a Protocol object | 
| Returns : | a description of the parameters supported by this protocol. [transfer none][array zero-terminated=1] | 
Since 0.11.11
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.
| 
 | 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 asselfdoes. | 
Since 0.13.5
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.
| 
 | a Protocol object | 
| 
 | the parameters provided via D-Bus. [transfer none][element-type utf8 GObject.Value] | 
| 
 | used to return an error if NULLis returned | 
| Returns : | a new connection, or NULLon error | 
Since 0.11.11
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.
| GObjectClass  | the parent class | 
| TpDBusPropertiesMixinClass  | a D-Bus properties mixin | 
| gboolean  | if TRUE, this protocol will not be advertised on D-Bus (for
internal use by TpBaseConnection) | 
| a callback used to implement tp_base_protocol_get_parameters(), which all subclasses must provide;
see the documentation of that method for details | |
| a callback used to implement tp_base_protocol_new_connection(), which all subclasses must provide;
see the documentation of that method for details | |
| 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 viaerrorand
returnNULL. If not implemented,TP_ERROR_NOT_IMPLEMENTEDwill be raised
instead. | |
| 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),
orNULLwith an error raised viaerror | |
| a callback used to implement the Protocol D-Bus properties that represent details of the connections provided by this protocol | |
| a callback used to implement the Protocol.Interface.Presence interface's Statuses property. Since 0.13.5 | |
| TpBaseProtocolGetAvatarDetailsFunc  | a callback used to implement the Protocol.Interface.Avatars interface's properties. Since 0.13.7 | 
| 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  | 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
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).
| 
 | a protocol | 
| Returns : | a description of the parameters supported by this protocol. [transfer none][array zero-terminated=1] | 
Since 0.11.11
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.
| 
 | a protocol | 
| 
 | the parameters provided via D-Bus. [transfer none][element-type utf8 GObject.Value] | 
| 
 | used to return an error if NULLis returned | 
| Returns : | a new connection, or NULLon error. [transfer full] | 
Since 0.11.11
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.
| 
 | a protocol | 
| 
 | a contact's identifier | 
| 
 | used to return an error if NULLis returned | 
| Returns : | a normalized identifier, or NULLon error. [transfer full] | 
Since 0.11.11
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.
| 
 | a protocol | 
| 
 | parameters that might be passed to the RequestConnection D-Bus method | 
| 
 | used to return an error if NULLis returned | 
| Returns : | a unique name for the account, or NULLon error. [transfer full] | 
Since 0.11.11
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.
| 
 | a protocol | 
| Returns : | a NULL-terminated array of D-Bus interface names. [transfer full] | 
Since 0.11.11
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.
| 
 | a protocol | 
| 
 | used to return a NULL-terminated array of interfaces which might be implemented on
connections to this protocol. [out][transfer full] | 
| 
 | 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 withg_free()by the caller. [out][transfer full][array zero-terminated=1] | 
| 
 | used to return the name of an icon for this protocol, such as "im-icq", or an empty string. [out][transfer full] | 
| 
 | used to return a human-readable but non-localized name for this protocol, or an empty string. [out][transfer full] | 
| 
 | 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
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.
| 
 | a protocol | 
| 
 | used to return a NULL-terminated array of supported avatar mime types. [out][transfer full] | 
| 
 | used to return the minimum height in pixels of an avatar on this protocol, which may be 0. [out] | 
| 
 | used to return the minimum width in pixels of an avatar on this protocol, which may be 0. [out] | 
| 
 | used to return the rec height in pixels of an avatar on this protocol, or 0 if there is no preferred height. [out] | 
| 
 | used to return the rec width in pixels of an avatar on this protocol, or 0 if there is no preferred width. [out] | 
| 
 | used to return the maximum height in pixels of an avatar on this protocol, or 0 if there is no limit. [out] | 
| 
 | used to return the maximum width in pixels of an avatar on this protocol, or 0 if there is no limit. [out] | 
| 
 | 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
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; } | 
| 
 | a TpBaseProtocol | 
| Returns : | a GPtrArray of static strings for D-Bus interfaces implemented by this client. [transfer container] | 
Since 0.19.4
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.
| GTypeInterface  | the parent interface | 
| TpBaseProtocolDupSupportedVCardFieldsFunc  | provides the supported vCard fields. Must always be implemented. | 
| TpBaseProtocolDupSupportedURISchemesFunc  | provides the supported URI schemes. Must always be implemented. | 
| TpBaseProtocolNormalizeVCardAddressFunc  | protocol-specific implementation for normalizing vCard addresses. | 
| TpBaseProtocolNormalizeURIFunc  | protocol-specific implementation for normalizing contact URIs. | 
Since 0.17.2
GStrv               (*TpBaseProtocolDupSupportedVCardFieldsFunc)
                                                        (TpBaseProtocol *self);
Signature of a virtual method to get the supported vCard fields supported by 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
GStrv               (*TpBaseProtocolDupSupportedURISchemesFunc)
                                                        (TpBaseProtocol *self);
Signature of a virtual method to get the supported URI schemes supported by self.
| 
 | a protocol | 
| Returns : | a list of uri schemes, e.g. [sip, sips, tel]. [allow-none][out][transfer full] | 
Since 0.17.2
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.
| 
 | a protocol | 
| 
 | The vCard field of the address to be normalized. | 
| 
 | The address to normalize. | 
| 
 | used to return an error if NULLis returned | 
| Returns : | a normalized identifier, or NULLon error. [transfer full] | 
Since 0.17.2
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.
| 
 | a protocol | 
| 
 | The URI to normalize. | 
| 
 | used to return an error if NULLis returned | 
| Returns : | a normalized identifier, or NULLon error. [transfer full] | 
Since 0.13.11
"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
"name" property"name" gchar* : Read / Write / Construct Only
The Protocol from telepathy-spec, such as 'jabber' or 'local-xmpp'.
Default value: NULL