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