From f63da5886001e5ca51342a9ae55aa8de28b085b5 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 6 Sep 2013 12:00:12 +0100 Subject: [PATCH 10/19] TpSimpleClientFactory: suggest getting objects from "larger" objects --- telepathy-glib/simple-client-factory.c | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/telepathy-glib/simple-client-factory.c b/telepathy-glib/simple-client-factory.c index 34ad54c..71b8e6b 100644 --- a/telepathy-glib/simple-client-factory.c +++ b/telepathy-glib/simple-client-factory.c @@ -36,7 +36,8 @@ * * Currently supported classes are #TpAccount, #TpConnection, * #TpChannel and #TpContact. Those objects should always be acquired through a - * factory, rather than being constructed directly. + * 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 @@ -451,6 +452,10 @@ tp_simple_client_factory_get_dbus_daemon (TpSimpleClientFactory *self) * 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 #TpAccountManager::validity-changed are more appropriate for most + * applications. + * * Returns: (transfer full): a reference to a #TpAccount; * see tp_account_new(). * @@ -576,6 +581,9 @@ tp_simple_client_factory_add_account_features_varargs ( * 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. #TpAccount:connection is more + * appropriate for most applications. + * * Returns: (transfer full): a reference to a #TpConnection; * see tp_connection_new(). * @@ -702,6 +710,10 @@ tp_simple_client_factory_add_connection_features_varargs ( * 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. + * * Returns: (transfer full): a reference to a #TpChannel; * see tp_channel_new_from_properties(). * -- 1.8.4.rc3