![]() |
![]() |
![]() |
telepathy-glib API Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#include <telepathy-glib/telepathy-glib.h> TpClientFactory; struct TpClientFactoryClass; TpClientFactory * tp_client_factory_new (TpDBusDaemon *dbus
); TpDBusDaemon * tp_client_factory_get_dbus_daemon (TpClientFactory *self
); TpAccount * tp_client_factory_ensure_account (TpClientFactory *self
,const gchar *object_path
,const GHashTable *immutable_properties
,GError **error
); GArray * tp_client_factory_dup_account_features (TpClientFactory *self
,TpAccount *account
); void tp_client_factory_add_account_features (TpClientFactory *self
,const GQuark *features
); void tp_client_factory_add_account_features_varargs (TpClientFactory *self
,GQuark feature
,...
); TpConnection * tp_client_factory_ensure_connection (TpClientFactory *self
,const gchar *object_path
,const GHashTable *immutable_properties
,GError **error
); GArray * tp_client_factory_dup_connection_features (TpClientFactory *self
,TpConnection *connection
); void tp_client_factory_add_connection_features (TpClientFactory *self
,const GQuark *features
); void tp_client_factory_add_connection_features_varargs (TpClientFactory *self
,GQuark feature
,...
); TpChannel * tp_client_factory_ensure_channel (TpClientFactory *self
,TpConnection *connection
,const gchar *object_path
,const GHashTable *immutable_properties
,GError **error
); GArray * tp_client_factory_dup_channel_features (TpClientFactory *self
,TpChannel *channel
); void tp_client_factory_add_channel_features (TpClientFactory *self
,const GQuark *features
); void tp_client_factory_add_channel_features_varargs (TpClientFactory *self
,GQuark feature
,...
); TpContact * tp_client_factory_ensure_contact (TpClientFactory *self
,TpConnection *connection
,TpHandle handle
,const gchar *identifier
); void tp_client_factory_upgrade_contacts_async (TpClientFactory *self
,TpConnection *connection
,guint n_contacts
,TpContact * const *contacts
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean tp_client_factory_upgrade_contacts_finish (TpClientFactory *self
,GAsyncResult *result
,GPtrArray **contacts
,GError **error
); void tp_client_factory_ensure_contact_by_id_async (TpClientFactory *self
,TpConnection *connection
,const gchar *identifier
,GAsyncReadyCallback callback
,gpointer user_data
); TpContact * tp_client_factory_ensure_contact_by_id_finish (TpClientFactory *self
,GAsyncResult *result
,GError **error
); GArray * tp_client_factory_dup_contact_features (TpClientFactory *self
,TpConnection *connection
); void tp_client_factory_add_contact_features (TpClientFactory *self
,const GQuark *features
); void tp_client_factory_add_contact_features_varargs (TpClientFactory *self
,GQuark 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 TpClientFactory 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[]) { TpClientFactory *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 _TpClientFactory TpClientFactory;
Data structure representing a TpClientFactory
Since 0.99.1
struct TpClientFactoryClass { GObjectClass parent_class; /* TpAccount */ TpAccount * (*create_account) (TpClientFactory *self, const gchar *object_path, const GHashTable *immutable_properties, GError **error); GArray * (*dup_account_features) (TpClientFactory *self, TpAccount *account); /* TpConnection */ TpConnection * (*create_connection) (TpClientFactory *self, const gchar *object_path, const GHashTable *immutable_properties, GError **error); GArray * (*dup_connection_features) (TpClientFactory *self, TpConnection *connection); /* TpChannel */ TpChannel * (*create_channel) (TpClientFactory *self, TpConnection *conn, const gchar *object_path, const GHashTable *immutable_properties, GError **error); GArray * (*dup_channel_features) (TpClientFactory *self, TpChannel *channel); /* TpContact */ TpContact * (*create_contact) (TpClientFactory *self, TpConnection *connection, TpHandle handle, const gchar *identifier); GArray * (*dup_contact_features) (TpClientFactory *self, TpConnection *connection); };
The class structure for TpClientFactory.
TpClientFactory 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_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_client_factory_ensure_account()
|
|
implementation of tp_client_factory_dup_account_features()
|
|
create a TpConnection;
see tp_client_factory_ensure_connection()
|
|
implementation of
tp_client_factory_dup_connection_features()
|
|
create a TpChannel;
see tp_client_factory_ensure_channel()
|
|
implementation of tp_client_factory_dup_channel_features()
|
|
create a TpContact;
see tp_client_factory_ensure_contact()
|
|
implementation of tp_client_factory_dup_contact_features()
|
Since 0.99.1
TpClientFactory * tp_client_factory_new (TpDBusDaemon *dbus
);
Creates a new TpClientFactory instance. If dbus
is NULL
then
tp_dbus_daemon_dup()
will be used.
|
a TpDBusDaemon, or NULL . [allow-none]
|
Returns : |
a new TpClientFactory |
Since 0.99.1
TpDBusDaemon * tp_client_factory_get_dbus_daemon (TpClientFactory *self
);
|
a TpClientFactory object |
Returns : |
the value of the "dbus-daemon" property. [transfer none] |
Since 0.99.1
TpAccount * tp_client_factory_ensure_account (TpClientFactory *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_client_factory_dup_account_features()
).
This function is rather low-level. tp_account_manager_dup_usable_accounts()
and "usability-changed" are more appropriate for most
applications.
|
a TpClientFactory 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_path is not valid |
Returns : |
a reference to a TpAccount;
see tp_account_new() . [transfer full]
|
Since 0.99.1
GArray * tp_client_factory_dup_account_features (TpClientFactory *self
,TpAccount *account
);
Return a zero-terminated GArray containing the TpAccount features that
should be prepared on account
.
|
a TpClientFactory object |
|
a TpAccount |
Returns : |
a newly allocated GArray. [transfer full][element-type GLib.Quark] |
Since 0.99.1
void tp_client_factory_add_account_features (TpClientFactory *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_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 TpClientFactory object |
|
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.99.1
void tp_client_factory_add_account_features_varargs (TpClientFactory *self
,GQuark feature
,...
);
The same as tp_client_factory_add_account_features()
, but with a more
convenient calling convention from C.
|
a TpClientFactory |
|
the first feature |
|
the second and subsequent features, if any, ending with 0 |
Since 0.99.1
TpConnection * tp_client_factory_ensure_connection (TpClientFactory *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_client_factory_dup_connection_features()
).
This function is rather low-level. "connection" is more appropriate for most applications.
|
a TpClientFactory 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_path is not valid |
Returns : |
a reference to a TpConnection;
see tp_connection_new() . [transfer full]
|
Since 0.99.1
GArray * tp_client_factory_dup_connection_features (TpClientFactory *self
,TpConnection *connection
);
Return a zero-terminated GArray containing the TpConnection features that
should be prepared on connection
.
|
a TpClientFactory object |
|
a TpConnection |
Returns : |
a newly allocated GArray. [transfer full][element-type GLib.Quark] |
Since 0.99.1
void tp_client_factory_add_connection_features (TpClientFactory *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_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 TpClientFactory object |
|
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.99.1
void tp_client_factory_add_connection_features_varargs (TpClientFactory *self
,GQuark feature
,...
);
The same as tp_client_factory_add_connection_features()
, but with a
more convenient calling convention from C.
|
a TpClientFactory |
|
the first feature |
|
the second and subsequent features, if any, ending with 0 |
Since 0.99.1
TpChannel * tp_client_factory_ensure_channel (TpClientFactory *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_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 TpClientFactory |
|
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_path is not valid |
Returns : |
a reference to a TpChannel;
see tp_channel_new_from_properties() . [transfer full]
|
Since 0.99.1
GArray * tp_client_factory_dup_channel_features (TpClientFactory *self
,TpChannel *channel
);
Return a zero-terminated GArray containing the TpChannel features that
should be prepared on channel
.
|
a TpClientFactory object |
|
a TpChannel |
Returns : |
a newly allocated GArray. [transfer full][element-type GLib.Quark] |
Since 0.99.1
void tp_client_factory_add_channel_features (TpClientFactory *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_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 TpClientFactory object |
|
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.99.1
void tp_client_factory_add_channel_features_varargs (TpClientFactory *self
,GQuark feature
,...
);
The same as tp_client_factory_add_channel_features()
, but with a
more convenient calling convention from C.
|
a TpClientFactory |
|
the first feature |
|
the second and subsequent features, if any, ending with 0 |
Since 0.99.1
TpContact * tp_client_factory_ensure_contact (TpClientFactory *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_client_factory_dup_contact_features()
).
|
a TpClientFactory 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.99.1
void tp_client_factory_upgrade_contacts_async (TpClientFactory *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_client_factory_add_contact_features()
.
|
a TpClientFactory 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_client_factory_upgrade_contacts_finish (TpClientFactory *self
,GAsyncResult *result
,GPtrArray **contacts
,GError **error
);
Finishes tp_client_factory_upgrade_contacts_async()
|
a TpClientFactory |
|
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 : |
TRUE on success, FALSE otherwise. |
Since 0.19.1
void tp_client_factory_ensure_contact_by_id_async (TpClientFactory *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_client_factory_add_contact_features()
.
|
a TpClientFactory 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_client_factory_ensure_contact_by_id_finish (TpClientFactory *self
,GAsyncResult *result
,GError **error
);
Finishes tp_client_factory_ensure_contact_by_id_async()
|
a TpClientFactory |
|
a GAsyncResult |
|
a GError to fill |
Returns : |
a TpContact or NULL on error. [transfer full]
|
Since 0.19.1
GArray * tp_client_factory_dup_contact_features (TpClientFactory *self
,TpConnection *connection
);
Return a GArray containing the contact feature GQuarks
that should be prepared on all contacts of connection
.
|
a TpClientFactory object |
|
a TpConnection |
Returns : |
a newly allocated GArray. [transfer full][element-type GLib.Quark] |
Since 0.99.1
void tp_client_factory_add_contact_features (TpClientFactory *self
,const GQuark *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_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 TpClientFactory object |
|
an array of desired features. [transfer none][array zero-terminated=1][allow-none] |
Since 0.99.1
void tp_client_factory_add_contact_features_varargs (TpClientFactory *self
,GQuark feature
,...
);
The same as tp_client_factory_add_contact_features()
, but with a
more convenient calling convention from C.
|
a TpClientFactory |
|
the first feature |
|
the second and subsequent features, if any, ending with 0 |
Since 0.99.1
"dbus-daemon"
property"dbus-daemon" TpDBusDaemon* : Read / Write / Construct Only
The D-Bus daemon for this object.