1 /*
2 * Interface for channel factories
3 *
4 * Copyright © 2010 Collabora Ltd.
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21 /**
22 * SECTION:client-channel-factory
23 * @title: TpClientChannelFactoryInterface
24 * @short_description: an interface for client channel factories
25 *
26 * Client channel factories are used to create channel proxies. An application
27 * wanting to use its own #TpChannel subclass has to implement an object
28 * implementing the #TpClientChannelFactoryInterface interface.
29 *
30 * Once a channel has been created by a factory using
31 * tp_client_channel_factory_create_channel(), the caller should then prepare
32 * on it the channel features returned by
33 * tp_client_channel_factory_dup_channel_features() using
34 * tp_proxy_prepare_async().
35 *
36 * Since: 0.13.2
37 */
38
39 /**
40 * TpClientChannelFactory:
41 *
42 * Opaque typedef representing a #GObject that implements
43 * the %TP_TYPE_CLIENT_CHANNEL_FACTORY interface.
44 *
45 * Since: 0.13.6
46 */
47
48 /**
49 * TpClientChannelFactoryInterface:
50 * @parent: the parent
51 * @create_channel: obsolete version of @obj_create_channel which does not
52 * receive the object instance as an argument
53 * @dup_channel_features: obsolete version of @obj_dup_channel_features which
54 * does not receive the object instance as an argument
55 * @obj_create_channel: virtual method used to create channels;
56 * see tp_client_channel_factory_create_channel()
57 * @obj_dup_channel_features: virtual method returning channel features that
58 * have to be prepared on newly created channels;
59 * see tp_client_channel_factory_dup_channel_features()
60 *
61 * Interface for a channel factory
62 *
63 * Since: 0.13.2
64 */
65
66 #include "config.h"
67
68 #include "telepathy-glib/client-channel-factory.h"
69
70 #include <telepathy-glib/util.h>
71
72 #define DEBUG_FLAG TP_DEBUG_CLIENT
73 #include "telepathy-glib/debug-internal.h"
74
G_DEFINE_INTERFACE(TpClientChannelFactory,tp_client_channel_factory,G_TYPE_OBJECT)75 G_DEFINE_INTERFACE(TpClientChannelFactory, tp_client_channel_factory,
76 G_TYPE_OBJECT)
77
78 /* Deprecated module can use deprecated APIs */
79 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
80
81 static void
82 tp_client_channel_factory_default_init (TpClientChannelFactoryInterface *iface)
83 {
84 }
85
86 /**
87 * tp_client_channel_factory_create_channel:
88 * @self: a client channel factory
89 * @conn: a #TpConnection
90 * @path: the object path of the channel
91 * @properties: (transfer none) (element-type utf8 GObject.Value):
92 * the immutable properties of the channel
93 * @error: used to indicate the error if %NULL is returned
94 *
95 * Function called when a channel need to be created.
96 * Implementation can return a subclass of #TpChannel if they need to.
97 *
98 * Changed in 0.13.6: the function's signature was previously wrong;
99 * it expected an object instance as its first parameter, but the type of the
100 * parameter was the type of the interface vtable.
101 *
102 * Returns: (transfer full): a new channel proxy, or %NULL on invalid arguments
103 *
104 * Since: 0.13.2
105 */
106 TpChannel *
tp_client_channel_factory_create_channel(TpClientChannelFactory * self,TpConnection * conn,const gchar * path,GHashTable * properties,GError ** error)107 tp_client_channel_factory_create_channel (TpClientChannelFactory *self,
108 TpConnection *conn,
109 const gchar *path,
110 GHashTable *properties,
111 GError **error)
112 {
113 TpClientChannelFactoryInterface *iface = TP_CLIENT_CHANNEL_FACTORY_GET_IFACE (
114 self);
115
116 g_return_val_if_fail (TP_IS_CLIENT_CHANNEL_FACTORY (self), NULL);
117 g_return_val_if_fail (TP_IS_CONNECTION (conn), NULL);
118 g_return_val_if_fail (path != NULL, NULL);
119 g_return_val_if_fail (properties != NULL, NULL);
120
121 if (iface->obj_create_channel != NULL)
122 return iface->obj_create_channel (self, conn, path, properties, error);
123
124 if (iface->create_channel != NULL)
125 return iface->create_channel (iface, conn, path, properties, error);
126
127 return tp_channel_new_from_properties (conn, path, properties, error);
128 }
129
130 /**
131 * tp_client_channel_factory_dup_channel_features:
132 * @self: a client channel factory
133 * @channel: a #TpChannel
134 *
135 * Return a zero terminated #GArray containing the #TpChannel features that
136 * should be prepared on @channel.
137 *
138 * Changed in 0.13.6: the function's signature was previously wrong;
139 * it expected an object instance as its first parameter, but the type of the
140 * parameter was the type of the interface vtable.
141 *
142 * Returns: (transfer full) (element-type GQuark): a newly allocated #GArray
143 *
144 * Since: 0.13.3
145 */
146 GArray *
tp_client_channel_factory_dup_channel_features(TpClientChannelFactory * self,TpChannel * channel)147 tp_client_channel_factory_dup_channel_features (
148 TpClientChannelFactory *self,
149 TpChannel *channel)
150 {
151 TpClientChannelFactoryInterface *iface = TP_CLIENT_CHANNEL_FACTORY_GET_IFACE (
152 self);
153 GArray *arr;
154 GQuark feature = TP_CHANNEL_FEATURE_CORE;
155
156 g_return_val_if_fail (TP_IS_CLIENT_CHANNEL_FACTORY (self), NULL);
157 g_return_val_if_fail (TP_IS_CHANNEL (channel), NULL);
158
159 if (iface->obj_dup_channel_features != NULL)
160 return iface->obj_dup_channel_features (self, channel);
161
162 if (iface->dup_channel_features != NULL)
163 return iface->dup_channel_features (iface, channel);
164
165 arr = g_array_sized_new (TRUE, FALSE, sizeof (GQuark), 1);
166
167 g_array_append_val (arr, feature);
168
169 return arr;
170 }
171
172 G_GNUC_END_IGNORE_DEPRECATIONS
173