1 /*
2 * tp-handle-repo.h - handle reference-counting for connection managers
3 *
4 * Copyright (C) 2005,2006,2007 Collabora Ltd.
5 * Copyright (C) 2005,2006,2007 Nokia Corporation
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * as published by the Free Software Foundation; either version 2.1 of
10 * the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA
21 *
22 */
23
24 #if defined (TP_DISABLE_SINGLE_INCLUDE) && !defined (_TP_IN_META_HEADER) && !defined (_TP_COMPILATION)
25 #error "Only <telepathy-glib/telepathy-glib.h> and <telepathy-glib/telepathy-glib-dbus.h> can be included directly."
26 #endif
27
28 #ifndef __TP_HANDLE_REPO_H__
29 #define __TP_HANDLE_REPO_H__
30
31 #include <glib-object.h>
32
33 #include <gio/gio.h>
34
35 #include <telepathy-glib/intset.h>
36 #include <telepathy-glib/handle.h>
37
38 G_BEGIN_DECLS
39
40 /* Forward declaration to avoid circular includes */
41 typedef struct _TpBaseConnection TpBaseConnection;
42
43 /* Forward declaration because it's in the HandleRepo API */
44
45 #define TP_TYPE_HANDLE_SET (tp_handle_set_get_type ())
46 GType tp_handle_set_get_type (void);
47
48 typedef struct _TpHandleSet TpHandleSet;
49
50 /* Handle repository abstract interface */
51
52 #define TP_TYPE_HANDLE_REPO_IFACE (tp_handle_repo_iface_get_type ())
53
54 #define TP_HANDLE_REPO_IFACE(obj) \
55 (G_TYPE_CHECK_INSTANCE_CAST ((obj), \
56 TP_TYPE_HANDLE_REPO_IFACE, TpHandleRepoIface))
57
58 #define TP_IS_HANDLE_REPO_IFACE(obj) \
59 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
60 TP_TYPE_HANDLE_REPO_IFACE))
61
62 #define TP_HANDLE_REPO_IFACE_GET_CLASS(obj) \
63 (G_TYPE_INSTANCE_GET_INTERFACE ((obj), \
64 TP_TYPE_HANDLE_REPO_IFACE, TpHandleRepoIfaceClass))
65
66 /**
67 * TpHandleRepoIface:
68 *
69 * Dummy typedef representing any implementation of this interface.
70 */
71 typedef struct _TpHandleRepoIface TpHandleRepoIface;
72
73 /**
74 * TpHandleRepoIfaceClass:
75 *
76 * The class of a handle repository interface. The structure layout is
77 * only available within telepathy-glib, for the handle repository
78 * implementations' benefit.
79 */
80 typedef struct _TpHandleRepoIfaceClass TpHandleRepoIfaceClass;
81
82 GType tp_handle_repo_iface_get_type (void);
83
84 /* Public API for handle repositories */
85
86 gboolean tp_handle_is_valid (TpHandleRepoIface *self,
87 TpHandle handle, GError **error);
88 gboolean tp_handles_are_valid (TpHandleRepoIface *self,
89 const GArray *handles, gboolean allow_zero, GError **error);
90
91 #ifndef TP_DISABLE_DEPRECATED
92 _TP_DEPRECATED_IN_0_20
93 TpHandle tp_handle_ref (TpHandleRepoIface *self, TpHandle handle);
94 _TP_DEPRECATED_IN_0_20
95 void tp_handles_ref (TpHandleRepoIface *self, const GArray *handles);
96 _TP_DEPRECATED_IN_0_20
97 void tp_handle_unref (TpHandleRepoIface *self, TpHandle handle);
98 _TP_DEPRECATED_IN_0_20
99 void tp_handles_unref (TpHandleRepoIface *self, const GArray *handles);
100
101 _TP_DEPRECATED_IN_0_20
102 gboolean tp_handle_client_hold (TpHandleRepoIface *self,
103 const gchar *client, TpHandle handle, GError **error);
104 _TP_DEPRECATED_IN_0_20
105 gboolean tp_handles_client_hold (TpHandleRepoIface *self,
106 const gchar *client, const GArray *handles, GError **error);
107 _TP_DEPRECATED_IN_0_20
108 gboolean tp_handle_client_release (TpHandleRepoIface *self,
109 const gchar *client, TpHandle handle, GError **error);
110 _TP_DEPRECATED_IN_0_20
111 gboolean tp_handles_client_release (TpHandleRepoIface *self,
112 const gchar *client, const GArray *handles, GError **error);
113 #endif
114
115 const char *tp_handle_inspect (TpHandleRepoIface *self,
116 TpHandle handle) G_GNUC_WARN_UNUSED_RESULT;
117 TpHandle tp_handle_lookup (TpHandleRepoIface *self,
118 const gchar *id, gpointer context, GError **error);
119 TpHandle tp_handle_ensure (TpHandleRepoIface *self,
120 const gchar *id, gpointer context, GError **error)
121 G_GNUC_WARN_UNUSED_RESULT;
122
123 _TP_AVAILABLE_IN_0_20
124 void tp_handle_ensure_async (TpHandleRepoIface *self,
125 TpBaseConnection *connection,
126 const gchar *id,
127 gpointer context,
128 GAsyncReadyCallback callback,
129 gpointer user_data);
130 _TP_AVAILABLE_IN_0_20
131 TpHandle tp_handle_ensure_finish (TpHandleRepoIface *self,
132 GAsyncResult *result,
133 GError **error);
134
135 #ifndef TP_DISABLE_DEPRECATED
136 _TP_DEPRECATED_IN_0_20
137 void tp_handle_set_qdata (TpHandleRepoIface *repo, TpHandle handle,
138 GQuark key_id, gpointer data, GDestroyNotify destroy);
139 _TP_DEPRECATED_IN_0_20
140 gpointer tp_handle_get_qdata (TpHandleRepoIface *repo, TpHandle handle,
141 GQuark key_id);
142 #endif
143
144 /* Handle set helper class */
145
146 typedef void (*TpHandleSetMemberFunc)(TpHandleSet *set, TpHandle handle,
147 gpointer userdata);
148
149 TpHandleSet * tp_handle_set_new (TpHandleRepoIface *repo)
150 G_GNUC_WARN_UNUSED_RESULT;
151 TpHandleSet *tp_handle_set_copy (const TpHandleSet *other)
152 G_GNUC_WARN_UNUSED_RESULT;
153 TpHandleSet *tp_handle_set_new_from_intset (TpHandleRepoIface *repo,
154 const TpIntset *intset);
155 TpHandleSet *tp_handle_set_new_containing (TpHandleRepoIface *repo,
156 TpHandle handle);
157
158 void tp_handle_set_clear (TpHandleSet *set);
159 void tp_handle_set_destroy (TpHandleSet *set);
160
161 TpIntset *tp_handle_set_peek (TpHandleSet *set) G_GNUC_WARN_UNUSED_RESULT;
162
163 void tp_handle_set_add (TpHandleSet *set, TpHandle handle);
164 gboolean tp_handle_set_remove (TpHandleSet *set, TpHandle handle);
165 gboolean tp_handle_set_is_member (const TpHandleSet *set, TpHandle handle);
166
167 void tp_handle_set_foreach (TpHandleSet *set, TpHandleSetMemberFunc func,
168 gpointer user_data);
169
170 gboolean tp_handle_set_is_empty (const TpHandleSet *set);
171 int tp_handle_set_size (const TpHandleSet *set);
172 GArray *tp_handle_set_to_array (const TpHandleSet *set)
173 G_GNUC_WARN_UNUSED_RESULT;
174 GHashTable *tp_handle_set_to_identifier_map (TpHandleSet *self)
175 G_GNUC_WARN_UNUSED_RESULT;
176 TpHandleSet *tp_handle_set_new_from_array (TpHandleRepoIface *repo,
177 const GArray *array) G_GNUC_WARN_UNUSED_RESULT;
178
179 TpIntset *tp_handle_set_update (TpHandleSet *set, const TpIntset *add)
180 G_GNUC_WARN_UNUSED_RESULT;
181 TpIntset *tp_handle_set_difference_update (TpHandleSet *set,
182 const TpIntset *remove) G_GNUC_WARN_UNUSED_RESULT;
183
184 gchar *tp_handle_set_dump (const TpHandleSet *self) G_GNUC_WARN_UNUSED_RESULT;
185
186 /* static inline because it relies on TP_NUM_HANDLE_TYPES */
187 /**
188 * tp_handles_supported_and_valid: (skip)
189 * @repos: An array of possibly null pointers to handle repositories, indexed
190 * by handle type, where a null pointer means an unsupported handle
191 * type
192 * @handle_type: The handle type
193 * @handles: A GArray of guint representing handles of the given type
194 * @allow_zero: If %TRUE, zero is treated like a valid handle
195 * @error: Used to return an error if %FALSE is returned
196 *
197 * Return %TRUE if the given handle type is supported (i.e. repos[handle_type]
198 * is not %NULL) and the given handles are all valid in that repository.
199 * If not, set @error and return %FALSE.
200 *
201 * Returns: %TRUE if the handle type is supported and the handles are all
202 * valid.
203 */
204
205 static inline
206 /* spacer so gtkdoc documents this function as though not static */
207 gboolean tp_handles_supported_and_valid (
208 TpHandleRepoIface *repos[TP_NUM_HANDLE_TYPES],
209 TpHandleType handle_type, const GArray *handles, gboolean allow_zero,
210 GError **error);
211
212 static inline gboolean
tp_handles_supported_and_valid(TpHandleRepoIface * repos[TP_NUM_HANDLE_TYPES],TpHandleType handle_type,const GArray * handles,gboolean allow_zero,GError ** error)213 tp_handles_supported_and_valid (TpHandleRepoIface *repos[TP_NUM_HANDLE_TYPES],
214 TpHandleType handle_type,
215 const GArray *handles,
216 gboolean allow_zero,
217 GError **error)
218 {
219 if (!tp_handle_type_is_valid (handle_type, error))
220 return FALSE;
221
222 if (!repos[handle_type])
223 {
224 tp_g_set_error_unsupported_handle_type (handle_type, error);
225 return FALSE;
226 }
227 return tp_handles_are_valid (repos[handle_type], handles, allow_zero, error);
228 }
229
230 G_END_DECLS
231
232 #endif /*__HANDLE_SET_H__*/
233