|  |  |  | telepathy-glib API Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | ||||
| TpSimpleClientFactoryTpSimpleClientFactory — a factory for TpContacts and plain subclasses of TpProxy | 
#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,
                                                         ...);
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.
typedef struct _TpSimpleClientFactory TpSimpleClientFactory;
Data structure representing a TpSimpleClientFactory
Since 0.15.5
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  | the parent | 
| create a TpAccount;
see tp_simple_client_factory_ensure_account() | |
| implementation of tp_simple_client_factory_dup_account_features() | |
| create a TpConnection;
see tp_simple_client_factory_ensure_connection() | |
| implementation of tp_simple_client_factory_dup_connection_features() | |
| create a TpChannel;
see tp_simple_client_factory_ensure_channel() | |
| implementation of tp_simple_client_factory_dup_channel_features() | |
| create a TpContact;
see tp_simple_client_factory_ensure_contact() | |
| implementation of tp_simple_client_factory_dup_contact_features() | 
Since 0.15.5
TpSimpleClientFactory * tp_simple_client_factory_new    (TpDBusDaemon *dbus);
Creates a new TpSimpleClientFactory instance. If dbus is NULL,
tp_dbus_daemon_dup() will be used.
| 
 | a TpDBusDaemon, or NULL. [allow-none] | 
| Returns : | a new TpSimpleClientFactory | 
Since 0.15.5
TpDBusDaemon *      tp_simple_client_factory_get_dbus_daemon
                                                        (TpSimpleClientFactory *self);
| 
 | a TpSimpleClientFactory object | 
| Returns : | the value of the "dbus-daemon" property. [transfer none] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | the object path of an account | 
| 
 | the immutable properties of the account, or NULL. [transfer none][element-type utf8 GObject.Value] | 
| 
 | Used to raise an error if object_pathis not valid | 
| Returns : | a reference to a TpAccount;
see tp_account_new(). [transfer full] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpAccount | 
| Returns : | a newly allocated GArray. [transfer full][element-type GLib.Quark] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | an array
of desired features, ending with 0; NULLis equivalent to an array
containing only 0. [transfer none][array zero-terminated=1][allow-none] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory | 
| 
 | the first feature | 
| 
 | the second and subsequent features, if any, ending with 0 | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | the object path of a connection | 
| 
 | the immutable properties of the connection. [transfer none][element-type utf8 GObject.Value] | 
| 
 | Used to raise an error if object_pathis not valid | 
| Returns : | a reference to a TpConnection;
see tp_connection_new(). [transfer full] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpConnection | 
| Returns : | a newly allocated GArray. [transfer full][element-type GLib.Quark] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | an array
of desired features, ending with 0; NULLis equivalent to an array
containing only 0. [transfer none][array zero-terminated=1][allow-none] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory | 
| 
 | the first feature | 
| 
 | the second and subsequent features, if any, ending with 0 | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpConnection whose "factory" is this object | 
| 
 | the object path of a channel on connection | 
| 
 | the immutable properties of the channel. [transfer none][element-type utf8 GObject.Value] | 
| 
 | Used to raise an error if object_pathis not valid | 
| Returns : | a reference to a TpChannel;
see tp_channel_new_from_properties(). [transfer full] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpChannel | 
| Returns : | a newly allocated GArray. [transfer full][element-type GLib.Quark] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | an array
of desired features, ending with 0; NULLis equivalent to an array
containing only 0. [transfer none][array zero-terminated=1][allow-none] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory | 
| 
 | the first feature | 
| 
 | the second and subsequent features, if any, ending with 0 | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpConnection whose "factory" is this object | 
| 
 | a TpHandle | 
| 
 | a string representing the contact's identifier | 
| Returns : | a reference to a TpContact. [transfer full] | 
Since 0.15.5
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().
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpConnection whose "factory" is this object | 
| 
 | The number of contacts in contacts(must be at least 1) | 
| 
 | An array of TpContact objects
associated with self. [array length=n_contacts] | 
| 
 | a callback to call when the operation finishes | 
| 
 | data to pass to callback | 
Since 0.19.1
gboolean tp_simple_client_factory_upgrade_contacts_finish (TpSimpleClientFactory *self,GAsyncResult *result,GPtrArray **contacts,GError **error);
Finishes tp_simple_client_factory_upgrade_contacts_async()
| 
 | a TpSimpleClientFactory | 
| 
 | a GAsyncResult | 
| 
 | a location to set a GPtrArray of upgraded TpContact, or NULL. [element-type TelepathyGLib.Contact][transfer container][out][allow-none] | 
| 
 | a GError to fill | 
| Returns : | TRUEon success,FALSEotherwise. | 
Since 0.19.1
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().
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpConnection | 
| 
 | a string representing the contact's identifier | 
| 
 | a callback to call when the operation finishes | 
| 
 | data to pass to callback | 
Since 0.19.1
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()
| 
 | a TpSimpleClientFactory | 
| 
 | a GAsyncResult | 
| 
 | a GError to fill | 
| Returns : | a TpContact or NULLon error. [transfer full] | 
Since 0.19.1
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | a TpConnection | 
| Returns : | a newly allocated GArray. [transfer full][element-type TelepathyGLib.ContactFeature] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory object | 
| 
 | The number of features in features(may be 0) | 
| 
 | an array of desired
features (may be NULLifn_featuresis 0). [array length=n_features][allow-none] | 
Since 0.15.5
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.
| 
 | a TpSimpleClientFactory | 
| 
 | the first feature | 
| 
 | the second and subsequent features, if any, ending with TP_CONTACT_FEATURE_INVALID | 
Since 0.15.5
"dbus-daemon" property"dbus-daemon" TpDBusDaemon* : Read / Write / Construct Only
The D-Bus daemon for this object.