TpSimpleClientFactory

## 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