1 | /* GStreamer |
2 | * Copyright (C) 2003 David A. Schleef <ds@schleef.org> |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Library General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2 of the License, or (at your option) any later version. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Library General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Library General Public |
15 | * License along with this library; if not, write to the |
16 | * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, |
17 | * Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef __GST_STRUCTURE_H__ |
21 | #define __GST_STRUCTURE_H__ |
22 | |
23 | #include <gst/gstconfig.h> |
24 | #include <glib-object.h> |
25 | #include <gst/gstclock.h> |
26 | #include <gst/gstdatetime.h> |
27 | #include <gst/glib-compat.h> |
28 | |
29 | G_BEGIN_DECLS |
30 | |
31 | GST_API GType _gst_structure_type; |
32 | |
33 | typedef struct _GstStructure GstStructure; |
34 | |
35 | /** |
36 | * GstSerializeFlags: |
37 | * @GST_SERIALIZE_FLAG_NONE: No special flags specified. |
38 | * @GST_SERIALIZE_FLAG_BACKWARD_COMPAT: Serialize using the old format for |
39 | * nested structures. |
40 | * |
41 | * Since: 1.20 |
42 | */ |
43 | typedef enum |
44 | { |
45 | GST_SERIALIZE_FLAG_NONE = 0, |
46 | GST_SERIALIZE_FLAG_BACKWARD_COMPAT = (1 << 0), |
47 | } GstSerializeFlags; |
48 | |
49 | #define GST_TYPE_STRUCTURE (_gst_structure_type) |
50 | #define GST_IS_STRUCTURE(object) ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE)) |
51 | #define GST_STRUCTURE_CAST(object) ((GstStructure *)(object)) |
52 | #define GST_STRUCTURE(object) (GST_STRUCTURE_CAST(object)) |
53 | |
54 | |
55 | /** |
56 | * GstStructureForeachFunc: |
57 | * @field_id: the #GQuark of the field name |
58 | * @value: the #GValue of the field |
59 | * @user_data: user data |
60 | * |
61 | * A function that will be called in gst_structure_foreach(). The function may |
62 | * not modify @value. |
63 | * |
64 | * Returns: %TRUE if the foreach operation should continue, %FALSE if |
65 | * the foreach operation should stop with %FALSE. |
66 | */ |
67 | typedef gboolean (*GstStructureForeachFunc) (GQuark field_id, |
68 | const GValue * value, |
69 | gpointer user_data); |
70 | |
71 | /** |
72 | * GstStructureMapFunc: |
73 | * @field_id: the #GQuark of the field name |
74 | * @value: the #GValue of the field |
75 | * @user_data: user data |
76 | * |
77 | * A function that will be called in gst_structure_map_in_place(). The function |
78 | * may modify @value. |
79 | * |
80 | * Returns: %TRUE if the map operation should continue, %FALSE if |
81 | * the map operation should stop with %FALSE. |
82 | */ |
83 | typedef gboolean (*GstStructureMapFunc) (GQuark field_id, |
84 | GValue * value, |
85 | gpointer user_data); |
86 | |
87 | /** |
88 | * GstStructureFilterMapFunc: |
89 | * @field_id: the #GQuark of the field name |
90 | * @value: the #GValue of the field |
91 | * @user_data: user data |
92 | * |
93 | * A function that will be called in gst_structure_filter_and_map_in_place(). |
94 | * The function may modify @value, and the value will be removed from |
95 | * the structure if %FALSE is returned. |
96 | * |
97 | * Returns: %TRUE if the field should be preserved, %FALSE if it |
98 | * should be removed. |
99 | */ |
100 | typedef gboolean (*GstStructureFilterMapFunc) (GQuark field_id, |
101 | GValue * value, |
102 | gpointer user_data); |
103 | |
104 | /** |
105 | * GstStructure: |
106 | * @type: the GType of a structure |
107 | * |
108 | * The GstStructure object. Most fields are private. |
109 | */ |
110 | struct _GstStructure { |
111 | GType type; |
112 | |
113 | /*< private >*/ |
114 | GQuark name; |
115 | }; |
116 | |
117 | GST_API |
118 | GType gst_structure_get_type (void); |
119 | |
120 | GST_API |
121 | GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC; |
122 | |
123 | GST_API |
124 | GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC; |
125 | |
126 | GST_API |
127 | GstStructure * gst_structure_new (const gchar * name, |
128 | const gchar * firstfield, |
129 | ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC; |
130 | GST_API |
131 | GstStructure * gst_structure_new_valist (const gchar * name, |
132 | const gchar * firstfield, |
133 | va_list varargs) G_GNUC_MALLOC; |
134 | GST_API |
135 | GstStructure * gst_structure_new_id (GQuark name_quark, |
136 | GQuark field_quark, |
137 | ...) G_GNUC_MALLOC; |
138 | GST_API |
139 | GstStructure * gst_structure_new_from_string (const gchar * string); |
140 | |
141 | GST_API |
142 | GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC; |
143 | |
144 | GST_API |
145 | gboolean gst_structure_set_parent_refcount (GstStructure * structure, |
146 | gint * refcount); |
147 | GST_API |
148 | void gst_structure_free (GstStructure * structure); |
149 | |
150 | GST_API |
151 | void gst_clear_structure (GstStructure **structure_ptr); |
152 | #define gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free) |
153 | |
154 | GST_API |
155 | gboolean gst_structure_take (GstStructure ** oldstr_ptr, |
156 | GstStructure * newstr); |
157 | GST_API |
158 | const gchar * gst_structure_get_name (const GstStructure * structure); |
159 | |
160 | GST_API |
161 | GQuark gst_structure_get_name_id (const GstStructure * structure); |
162 | |
163 | GST_API |
164 | gboolean gst_structure_has_name (const GstStructure * structure, |
165 | const gchar * name); |
166 | GST_API |
167 | void gst_structure_set_name (GstStructure * structure, |
168 | const gchar * name); |
169 | GST_API |
170 | void gst_structure_id_set_value (GstStructure * structure, |
171 | GQuark field, |
172 | const GValue * value); |
173 | GST_API |
174 | void gst_structure_set_value (GstStructure * structure, |
175 | const gchar * fieldname, |
176 | const GValue * value); |
177 | GST_API |
178 | void gst_structure_set_array (GstStructure * structure, |
179 | const gchar * fieldname, |
180 | const GValueArray * array); |
181 | GST_API |
182 | void gst_structure_set_list (GstStructure * structure, |
183 | const gchar * fieldname, |
184 | const GValueArray * array); |
185 | GST_API |
186 | void gst_structure_id_take_value (GstStructure * structure, |
187 | GQuark field, |
188 | GValue * value); |
189 | GST_API |
190 | void gst_structure_take_value (GstStructure * structure, |
191 | const gchar * fieldname, |
192 | GValue * value); |
193 | GST_API |
194 | void gst_structure_set (GstStructure * structure, |
195 | const gchar * fieldname, |
196 | ...) G_GNUC_NULL_TERMINATED; |
197 | GST_API |
198 | void gst_structure_set_valist (GstStructure * structure, |
199 | const gchar * fieldname, |
200 | va_list varargs); |
201 | GST_API |
202 | void gst_structure_id_set (GstStructure * structure, |
203 | GQuark fieldname, |
204 | ...) G_GNUC_NULL_TERMINATED; |
205 | GST_API |
206 | void gst_structure_id_set_valist (GstStructure * structure, |
207 | GQuark fieldname, |
208 | va_list varargs); |
209 | GST_API |
210 | gboolean gst_structure_get_valist (const GstStructure * structure, |
211 | const char * first_fieldname, |
212 | va_list args); |
213 | GST_API |
214 | gboolean gst_structure_get (const GstStructure * structure, |
215 | const char * first_fieldname, |
216 | ...) G_GNUC_NULL_TERMINATED; |
217 | GST_API |
218 | gboolean gst_structure_id_get_valist (const GstStructure * structure, |
219 | GQuark first_field_id, |
220 | va_list args); |
221 | GST_API |
222 | gboolean gst_structure_id_get (const GstStructure * structure, |
223 | GQuark first_field_id, |
224 | ...) G_GNUC_NULL_TERMINATED; |
225 | GST_API |
226 | const GValue * gst_structure_id_get_value (const GstStructure * structure, |
227 | GQuark field); |
228 | GST_API |
229 | const GValue * gst_structure_get_value (const GstStructure * structure, |
230 | const gchar * fieldname); |
231 | GST_API |
232 | void gst_structure_remove_field (GstStructure * structure, |
233 | const gchar * fieldname); |
234 | GST_API |
235 | void gst_structure_remove_fields (GstStructure * structure, |
236 | const gchar * fieldname, |
237 | ...) G_GNUC_NULL_TERMINATED; |
238 | GST_API |
239 | void gst_structure_remove_fields_valist (GstStructure * structure, |
240 | const gchar * fieldname, |
241 | va_list varargs); |
242 | GST_API |
243 | void gst_structure_remove_all_fields (GstStructure * structure); |
244 | |
245 | GST_API |
246 | GType gst_structure_get_field_type (const GstStructure * structure, |
247 | const gchar * fieldname); |
248 | GST_API |
249 | gboolean gst_structure_foreach (const GstStructure * structure, |
250 | GstStructureForeachFunc func, |
251 | gpointer user_data); |
252 | GST_API |
253 | gboolean gst_structure_map_in_place (GstStructure * structure, |
254 | GstStructureMapFunc func, |
255 | gpointer user_data); |
256 | GST_API |
257 | void gst_structure_filter_and_map_in_place (GstStructure * structure, |
258 | GstStructureFilterMapFunc func, |
259 | gpointer user_data); |
260 | GST_API |
261 | gint gst_structure_n_fields (const GstStructure * structure); |
262 | |
263 | GST_API |
264 | const gchar * gst_structure_nth_field_name (const GstStructure * structure, |
265 | guint index); |
266 | GST_API |
267 | gboolean gst_structure_id_has_field (const GstStructure * structure, |
268 | GQuark field); |
269 | GST_API |
270 | gboolean gst_structure_id_has_field_typed (const GstStructure * structure, |
271 | GQuark field, |
272 | GType type); |
273 | GST_API |
274 | gboolean gst_structure_has_field (const GstStructure * structure, |
275 | const gchar * fieldname); |
276 | GST_API |
277 | gboolean gst_structure_has_field_typed (const GstStructure * structure, |
278 | const gchar * fieldname, |
279 | GType type); |
280 | |
281 | /* utility functions */ |
282 | |
283 | GST_API |
284 | gboolean gst_structure_get_boolean (const GstStructure * structure, |
285 | const gchar * fieldname, |
286 | gboolean * value); |
287 | GST_API |
288 | gboolean gst_structure_get_int (const GstStructure * structure, |
289 | const gchar * fieldname, |
290 | gint * value); |
291 | GST_API |
292 | gboolean gst_structure_get_uint (const GstStructure * structure, |
293 | const gchar * fieldname, |
294 | guint * value); |
295 | GST_API |
296 | gboolean gst_structure_get_int64 (const GstStructure * structure, |
297 | const gchar * fieldname, |
298 | gint64 * value); |
299 | GST_API |
300 | gboolean gst_structure_get_uint64 (const GstStructure * structure, |
301 | const gchar * fieldname, |
302 | guint64 * value); |
303 | GST_API |
304 | gboolean gst_structure_get_double (const GstStructure * structure, |
305 | const gchar * fieldname, |
306 | gdouble * value); |
307 | GST_API |
308 | gboolean gst_structure_get_date (const GstStructure * structure, |
309 | const gchar * fieldname, |
310 | GDate ** value); |
311 | GST_API |
312 | gboolean gst_structure_get_date_time (const GstStructure * structure, |
313 | const gchar * fieldname, |
314 | GstDateTime ** value); |
315 | GST_API |
316 | gboolean gst_structure_get_clock_time (const GstStructure * structure, |
317 | const gchar * fieldname, |
318 | GstClockTime * value); |
319 | GST_API |
320 | const gchar * gst_structure_get_string (const GstStructure * structure, |
321 | const gchar * fieldname); |
322 | GST_API |
323 | gboolean gst_structure_get_enum (const GstStructure * structure, |
324 | const gchar * fieldname, |
325 | GType enumtype, |
326 | gint * value); |
327 | GST_API |
328 | gboolean gst_structure_get_fraction (const GstStructure * structure, |
329 | const gchar * fieldname, |
330 | gint * value_numerator, |
331 | gint * value_denominator); |
332 | GST_API |
333 | gboolean gst_structure_get_flagset (const GstStructure * structure, |
334 | const gchar * fieldname, |
335 | guint * value_flags, |
336 | guint * value_mask); |
337 | GST_API |
338 | gboolean gst_structure_get_array (GstStructure * structure, |
339 | const gchar * fieldname, |
340 | GValueArray ** array); |
341 | GST_API |
342 | gboolean gst_structure_get_list (GstStructure * structure, |
343 | const gchar * fieldname, |
344 | GValueArray ** array); |
345 | GST_API |
346 | gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC; |
347 | GST_API |
348 | gchar * gst_structure_serialize (const GstStructure * structure, |
349 | GstSerializeFlags flags) G_GNUC_MALLOC; |
350 | |
351 | GST_API |
352 | GstStructure * gst_structure_from_string (const gchar * string, |
353 | gchar ** end) G_GNUC_MALLOC; |
354 | GST_API |
355 | gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure, |
356 | const char * field_name, |
357 | int target); |
358 | GST_API |
359 | gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure, |
360 | const char * field_name, |
361 | double target); |
362 | GST_API |
363 | gboolean gst_structure_fixate_field_boolean (GstStructure * structure, |
364 | const char * field_name, |
365 | gboolean target); |
366 | GST_API |
367 | gboolean gst_structure_fixate_field_string (GstStructure * structure, |
368 | const char * field_name, |
369 | const gchar * target); |
370 | GST_API |
371 | gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure, |
372 | const char * field_name, |
373 | const gint target_numerator, |
374 | const gint target_denominator); |
375 | GST_API |
376 | gboolean gst_structure_fixate_field (GstStructure * structure, |
377 | const char * field_name); |
378 | GST_API |
379 | void gst_structure_fixate (GstStructure * structure); |
380 | |
381 | GST_API |
382 | gboolean gst_structure_is_equal (const GstStructure * structure1, |
383 | const GstStructure * structure2); |
384 | GST_API |
385 | gboolean gst_structure_is_subset (const GstStructure * subset, |
386 | const GstStructure * superset); |
387 | GST_API |
388 | gboolean gst_structure_can_intersect (const GstStructure * struct1, |
389 | const GstStructure * struct2); |
390 | GST_API |
391 | GstStructure * gst_structure_intersect (const GstStructure * struct1, |
392 | const GstStructure * struct2) G_GNUC_MALLOC; |
393 | |
394 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free) |
395 | |
396 | G_END_DECLS |
397 | |
398 | #endif |
399 | |
400 | |