TpSimpleClientFactory

TpSimpleClientFactory — a factory for TpContacts and plain subclasses of TpProxy

Synopsis

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

                    TpSimpleClientFactory;
struct              TpSimpleClientFactoryClass;
TpSimpleClientFactory * tp_simple_client_factory_new    (TpDBusDaemon *dbus);
TpDBusDaemon *      tp_simple_client_factory_get_dbus_daemon
                                                        (TpSimpleClientFactory *self);

TpAccount *         tp_simple_client_factory_ensure_account
                                                        (TpSimpleClientFactory *self,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);
GArray *            tp_simple_client_factory_dup_account_features
                                                        (TpSimpleClientFactory *self,
                                                         TpAccount *account);
void                tp_simple_client_factory_add_account_features
                                                        (TpSimpleClientFactory *self,
                                                         const GQuark *features);
void                tp_simple_client_factory_add_account_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         GQuark feature,
                                                         ...);

TpConnection *      tp_simple_client_factory_ensure_connection
                                                        (TpSimpleClientFactory *self,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);
GArray *            tp_simple_client_factory_dup_connection_features
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection);
void                tp_simple_client_factory_add_connection_features
                                                        (TpSimpleClientFactory *self,
                                                         const GQuark *features);
void                tp_simple_client_factory_add_connection_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         GQuark feature,
                                                         ...);

TpChannel *         tp_simple_client_factory_ensure_channel
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);
GArray *            tp_simple_client_factory_dup_channel_features
                                                        (TpSimpleClientFactory *self,
                                                         TpChannel *channel);
void                tp_simple_client_factory_add_channel_features
                                                        (TpSimpleClientFactory *self,
                                                         const GQuark *features);
void                tp_simple_client_factory_add_channel_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         GQuark feature,
                                                         ...);

TpContact *         tp_simple_client_factory_ensure_contact
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         TpHandle handle,
                                                         const gchar *identifier);
void                tp_simple_client_factory_upgrade_contacts_async
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_simple_client_factory_upgrade_contacts_finish
                                                        (TpSimpleClientFactory *self,
                                                         GAsyncResult *result,
                                                         GPtrArray **contacts,
                                                         GError **error);
void                tp_simple_client_factory_ensure_contact_by_id_async
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         const gchar *identifier,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
TpContact *         tp_simple_client_factory_ensure_contact_by_id_finish
                                                        (TpSimpleClientFactory *self,
                                                         GAsyncResult *result,
                                                         GError **error);
GArray *            tp_simple_client_factory_dup_contact_features
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection);
void                tp_simple_client_factory_add_contact_features
                                                        (TpSimpleClientFactory *self,
                                                         guint n_features,
                                                         const TpContactFeature *features);
void                tp_simple_client_factory_add_contact_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         TpContactFeature feature,
                                                         ...);

Object Hierarchy

  GObject
   +----TpSimpleClientFactory
         +----TpAutomaticClientFactory

Properties

  "dbus-daemon"              TpDBusDaemon*         : Read / Write / Construct Only

Description

This factory constructs various TpProxy subclasses as well as TpContact, which guarantees that at most one instance of those objects will exist for a given remote object or contact. It also stores the desired features for contacts and each type of proxy.

Note that the factory will not prepare the desired features: it is the caller's responsibility to do so. By default, only core features are requested.

Currently supported classes are TpAccount, TpConnection, TpChannel and TpContact. Those objects should always be acquired through a factory or a "larger" object (e.g. getting the TpConnection from a TpAccount), rather than being constructed directly.

One can subclass TpSimpleClientFactory and override some of its virtual methods to construct more specialized objects. See TpAutomaticClientFactory for a subclass which automatically constructs subclasses of TpChannel for common channel types.

An application using its own factory subclass would look like this: 

1
2
3
4
5
6
7
8
9
10
11
12
13
 
int main(int argc, char *argv[])
{
  TpSimpleClientFactory *factory;
  TpAccountManager *manager;

  factory = my_factory_new ();
  manager = tp_account_manager_new_with_factory (factory);
  tp_account_manager_set_default (manager);

  ...
  tp_proxy_prepare_async (manager, am_features, callback, user_data);
  ...
}

The call to tp_account_manager_set_default() near the beginning of main() will ensure that any libraries or plugins which also use Telepathy (and call tp_account_manager_dup()) will share your TpAccountManager.

Details

TpSimpleClientFactory

typedef struct _TpSimpleClientFactory TpSimpleClientFactory;

Data structure representing a TpSimpleClientFactory

Since 0.15.5

struct TpSimpleClientFactoryClass

struct TpSimpleClientFactoryClass {
    GObjectClass parent_class;

    /* TpAccount */
    TpAccount * (*create_account) (TpSimpleClientFactory *self,
        const gchar *object_path,
        const GHashTable *immutable_properties,
        GError **error);
    GArray * (*dup_account_features) (TpSimpleClientFactory *self,
        TpAccount *account);

    /* TpConnection */
    TpConnection * (*create_connection) (TpSimpleClientFactory *self,
        const gchar *object_path,
        const GHashTable *immutable_properties,
        GError **error);
    GArray * (*dup_connection_features) (TpSimpleClientFactory *self,
        TpConnection *connection);

    /* TpChannel */
    TpChannel * (*create_channel) (TpSimpleClientFactory *self,
        TpConnection *conn,
        const gchar *object_path,
        const GHashTable *immutable_properties,
        GError **error);
    GArray * (*dup_channel_features) (TpSimpleClientFactory *self,
        TpChannel *channel);

    /* TpContact */
    TpContact * (*create_contact) (TpSimpleClientFactory *self,
        TpConnection *connection,
        TpHandle handle,
        const gchar *identifier);
    GArray * (*dup_contact_features) (TpSimpleClientFactory *self,
        TpConnection *connection);
};

The class structure for TpSimpleClientFactory.

TpSimpleClientFactory maintains a cache of previously-constructed proxy objects, so the implementations of create_account, create_connection, create_channel, and create_contact may assume that a new object should be created when they are called. The default implementations create unadorned instances of the relevant classes; subclasses of the factory may choose to create more interesting proxy subclasses.

The default implementation of dup_channel_features returns TP_CHANNEL_FEATURE_CORE, plus all features passed to tp_simple_client_factory_add_channel_features() by the application. Subclasses may override this method to prepare more interesting features from subclasses of TpChannel, for instance. The default implementations of the other dup_x_features methods behave similarly.

GObjectClass parent_class;

 the parent

create_account ()

 create a TpAccount; see tp_simple_client_factory_ensure_account()

dup_account_features ()

 implementation of tp_simple_client_factory_dup_account_features()

create_connection ()

 create a TpConnection; see tp_simple_client_factory_ensure_connection()

dup_connection_features ()

 implementation of tp_simple_client_factory_dup_connection_features()

create_channel ()

 create a TpChannel; see tp_simple_client_factory_ensure_channel()

dup_channel_features ()

 implementation of tp_simple_client_factory_dup_channel_features()

create_contact ()

 create a TpContact; see tp_simple_client_factory_ensure_contact()

dup_contact_features ()

 implementation of tp_simple_client_factory_dup_contact_features()

Since 0.15.5

tp_simple_client_factory_new ()

TpSimpleClientFactory * tp_simple_client_factory_new    (TpDBusDaemon *dbus);

Creates a new TpSimpleClientFactory instance. If dbus is NULL, tp_dbus_daemon_dup() will be used.

dbus :

 a TpDBusDaemon, or NULL. [allow-none]

Returns :

 a new TpSimpleClientFactory

Since 0.15.5

tp_simple_client_factory_get_dbus_daemon ()

TpDBusDaemon *      tp_simple_client_factory_get_dbus_daemon
                                                        (TpSimpleClientFactory *self);

self :

 a TpSimpleClientFactory object

Returns :

 the value of the "dbus-daemon" property. [transfer none]

Since 0.15.5

tp_simple_client_factory_ensure_account ()

TpAccount *         tp_simple_client_factory_ensure_account
                                                        (TpSimpleClientFactory *self,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);

Returns a TpAccount proxy for the account at object_path. The returned TpAccount is cached; the same TpAccount object will be returned by this function repeatedly, as long as at least one reference exists.

Note that the returned TpAccount is not guaranteed to be ready; the caller is responsible for calling tp_proxy_prepare_async() with the desired features (as given by tp_simple_client_factory_dup_account_features()).

This function is rather low-level. tp_account_manager_dup_valid_accounts() and "validity-changed" are more appropriate for most applications.

self :

 a TpSimpleClientFactory object

object_path :

 the object path of an account

immutable_properties :

 the immutable properties of the account, or NULL. [transfer none][element-type utf8 GObject.Value]

error :

 Used to raise an error if object_path is not valid

Returns :

 a reference to a TpAccount; see tp_account_new(). [transfer full]

Since 0.15.5

tp_simple_client_factory_dup_account_features ()

GArray *            tp_simple_client_factory_dup_account_features
                                                        (TpSimpleClientFactory *self,
                                                         TpAccount *account);

Return a zero-terminated GArray containing the TpAccount features that should be prepared on account.

self :

 a TpSimpleClientFactory object

account :

 a TpAccount

Returns :

 a newly allocated GArray. [transfer full][element-type GLib.Quark]

Since 0.15.5

tp_simple_client_factory_add_account_features ()

void                tp_simple_client_factory_add_account_features
                                                        (TpSimpleClientFactory *self,
                                                         const GQuark *features);

Add features to the desired features to be prepared on TpAccount objects. Those features will be added to the features already returned be tp_simple_client_factory_dup_account_features().

It is not necessary to add TP_ACCOUNT_FEATURE_CORE as it is already included by default.

Note that these features will not be added to existing TpAccount objects; the user must call tp_proxy_prepare_async() themself.

self :

 a TpSimpleClientFactory object

features :

 an array of desired features, ending with 0; NULL is equivalent to an array containing only 0. [transfer none][array zero-terminated=1][allow-none]

Since 0.15.5

tp_simple_client_factory_add_account_features_varargs ()

void                tp_simple_client_factory_add_account_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         GQuark feature,
                                                         ...);

The same as tp_simple_client_factory_add_account_features(), but with a more convenient calling convention from C.

self :

 a TpSimpleClientFactory

feature :

 the first feature

... :

 the second and subsequent features, if any, ending with 0

Since 0.15.5

tp_simple_client_factory_ensure_connection ()

TpConnection *      tp_simple_client_factory_ensure_connection
                                                        (TpSimpleClientFactory *self,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);

Returns a TpConnection proxy for the connection at object_path. The returned TpConnection is cached; the same TpConnection object will be returned by this function repeatedly, as long as at least one reference exists.

Note that the returned TpConnection is not guaranteed to be ready; the caller is responsible for calling tp_proxy_prepare_async() with the desired features (as given by tp_simple_client_factory_dup_connection_features()).

This function is rather low-level. "connection" is more appropriate for most applications.

self :

 a TpSimpleClientFactory object

object_path :

 the object path of a connection

immutable_properties :

 the immutable properties of the connection. [transfer none][element-type utf8 GObject.Value]

error :

 Used to raise an error if object_path is not valid

Returns :

 a reference to a TpConnection; see tp_connection_new(). [transfer full]

Since 0.15.5

tp_simple_client_factory_dup_connection_features ()

GArray *            tp_simple_client_factory_dup_connection_features
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection);

Return a zero-terminated GArray containing the TpConnection features that should be prepared on connection.

self :

 a TpSimpleClientFactory object

connection :

 a TpConnection

Returns :

 a newly allocated GArray. [transfer full][element-type GLib.Quark]

Since 0.15.5

tp_simple_client_factory_add_connection_features ()

void                tp_simple_client_factory_add_connection_features
                                                        (TpSimpleClientFactory *self,
                                                         const GQuark *features);

Add features to the desired features to be prepared on TpConnection objects. Those features will be added to the features already returned be tp_simple_client_factory_dup_connection_features().

It is not necessary to add TP_CONNECTION_FEATURE_CORE as it is already included by default.

Note that these features will not be added to existing TpConnection objects; the user must call tp_proxy_prepare_async() themself.

self :

 a TpSimpleClientFactory object

features :

 an array of desired features, ending with 0; NULL is equivalent to an array containing only 0. [transfer none][array zero-terminated=1][allow-none]

Since 0.15.5

tp_simple_client_factory_add_connection_features_varargs ()

void                tp_simple_client_factory_add_connection_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         GQuark feature,
                                                         ...);

The same as tp_simple_client_factory_add_connection_features(), but with a more convenient calling convention from C.

self :

 a TpSimpleClientFactory

feature :

 the first feature

... :

 the second and subsequent features, if any, ending with 0

Since 0.15.5

tp_simple_client_factory_ensure_channel ()

TpChannel *         tp_simple_client_factory_ensure_channel
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         const gchar *object_path,
                                                         const GHashTable *immutable_properties,
                                                         GError **error);

Returns a TpChannel proxy for the channel at object_path on connection. The returned TpChannel is cached; the same TpChannel object will be returned by this function repeatedly, as long as at least one reference exists.

Note that the returned TpChannel is not guaranteed to be ready; the caller is responsible for calling tp_proxy_prepare_async() with the desired features (as given by tp_simple_client_factory_dup_channel_features()).

This function is rather low-level. TpAccountChannelRequest and TpBaseClient are more appropriate ways to obtain channels for most applications.

self :

 a TpSimpleClientFactory object

connection :

 a TpConnection whose "factory" is this object

object_path :

 the object path of a channel on connection

immutable_properties :

 the immutable properties of the channel. [transfer none][element-type utf8 GObject.Value]

error :

 Used to raise an error if object_path is not valid

Returns :

 a reference to a TpChannel; see tp_channel_new_from_properties(). [transfer full]

Since 0.15.5

tp_simple_client_factory_dup_channel_features ()

GArray *            tp_simple_client_factory_dup_channel_features
                                                        (TpSimpleClientFactory *self,
                                                         TpChannel *channel);

Return a zero-terminated GArray containing the TpChannel features that should be prepared on channel.

self :

 a TpSimpleClientFactory object

channel :

 a TpChannel

Returns :

 a newly allocated GArray. [transfer full][element-type GLib.Quark]

Since 0.15.5

tp_simple_client_factory_add_channel_features ()

void                tp_simple_client_factory_add_channel_features
                                                        (TpSimpleClientFactory *self,
                                                         const GQuark *features);

Add features to the desired features to be prepared on TpChannel objects. Those features will be added to the features already returned be tp_simple_client_factory_dup_channel_features().

It is not necessary to add TP_CHANNEL_FEATURE_CORE as it is already included by default.

Note that these features will not be added to existing TpChannel objects; the user must call tp_proxy_prepare_async() themself.

self :

 a TpSimpleClientFactory object

features :

 an array of desired features, ending with 0; NULL is equivalent to an array containing only 0. [transfer none][array zero-terminated=1][allow-none]

Since 0.15.5

tp_simple_client_factory_add_channel_features_varargs ()

void                tp_simple_client_factory_add_channel_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         GQuark feature,
                                                         ...);

The same as tp_simple_client_factory_add_channel_features(), but with a more convenient calling convention from C.

self :

 a TpSimpleClientFactory

feature :

 the first feature

... :

 the second and subsequent features, if any, ending with 0

Since 0.15.5

tp_simple_client_factory_ensure_contact ()

TpContact *         tp_simple_client_factory_ensure_contact
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         TpHandle handle,
                                                         const gchar *identifier);

Returns a TpContact representing identifier (and handle) on connection. The returned TpContact is cached; the same TpContact object will be returned by this function repeatedly, as long as at least one reference exists.

Note that the returned TpContact is not guaranteed to be ready; the caller is responsible for calling tp_connection_upgrade_contacts() with the desired features (as given by tp_simple_client_factory_dup_contact_features()).

For this function to work properly, tp_connection_has_immortal_handles() must return TRUE for connection.

self :

 a TpSimpleClientFactory object

connection :

 a TpConnection whose "factory" is this object

handle :

 a TpHandle

identifier :

 a string representing the contact's identifier

Returns :

 a reference to a TpContact. [transfer full]

Since 0.15.5

tp_simple_client_factory_upgrade_contacts_async ()

void                tp_simple_client_factory_upgrade_contacts_async
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         guint n_contacts,
                                                         TpContact * const *contacts,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Same as tp_connection_upgrade_contacts_async(), but prepare contacts with all features previously passed to tp_simple_client_factory_add_contact_features().

self :

 a TpSimpleClientFactory object

connection :

 a TpConnection whose "factory" is this object

n_contacts :

 The number of contacts in contacts (must be at least 1)

contacts :

 An array of TpContact objects associated with self. [array length=n_contacts]

callback :

 a callback to call when the operation finishes

user_data :

 data to pass to callback

Since 0.19.1

tp_simple_client_factory_upgrade_contacts_finish ()

gboolean            tp_simple_client_factory_upgrade_contacts_finish
                                                        (TpSimpleClientFactory *self,
                                                         GAsyncResult *result,
                                                         GPtrArray **contacts,
                                                         GError **error);

Finishes tp_simple_client_factory_upgrade_contacts_async()

self :

 a TpSimpleClientFactory

result :

 a GAsyncResult

contacts :

 a location to set a GPtrArray of upgraded TpContact, or NULL. [element-type TelepathyGLib.Contact][transfer container][out][allow-none]

error :

 a GError to fill

Returns :

 TRUE on success, FALSE otherwise.

Since 0.19.1

tp_simple_client_factory_ensure_contact_by_id_async ()

void                tp_simple_client_factory_ensure_contact_by_id_async
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection,
                                                         const gchar *identifier,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Same as tp_connection_dup_contact_by_id_async(), but prepare the contact with all features previously passed to tp_simple_client_factory_add_contact_features().

self :

 a TpSimpleClientFactory object

connection :

 a TpConnection

identifier :

 a string representing the contact's identifier

callback :

 a callback to call when the operation finishes

user_data :

 data to pass to callback

Since 0.19.1

tp_simple_client_factory_ensure_contact_by_id_finish ()

TpContact *         tp_simple_client_factory_ensure_contact_by_id_finish
                                                        (TpSimpleClientFactory *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes tp_simple_client_factory_ensure_contact_by_id_async()

self :

 a TpSimpleClientFactory

result :

 a GAsyncResult

error :

 a GError to fill

Returns :

 a TpContact or NULL on error. [transfer full]

Since 0.19.1

tp_simple_client_factory_dup_contact_features ()

GArray *            tp_simple_client_factory_dup_contact_features
                                                        (TpSimpleClientFactory *self,
                                                         TpConnection *connection);

Return a GArray containing the TpContactFeature that should be prepared on all contacts of connection.

self :

 a TpSimpleClientFactory object

connection :

 a TpConnection

Returns :

 a newly allocated GArray. [transfer full][element-type TelepathyGLib.ContactFeature]

Since 0.15.5

tp_simple_client_factory_add_contact_features ()

void                tp_simple_client_factory_add_contact_features
                                                        (TpSimpleClientFactory *self,
                                                         guint n_features,
                                                         const TpContactFeature *features);

Add features to the desired features to be prepared on TpContact objects. Those features will be added to the features already returned be tp_simple_client_factory_dup_contact_features().

Note that these features will not be added to existing TpContact objects; the user must call tp_connection_upgrade_contacts() themself.

self :

 a TpSimpleClientFactory object

n_features :

 The number of features in features (may be 0)

features :

 an array of desired features (may be NULL if n_features is 0). [array length=n_features][allow-none]

Since 0.15.5

tp_simple_client_factory_add_contact_features_varargs ()

void                tp_simple_client_factory_add_contact_features_varargs
                                                        (TpSimpleClientFactory *self,
                                                         TpContactFeature feature,
                                                         ...);

The same as tp_simple_client_factory_add_contact_features(), but with a more convenient calling convention from C.

self :

 a TpSimpleClientFactory

feature :

 the first feature

... :

 the second and subsequent features, if any, ending with TP_CONTACT_FEATURE_INVALID

Since 0.15.5

Property Details

The "dbus-daemon" property

  "dbus-daemon"              TpDBusDaemon*         : Read / Write / Construct Only

The D-Bus daemon for this object.

See Also

TpAutomaticClientFactory
Generated by GTK-Doc V1.19