1 /*
2 * util.h - Headers for telepathy-glib utility functions
3 *
4 * Copyright © 2006-2010 Collabora Ltd. <http://www.collabora.co.uk/>
5 * Copyright © 2006-2008 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
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but 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 02110-1301 USA
20 */
21
22 #if defined (TP_DISABLE_SINGLE_INCLUDE) && !defined (_TP_IN_META_HEADER) && !defined (_TP_COMPILATION)
23 #error "Only <telepathy-glib/telepathy-glib.h> and <telepathy-glib/telepathy-glib-dbus.h> can be included directly."
24 #endif
25
26 #ifndef __TP_UTIL_H__
27 #define __TP_UTIL_H__
28 #define __TP_IN_UTIL_H__
29
30 #include <gio/gio.h>
31
32 #include <telepathy-glib/defs.h>
33 #include <telepathy-glib/verify.h>
34
35 #define tp_verify_statement(R) ((void) tp_verify_true (R))
36
37 G_BEGIN_DECLS
38
39 gboolean tp_g_ptr_array_contains (GPtrArray *haystack, gpointer needle);
40 void tp_g_ptr_array_extend (GPtrArray *target, GPtrArray *source);
41
42 #ifndef __GI_SCANNER__
43 /* Functions with _new in their names confuse the g-i scanner, but these
44 * are all (skip)'d anyway. */
45
46 GValue *tp_g_value_slice_new (GType type) G_GNUC_WARN_UNUSED_RESULT;
47
48 GValue *tp_g_value_slice_new_boolean (gboolean b) G_GNUC_WARN_UNUSED_RESULT;
49 GValue *tp_g_value_slice_new_int (gint n) G_GNUC_WARN_UNUSED_RESULT;
50 GValue *tp_g_value_slice_new_int64 (gint64 n) G_GNUC_WARN_UNUSED_RESULT;
51 GValue *tp_g_value_slice_new_byte (guchar n) G_GNUC_WARN_UNUSED_RESULT;
52 GValue *tp_g_value_slice_new_uint (guint n) G_GNUC_WARN_UNUSED_RESULT;
53 GValue *tp_g_value_slice_new_uint64 (guint64 n) G_GNUC_WARN_UNUSED_RESULT;
54 GValue *tp_g_value_slice_new_double (double d) G_GNUC_WARN_UNUSED_RESULT;
55
56 GValue *tp_g_value_slice_new_string (const gchar *string)
57 G_GNUC_WARN_UNUSED_RESULT;
58 GValue *tp_g_value_slice_new_static_string (const gchar *string)
59 G_GNUC_WARN_UNUSED_RESULT;
60 GValue *tp_g_value_slice_new_take_string (gchar *string)
61 G_GNUC_WARN_UNUSED_RESULT;
62
63 GValue *tp_g_value_slice_new_boxed (GType type, gconstpointer p)
64 G_GNUC_WARN_UNUSED_RESULT;
65 GValue *tp_g_value_slice_new_static_boxed (GType type, gconstpointer p)
66 G_GNUC_WARN_UNUSED_RESULT;
67 GValue *tp_g_value_slice_new_take_boxed (GType type, gpointer p)
68 G_GNUC_WARN_UNUSED_RESULT;
69
70 #endif
71
72 void tp_g_value_slice_free (GValue *value);
73
74 GValue *tp_g_value_slice_dup (const GValue *value) G_GNUC_WARN_UNUSED_RESULT;
75
76 void tp_g_hash_table_update (GHashTable *target, GHashTable *source,
77 GBoxedCopyFunc key_dup, GBoxedCopyFunc value_dup);
78
79 /* See https://bugzilla.gnome.org/show_bug.cgi?id=399880 for glib inclusion */
80 static inline gboolean
tp_str_empty(const gchar * s)81 tp_str_empty (const gchar *s)
82 {
83 return (s == NULL || s[0] == '\0');
84 }
85
86 /* See https://bugzilla.gnome.org/show_bug.cgi?id=685878 for glib inclusion */
87 gboolean tp_strdiff (const gchar *left, const gchar *right);
88
89 gpointer tp_mixin_offset_cast (gpointer instance, guint offset);
90 guint tp_mixin_instance_get_offset (gpointer instance, GQuark quark);
91 guint tp_mixin_class_get_offset (gpointer klass, GQuark quark);
92
93 gchar *tp_escape_as_identifier (const gchar *name) G_GNUC_WARN_UNUSED_RESULT;
94
95 /* See https://bugzilla.gnome.org/show_bug.cgi?id=685880 for glib inclusion */
96 gboolean tp_strv_contains (const gchar * const *strv, const gchar *str);
97
98 #ifndef TP_DISABLE_DEPRECATED
99 _TP_DEPRECATED_IN_0_22_FOR(g_key_file_get_int64)
100 gint64 tp_g_key_file_get_int64 (GKeyFile *key_file, const gchar *group_name,
101 const gchar *key, GError **error);
102 _TP_DEPRECATED_IN_0_22_FOR(g_key_file_get_uint64)
103 guint64 tp_g_key_file_get_uint64 (GKeyFile *key_file, const gchar *group_name,
104 const gchar *key, GError **error);
105 #endif
106
107 /* g_signal_connect_object() has been fixed in GLib 2.36, we can deprecate this
108 * once we depend on that version. */
109 gulong tp_g_signal_connect_object (gpointer instance,
110 const gchar *detailed_signal, GCallback c_handler, gpointer gobject,
111 GConnectFlags connect_flags);
112
113 GValueArray *tp_value_array_build (gsize length,
114 GType type,
115 ...) G_GNUC_WARN_UNUSED_RESULT;
116 void tp_value_array_unpack (GValueArray *array,
117 gsize len,
118 ...);
119
120 /* Work around GLib having deprecated something that is part of our API. */
121 _TP_AVAILABLE_IN_0_24
122 void tp_value_array_free (GValueArray *va);
123 #if TP_VERSION_MAX_ALLOWED >= TP_VERSION_0_24
124 #define tp_value_array_free(va) _tp_value_array_free_inline (va)
125 #ifndef __GTK_DOC_IGNORE__ /* gtk-doc can't parse this */
126 static inline void
_tp_value_array_free_inline(GValueArray * va)127 _tp_value_array_free_inline (GValueArray *va)
128 {
129 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
130 g_value_array_free (va);
131 G_GNUC_END_IGNORE_DEPRECATIONS
132 }
133 #endif
134 #endif
135
136 /* See https://bugzilla.gnome.org/show_bug.cgi?id=680813 for glib inclusion */
137 typedef struct _TpWeakRef TpWeakRef;
138 TpWeakRef *tp_weak_ref_new (gpointer object,
139 gpointer user_data,
140 GDestroyNotify destroy) G_GNUC_WARN_UNUSED_RESULT;
141 gpointer tp_weak_ref_get_user_data (TpWeakRef *self) G_GNUC_WARN_UNUSED_RESULT;
142 gpointer tp_weak_ref_dup_object (TpWeakRef *self) G_GNUC_WARN_UNUSED_RESULT;
143 void tp_weak_ref_destroy (TpWeakRef *self);
144
145 #define tp_clear_pointer(pp, destroy) \
146 G_STMT_START \
147 { \
148 gpointer _tp_clear_pointer_tmp; \
149 \
150 _tp_clear_pointer_tmp = *(pp); \
151 *(pp) = NULL; \
152 \
153 if (_tp_clear_pointer_tmp != NULL) \
154 (destroy) (_tp_clear_pointer_tmp); \
155 } \
156 G_STMT_END
157
158 #define tp_clear_object(op) tp_clear_pointer ((op), g_object_unref)
159
160 #define tp_clear_boxed(gtype, pp) \
161 G_STMT_START \
162 { \
163 gpointer _tp_clear_boxed_tmp; \
164 \
165 _tp_clear_boxed_tmp = *(pp); \
166 *(pp) = NULL; \
167 \
168 if (_tp_clear_boxed_tmp != NULL) \
169 g_boxed_free (gtype, _tp_clear_boxed_tmp); \
170 } \
171 G_STMT_END
172
173 void tp_simple_async_report_success_in_idle (GObject *source,
174 GAsyncReadyCallback callback, gpointer user_data, gpointer source_tag);
175
176 gint64 tp_user_action_time_from_x11 (guint32 x11_time);
177 gboolean tp_user_action_time_should_present (gint64 user_action_time,
178 guint32 *x11_time);
179
180 /* See https://bugzilla.gnome.org/show_bug.cgi?id=610969 for glib inclusion */
181 gchar *tp_utf8_make_valid (const gchar *name);
182
183 G_END_DECLS
184
185 #undef __TP_IN_UTIL_H__
186 #endif /* __TP_UTIL_H__ */
187