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., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, 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
31#define GST_TYPE_STRUCTURE (gst_structure_get_type ())
32#define GST_STRUCTURE(object) ((GstStructure *)(object))
33#define GST_IS_STRUCTURE(object) ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE))
34
35typedef struct _GstStructure GstStructure;
36
37/**
38 * GstStructureForeachFunc:
39 * @field_id: the #GQuark of the field name
40 * @value: the #GValue of the field
41 * @user_data: user data
42 *
43 * A function that will be called in gst_structure_foreach(). The function may
44 * not modify @value.
45 *
46 * Returns: TRUE if the foreach operation should continue, FALSE if
47 * the foreach operation should stop with FALSE.
48 */
49typedef gboolean (*GstStructureForeachFunc) (GQuark field_id,
50 const GValue * value,
51 gpointer user_data);
52
53/**
54 * GstStructureMapFunc:
55 * @field_id: the #GQuark of the field name
56 * @value: the #GValue of the field
57 * @user_data: user data
58 *
59 * A function that will be called in gst_structure_map_in_place(). The function
60 * may modify @value.
61 *
62 * Returns: TRUE if the map operation should continue, FALSE if
63 * the map operation should stop with FALSE.
64 */
65typedef gboolean (*GstStructureMapFunc) (GQuark field_id,
66 GValue * value,
67 gpointer user_data);
68
69/**
70 * GstStructure:
71 * @type: the GType of a structure
72 *
73 * The GstStructure object. Most fields are private.
74 */
75struct _GstStructure {
76 GType type;
77
78 /*< private >*/
79 GQuark name;
80
81 /* owned by parent structure, NULL if no parent */
82 gint *parent_refcount;
83
84 GArray *fields;
85
86 gpointer _gst_reserved;
87};
88
89GType gst_structure_get_type (void);
90
91GstStructure * gst_structure_empty_new (const gchar * name) G_GNUC_MALLOC;
92GstStructure * gst_structure_id_empty_new (GQuark quark) G_GNUC_MALLOC;
93GstStructure * gst_structure_new (const gchar * name,
94 const gchar * firstfield,
95 ...) G_GNUC_MALLOC;
96GstStructure * gst_structure_new_valist (const gchar * name,
97 const gchar * firstfield,
98 va_list varargs) G_GNUC_MALLOC;
99GstStructure * gst_structure_id_new (GQuark name_quark,
100 GQuark field_quark,
101 ...) G_GNUC_MALLOC;
102GstStructure * gst_structure_copy (const GstStructure *structure) G_GNUC_MALLOC;
103void gst_structure_set_parent_refcount (GstStructure *structure,
104 gint *refcount);
105void gst_structure_free (GstStructure *structure);
106
107const gchar * gst_structure_get_name (const GstStructure *structure);
108GQuark gst_structure_get_name_id (const GstStructure *structure);
109gboolean gst_structure_has_name (const GstStructure *structure,
110 const gchar *name);
111void gst_structure_set_name (GstStructure *structure,
112 const gchar *name);
113
114void gst_structure_id_set_value (GstStructure *structure,
115 GQuark field,
116 const GValue *value);
117void gst_structure_set_value (GstStructure *structure,
118 const gchar *fieldname,
119 const GValue *value);
120void gst_structure_id_take_value (GstStructure *structure,
121 GQuark field,
122 GValue *value);
123void gst_structure_take_value (GstStructure *structure,
124 const gchar *fieldname,
125 GValue *value);
126void gst_structure_set (GstStructure *structure,
127 const gchar *fieldname,
128 ...) G_GNUC_NULL_TERMINATED;
129
130void gst_structure_set_valist (GstStructure *structure,
131 const gchar *fieldname,
132 va_list varargs);
133
134void gst_structure_id_set (GstStructure *structure,
135 GQuark fieldname,
136 ...) G_GNUC_NULL_TERMINATED;
137
138void gst_structure_id_set_valist (GstStructure *structure,
139 GQuark fieldname,
140 va_list varargs);
141
142gboolean gst_structure_get_valist (const GstStructure *structure,
143 const char *first_fieldname,
144 va_list args);
145
146gboolean gst_structure_get (const GstStructure *structure,
147 const char *first_fieldname,
148 ...) G_GNUC_NULL_TERMINATED;
149
150gboolean gst_structure_id_get_valist (const GstStructure *structure,
151 GQuark first_field_id,
152 va_list args);
153
154gboolean gst_structure_id_get (const GstStructure *structure,
155 GQuark first_field_id,
156 ...) G_GNUC_NULL_TERMINATED;
157
158const GValue * gst_structure_id_get_value (const GstStructure *structure,
159 GQuark field);
160const GValue * gst_structure_get_value (const GstStructure *structure,
161 const gchar *fieldname);
162void gst_structure_remove_field (GstStructure *structure,
163 const gchar *fieldname);
164void gst_structure_remove_fields (GstStructure *structure,
165 const gchar *fieldname,
166 ...) G_GNUC_NULL_TERMINATED;
167void gst_structure_remove_fields_valist (GstStructure *structure,
168 const gchar *fieldname,
169 va_list varargs);
170void gst_structure_remove_all_fields (GstStructure *structure);
171
172GType gst_structure_get_field_type (const GstStructure *structure,
173 const gchar *fieldname);
174gboolean gst_structure_foreach (const GstStructure *structure,
175 GstStructureForeachFunc func,
176 gpointer user_data);
177gboolean gst_structure_map_in_place (GstStructure *structure,
178 GstStructureMapFunc func,
179 gpointer user_data);
180gint gst_structure_n_fields (const GstStructure *structure);
181const gchar * gst_structure_nth_field_name (const GstStructure *structure, guint index);
182gboolean gst_structure_id_has_field (const GstStructure *structure,
183 GQuark field);
184gboolean gst_structure_id_has_field_typed (const GstStructure *structure,
185 GQuark field,
186 GType type);
187gboolean gst_structure_has_field (const GstStructure *structure,
188 const gchar *fieldname);
189gboolean gst_structure_has_field_typed (const GstStructure *structure,
190 const gchar *fieldname,
191 GType type);
192
193/* utility functions */
194gboolean gst_structure_get_boolean (const GstStructure *structure,
195 const gchar *fieldname,
196 gboolean *value);
197gboolean gst_structure_get_int (const GstStructure *structure,
198 const gchar *fieldname,
199 gint *value);
200gboolean gst_structure_get_uint (const GstStructure *structure,
201 const gchar *fieldname,
202 guint *value);
203gboolean gst_structure_get_fourcc (const GstStructure *structure,
204 const gchar *fieldname,
205 guint32 *value);
206gboolean gst_structure_get_double (const GstStructure *structure,
207 const gchar *fieldname,
208 gdouble *value);
209gboolean gst_structure_get_date (const GstStructure *structure,
210 const gchar *fieldname,
211 GDate **value);
212gboolean gst_structure_get_date_time (const GstStructure *structure,
213 const gchar *fieldname,
214 GstDateTime **value);
215gboolean gst_structure_get_clock_time (const GstStructure *structure,
216 const gchar *fieldname,
217 GstClockTime *value);
218const gchar * gst_structure_get_string (const GstStructure *structure,
219 const gchar *fieldname);
220gboolean gst_structure_get_enum (const GstStructure *structure,
221 const gchar *fieldname,
222 GType enumtype,
223 gint *value);
224gboolean gst_structure_get_fraction (const GstStructure *structure,
225 const gchar *fieldname,
226 gint *value_numerator,
227 gint *value_denominator);
228
229gchar * gst_structure_to_string (const GstStructure *structure) G_GNUC_MALLOC;
230GstStructure * gst_structure_from_string (const gchar *string,
231 gchar **end) G_GNUC_MALLOC;
232
233gboolean gst_structure_fixate_field_nearest_int (GstStructure *structure,
234 const char *field_name,
235 int target);
236gboolean gst_structure_fixate_field_nearest_double (GstStructure *structure,
237 const char *field_name,
238 double target);
239
240gboolean gst_structure_fixate_field_boolean (GstStructure *structure,
241 const char *field_name,
242 gboolean target);
243gboolean gst_structure_fixate_field_string (GstStructure *structure,
244 const char *field_name,
245 const gchar *target);
246gboolean gst_structure_fixate_field_nearest_fraction (GstStructure *structure,
247 const char *field_name,
248 const gint target_numerator,
249 const gint target_denominator);
250
251gboolean gst_structure_is_equal(const GstStructure *structure1,
252 const GstStructure *structure2);
253gboolean gst_structure_is_subset(const GstStructure *subset,
254 const GstStructure *superset);
255gboolean gst_structure_can_intersect(const GstStructure *struct1,
256 const GstStructure *struct2);
257GstStructure* gst_structure_intersect (const GstStructure *struct1,
258 const GstStructure *struct2) G_GNUC_MALLOC;
259
260G_END_DECLS
261
262#endif
263
264