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
29G_BEGIN_DECLS
30
31GST_API GType _gst_structure_type;
32
33typedef struct _GstStructure GstStructure;
34
35/**
36 * GST_SERIALIZE_FLAG_STRICT:
37 *
38 * Serialization fails if a value cannot be serialized instead of using
39 * placeholder "NULL" value (e.g. pointers, objects).
40 *
41 * Since: 1.24
42 */
43
44/**
45 * GstSerializeFlags:
46 * @GST_SERIALIZE_FLAG_NONE: No special flags specified.
47 * @GST_SERIALIZE_FLAG_BACKWARD_COMPAT: Serialize using the old format for
48 * nested structures.
49 * @GST_SERIALIZE_FLAG_STRICT: Serialization fails if a value cannot be
50 * serialized instead of using placeholder "NULL" value (e.g. pointers,
51 * objects). (Since 1.24)
52 *
53 * Since: 1.20
54 */
55typedef enum
56{
57 GST_SERIALIZE_FLAG_NONE = 0,
58 GST_SERIALIZE_FLAG_BACKWARD_COMPAT = (1 << 0),
59 GST_SERIALIZE_FLAG_STRICT = (1 << 1),
60} GstSerializeFlags;
61
62#define GST_TYPE_STRUCTURE (_gst_structure_type)
63#define GST_IS_STRUCTURE(object) ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE))
64#define GST_STRUCTURE_CAST(object) ((GstStructure *)(object))
65#define GST_STRUCTURE(object) (GST_STRUCTURE_CAST(object))
66
67
68/**
69 * GstStructureForeachFunc:
70 * @field_id: the #GQuark of the field name
71 * @value: the #GValue of the field
72 * @user_data: user data
73 *
74 * A function that will be called in gst_structure_foreach(). The function may
75 * not modify @value.
76 *
77 * Returns: %TRUE if the foreach operation should continue, %FALSE if
78 * the foreach operation should stop with %FALSE.
79 */
80typedef gboolean (*GstStructureForeachFunc) (GQuark field_id,
81 const GValue * value,
82 gpointer user_data);
83
84/**
85 * GstStructureMapFunc:
86 * @field_id: the #GQuark of the field name
87 * @value: the #GValue of the field
88 * @user_data: user data
89 *
90 * A function that will be called in gst_structure_map_in_place(). The function
91 * may modify @value.
92 *
93 * Returns: %TRUE if the map operation should continue, %FALSE if
94 * the map operation should stop with %FALSE.
95 */
96typedef gboolean (*GstStructureMapFunc) (GQuark field_id,
97 GValue * value,
98 gpointer user_data);
99
100/**
101 * GstStructureFilterMapFunc:
102 * @field_id: the #GQuark of the field name
103 * @value: the #GValue of the field
104 * @user_data: user data
105 *
106 * A function that will be called in gst_structure_filter_and_map_in_place().
107 * The function may modify @value, and the value will be removed from
108 * the structure if %FALSE is returned.
109 *
110 * Returns: %TRUE if the field should be preserved, %FALSE if it
111 * should be removed.
112 */
113typedef gboolean (*GstStructureFilterMapFunc) (GQuark field_id,
114 GValue * value,
115 gpointer user_data);
116
117/**
118 * GstStructure:
119 * @type: the GType of a structure
120 *
121 * The GstStructure object. Most fields are private.
122 */
123struct _GstStructure {
124 GType type;
125
126 /*< private >*/
127 GQuark name;
128};
129
130GST_API
131GType gst_structure_get_type (void);
132
133GST_API
134GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC;
135
136GST_API
137GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC;
138
139GST_API
140GstStructure * gst_structure_new (const gchar * name,
141 const gchar * firstfield,
142 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC;
143GST_API
144GstStructure * gst_structure_new_valist (const gchar * name,
145 const gchar * firstfield,
146 va_list varargs) G_GNUC_MALLOC;
147GST_API
148GstStructure * gst_structure_new_id (GQuark name_quark,
149 GQuark field_quark,
150 ...) G_GNUC_MALLOC;
151GST_API
152GstStructure * gst_structure_new_from_string (const gchar * string);
153
154GST_API
155GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC;
156
157GST_API
158gboolean gst_structure_set_parent_refcount (GstStructure * structure,
159 gint * refcount);
160GST_API
161void gst_structure_free (GstStructure * structure);
162
163GST_API
164void gst_clear_structure (GstStructure **structure_ptr);
165#define gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free)
166
167GST_API
168gboolean gst_structure_take (GstStructure ** oldstr_ptr,
169 GstStructure * newstr);
170GST_API
171const gchar * gst_structure_get_name (const GstStructure * structure);
172
173GST_API
174GQuark gst_structure_get_name_id (const GstStructure * structure);
175
176GST_API
177gboolean gst_structure_has_name (const GstStructure * structure,
178 const gchar * name);
179GST_API
180void gst_structure_set_name (GstStructure * structure,
181 const gchar * name);
182GST_API
183void gst_structure_id_set_value (GstStructure * structure,
184 GQuark field,
185 const GValue * value);
186GST_API
187void gst_structure_set_value (GstStructure * structure,
188 const gchar * fieldname,
189 const GValue * value);
190GST_API
191void gst_structure_set_array (GstStructure * structure,
192 const gchar * fieldname,
193 const GValueArray * array);
194GST_API
195void gst_structure_set_list (GstStructure * structure,
196 const gchar * fieldname,
197 const GValueArray * array);
198GST_API
199void gst_structure_id_take_value (GstStructure * structure,
200 GQuark field,
201 GValue * value);
202GST_API
203void gst_structure_take_value (GstStructure * structure,
204 const gchar * fieldname,
205 GValue * value);
206GST_API
207void gst_structure_set (GstStructure * structure,
208 const gchar * fieldname,
209 ...) G_GNUC_NULL_TERMINATED;
210GST_API
211void gst_structure_set_valist (GstStructure * structure,
212 const gchar * fieldname,
213 va_list varargs);
214GST_API
215void gst_structure_id_set (GstStructure * structure,
216 GQuark fieldname,
217 ...) G_GNUC_NULL_TERMINATED;
218GST_API
219void gst_structure_id_set_valist (GstStructure * structure,
220 GQuark fieldname,
221 va_list varargs);
222GST_API
223gboolean gst_structure_get_valist (const GstStructure * structure,
224 const char * first_fieldname,
225 va_list args);
226GST_API
227gboolean gst_structure_get (const GstStructure * structure,
228 const char * first_fieldname,
229 ...) G_GNUC_NULL_TERMINATED;
230GST_API
231gboolean gst_structure_id_get_valist (const GstStructure * structure,
232 GQuark first_field_id,
233 va_list args);
234GST_API
235gboolean gst_structure_id_get (const GstStructure * structure,
236 GQuark first_field_id,
237 ...) G_GNUC_NULL_TERMINATED;
238GST_API
239const GValue * gst_structure_id_get_value (const GstStructure * structure,
240 GQuark field);
241GST_API
242const GValue * gst_structure_get_value (const GstStructure * structure,
243 const gchar * fieldname);
244GST_API
245void gst_structure_remove_field (GstStructure * structure,
246 const gchar * fieldname);
247GST_API
248void gst_structure_remove_fields (GstStructure * structure,
249 const gchar * fieldname,
250 ...) G_GNUC_NULL_TERMINATED;
251GST_API
252void gst_structure_remove_fields_valist (GstStructure * structure,
253 const gchar * fieldname,
254 va_list varargs);
255GST_API
256void gst_structure_remove_all_fields (GstStructure * structure);
257
258GST_API
259GType gst_structure_get_field_type (const GstStructure * structure,
260 const gchar * fieldname);
261GST_API
262gboolean gst_structure_foreach (const GstStructure * structure,
263 GstStructureForeachFunc func,
264 gpointer user_data);
265GST_API
266gboolean gst_structure_map_in_place (GstStructure * structure,
267 GstStructureMapFunc func,
268 gpointer user_data);
269GST_API
270void gst_structure_filter_and_map_in_place (GstStructure * structure,
271 GstStructureFilterMapFunc func,
272 gpointer user_data);
273GST_API
274gint gst_structure_n_fields (const GstStructure * structure);
275
276GST_API
277const gchar * gst_structure_nth_field_name (const GstStructure * structure,
278 guint index);
279GST_API
280gboolean gst_structure_id_has_field (const GstStructure * structure,
281 GQuark field);
282GST_API
283gboolean gst_structure_id_has_field_typed (const GstStructure * structure,
284 GQuark field,
285 GType type);
286GST_API
287gboolean gst_structure_has_field (const GstStructure * structure,
288 const gchar * fieldname);
289GST_API
290gboolean gst_structure_has_field_typed (const GstStructure * structure,
291 const gchar * fieldname,
292 GType type);
293
294/* utility functions */
295
296GST_API
297gboolean gst_structure_get_boolean (const GstStructure * structure,
298 const gchar * fieldname,
299 gboolean * value);
300GST_API
301gboolean gst_structure_get_int (const GstStructure * structure,
302 const gchar * fieldname,
303 gint * value);
304GST_API
305gboolean gst_structure_get_uint (const GstStructure * structure,
306 const gchar * fieldname,
307 guint * value);
308GST_API
309gboolean gst_structure_get_int64 (const GstStructure * structure,
310 const gchar * fieldname,
311 gint64 * value);
312GST_API
313gboolean gst_structure_get_uint64 (const GstStructure * structure,
314 const gchar * fieldname,
315 guint64 * value);
316GST_API
317gboolean gst_structure_get_double (const GstStructure * structure,
318 const gchar * fieldname,
319 gdouble * value);
320GST_API
321gboolean gst_structure_get_date (const GstStructure * structure,
322 const gchar * fieldname,
323 GDate ** value);
324GST_API
325gboolean gst_structure_get_date_time (const GstStructure * structure,
326 const gchar * fieldname,
327 GstDateTime ** value);
328GST_API
329gboolean gst_structure_get_clock_time (const GstStructure * structure,
330 const gchar * fieldname,
331 GstClockTime * value);
332GST_API
333const gchar * gst_structure_get_string (const GstStructure * structure,
334 const gchar * fieldname);
335GST_API
336gboolean gst_structure_get_enum (const GstStructure * structure,
337 const gchar * fieldname,
338 GType enumtype,
339 gint * value);
340GST_API
341gboolean gst_structure_get_fraction (const GstStructure * structure,
342 const gchar * fieldname,
343 gint * value_numerator,
344 gint * value_denominator);
345GST_API
346gboolean gst_structure_get_flagset (const GstStructure * structure,
347 const gchar * fieldname,
348 guint * value_flags,
349 guint * value_mask);
350GST_API
351gboolean gst_structure_get_array (GstStructure * structure,
352 const gchar * fieldname,
353 GValueArray ** array);
354GST_API
355gboolean gst_structure_get_list (GstStructure * structure,
356 const gchar * fieldname,
357 GValueArray ** array);
358
359GST_API
360gboolean gst_structure_get_flags (const GstStructure * structure,
361 const gchar * fieldname,
362 GType flags_type,
363 guint * value);
364
365GST_API
366gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC;
367GST_DEPRECATED_FOR(gst_structure_serialize_full)
368gchar * gst_structure_serialize (const GstStructure * structure,
369 GstSerializeFlags flags) G_GNUC_MALLOC;
370GST_API
371gchar * gst_structure_serialize_full (const GstStructure * structure,
372 GstSerializeFlags flags) G_GNUC_MALLOC;
373
374GST_API
375GstStructure * gst_structure_from_string (const gchar * string,
376 gchar ** end) G_GNUC_MALLOC;
377GST_API
378gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure,
379 const char * field_name,
380 int target);
381GST_API
382gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure,
383 const char * field_name,
384 double target);
385GST_API
386gboolean gst_structure_fixate_field_boolean (GstStructure * structure,
387 const char * field_name,
388 gboolean target);
389GST_API
390gboolean gst_structure_fixate_field_string (GstStructure * structure,
391 const char * field_name,
392 const gchar * target);
393GST_API
394gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
395 const char * field_name,
396 const gint target_numerator,
397 const gint target_denominator);
398GST_API
399gboolean gst_structure_fixate_field (GstStructure * structure,
400 const char * field_name);
401GST_API
402void gst_structure_fixate (GstStructure * structure);
403
404GST_API
405gboolean gst_structure_is_equal (const GstStructure * structure1,
406 const GstStructure * structure2);
407GST_API
408gboolean gst_structure_is_subset (const GstStructure * subset,
409 const GstStructure * superset);
410GST_API
411gboolean gst_structure_can_intersect (const GstStructure * struct1,
412 const GstStructure * struct2);
413GST_API
414GstStructure * gst_structure_intersect (const GstStructure * struct1,
415 const GstStructure * struct2) G_GNUC_MALLOC;
416
417G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)
418
419G_END_DECLS
420
421#endif
422
423

source code of include/gstreamer-1.0/gst/gststructure.h