1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Structure;
26 
27 private import glib.ConstructionException;
28 private import glib.Date;
29 private import glib.Str;
30 private import gobject.ObjectG;
31 private import gobject.Value;
32 private import gobject.ValueArray;
33 private import gstreamer.DateTime;
34 private import gstreamer.c.functions;
35 public  import gstreamer.c.types;
36 public  import gstreamerc.gstreamertypes;
37 private import gtkd.Loader;
38 
39 
40 /**
41  * A #GstStructure is a collection of key/value pairs. The keys are expressed
42  * as GQuarks and the values can be of any GType.
43  * 
44  * In addition to the key/value pairs, a #GstStructure also has a name. The name
45  * starts with a letter and can be filled by letters, numbers and any of "/-_.:".
46  * 
47  * #GstStructure is used by various GStreamer subsystems to store information
48  * in a flexible and extensible way. A #GstStructure does not have a refcount
49  * because it usually is part of a higher level object such as #GstCaps,
50  * #GstMessage, #GstEvent, #GstQuery. It provides a means to enforce mutability
51  * using the refcount of the parent with the gst_structure_set_parent_refcount()
52  * method.
53  * 
54  * A #GstStructure can be created with gst_structure_new_empty() or
55  * gst_structure_new(), which both take a name and an optional set of
56  * key/value pairs along with the types of the values.
57  * 
58  * Field values can be changed with gst_structure_set_value() or
59  * gst_structure_set().
60  * 
61  * Field values can be retrieved with gst_structure_get_value() or the more
62  * convenient gst_structure_get_*() functions.
63  * 
64  * Fields can be removed with gst_structure_remove_field() or
65  * gst_structure_remove_fields().
66  * 
67  * Strings in structures must be ASCII or UTF-8 encoded. Other encodings are
68  * not allowed. Strings may be %NULL however.
69  * 
70  * Be aware that the current #GstCaps / #GstStructure serialization into string
71  * has limited support for nested #GstCaps / #GstStructure fields. It can only
72  * support one level of nesting. Using more levels will lead to unexpected
73  * behavior when using serialization features, such as gst_caps_to_string() or
74  * gst_value_serialize() and their counterparts.
75  */
76 public class Structure
77 {
78 	/** the main Gtk struct */
79 	protected GstStructure* gstStructure;
80 	protected bool ownedRef;
81 
82 	/** Get the main Gtk struct */
83 	public GstStructure* getStructureStruct(bool transferOwnership = false)
84 	{
85 		if (transferOwnership)
86 			ownedRef = false;
87 		return gstStructure;
88 	}
89 
90 	/** the main Gtk struct as a void* */
91 	protected void* getStruct()
92 	{
93 		return cast(void*)gstStructure;
94 	}
95 
96 	/**
97 	 * Sets our main struct and passes it to the parent class.
98 	 */
99 	public this (GstStructure* gstStructure, bool ownedRef = false)
100 	{
101 		this.gstStructure = gstStructure;
102 		this.ownedRef = ownedRef;
103 	}
104 
105 	~this ()
106 	{
107 		if ( Linker.isLoaded(LIBRARY_GSTREAMER) && ownedRef )
108 			gst_structure_free(gstStructure);
109 	}
110 
111 	public static Structure fromString(string name)
112 	{
113 		auto p = gst_structure_new_from_string(Str.toStringz(name));
114 
115 		if(p is null)
116 		{
117 			throw new ConstructionException("null returned by gst_structure_new_from_string(Str.toStringz(name))");
118 		}
119 
120 		return new Structure(cast(GstStructure*)p); //, true);
121 	}
122 
123 	/**
124 	 */
125 
126 	/** */
127 	public static GType getType()
128 	{
129 		return gst_structure_get_type();
130 	}
131 
132 	/**
133 	 * Creates a new, empty #GstStructure with the given @name.
134 	 *
135 	 * See gst_structure_set_name() for constraints on the @name parameter.
136 	 *
137 	 * Free-function: gst_structure_free
138 	 *
139 	 * Params:
140 	 *     name = name of new structure
141 	 *
142 	 * Returns: a new, empty #GstStructure
143 	 *
144 	 * Throws: ConstructionException GTK+ fails to create the object.
145 	 */
146 	public this(string name)
147 	{
148 		auto p = gst_structure_new_empty(Str.toStringz(name));
149 
150 		if(p is null)
151 		{
152 			throw new ConstructionException("null returned by new_empty");
153 		}
154 
155 		this(cast(GstStructure*) p);
156 	}
157 
158 	/**
159 	 * Creates a new, empty #GstStructure with the given name as a GQuark.
160 	 *
161 	 * Free-function: gst_structure_free
162 	 *
163 	 * Params:
164 	 *     quark = name of new structure
165 	 *
166 	 * Returns: a new, empty #GstStructure
167 	 *
168 	 * Throws: ConstructionException GTK+ fails to create the object.
169 	 */
170 	public this(GQuark quark)
171 	{
172 		auto p = gst_structure_new_id_empty(quark);
173 
174 		if(p is null)
175 		{
176 			throw new ConstructionException("null returned by new_id_empty");
177 		}
178 
179 		this(cast(GstStructure*) p);
180 	}
181 
182 	/**
183 	 * Creates a new #GstStructure with the given @name.  Structure fields
184 	 * are set according to the varargs in a manner similar to
185 	 * gst_structure_new().
186 	 *
187 	 * See gst_structure_set_name() for constraints on the @name parameter.
188 	 *
189 	 * Free-function: gst_structure_free
190 	 *
191 	 * Params:
192 	 *     name = name of new structure
193 	 *     firstfield = name of first field to set
194 	 *     varargs = variable argument list
195 	 *
196 	 * Returns: a new #GstStructure
197 	 *
198 	 * Throws: ConstructionException GTK+ fails to create the object.
199 	 */
200 	public this(string name, string firstfield, void* varargs)
201 	{
202 		auto p = gst_structure_new_valist(Str.toStringz(name), Str.toStringz(firstfield), varargs);
203 
204 		if(p is null)
205 		{
206 			throw new ConstructionException("null returned by new_valist");
207 		}
208 
209 		this(cast(GstStructure*) p);
210 	}
211 
212 	/**
213 	 * Tries intersecting @struct1 and @struct2 and reports whether the result
214 	 * would not be empty.
215 	 *
216 	 * Params:
217 	 *     struct2 = a #GstStructure
218 	 *
219 	 * Returns: %TRUE if intersection would not be empty
220 	 */
221 	public bool canIntersect(Structure struct2)
222 	{
223 		return gst_structure_can_intersect(gstStructure, (struct2 is null) ? null : struct2.getStructureStruct()) != 0;
224 	}
225 
226 	/**
227 	 * Duplicates a #GstStructure and all its fields and values.
228 	 *
229 	 * Free-function: gst_structure_free
230 	 *
231 	 * Returns: a new #GstStructure.
232 	 */
233 	public Structure copy()
234 	{
235 		auto p = gst_structure_copy(gstStructure);
236 
237 		if(p is null)
238 		{
239 			return null;
240 		}
241 
242 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p, true);
243 	}
244 
245 	/**
246 	 * Calls the provided function once for each field in the #GstStructure. In
247 	 * contrast to gst_structure_foreach(), the function may modify the fields.
248 	 * In contrast to gst_structure_map_in_place(), the field is removed from
249 	 * the structure if %FALSE is returned from the function.
250 	 * The structure must be mutable.
251 	 *
252 	 * Params:
253 	 *     func = a function to call for each field
254 	 *     userData = private data
255 	 *
256 	 * Since: 1.6
257 	 */
258 	public void filterAndMapInPlace(GstStructureFilterMapFunc func, void* userData)
259 	{
260 		gst_structure_filter_and_map_in_place(gstStructure, func, userData);
261 	}
262 
263 	/**
264 	 * Fixate all values in @structure using gst_value_fixate().
265 	 * @structure will be modified in-place and should be writable.
266 	 */
267 	public void fixate()
268 	{
269 		gst_structure_fixate(gstStructure);
270 	}
271 
272 	/**
273 	 * Fixates a #GstStructure by changing the given field with its fixated value.
274 	 *
275 	 * Params:
276 	 *     fieldName = a field in @structure
277 	 *
278 	 * Returns: %TRUE if the structure field could be fixated
279 	 */
280 	public bool fixateField(string fieldName)
281 	{
282 		return gst_structure_fixate_field(gstStructure, Str.toStringz(fieldName)) != 0;
283 	}
284 
285 	/**
286 	 * Fixates a #GstStructure by changing the given @field_name field to the given
287 	 * @target boolean if that field is not fixed yet.
288 	 *
289 	 * Params:
290 	 *     fieldName = a field in @structure
291 	 *     target = the target value of the fixation
292 	 *
293 	 * Returns: %TRUE if the structure could be fixated
294 	 */
295 	public bool fixateFieldBoolean(string fieldName, bool target)
296 	{
297 		return gst_structure_fixate_field_boolean(gstStructure, Str.toStringz(fieldName), target) != 0;
298 	}
299 
300 	/**
301 	 * Fixates a #GstStructure by changing the given field to the nearest
302 	 * double to @target that is a subset of the existing field.
303 	 *
304 	 * Params:
305 	 *     fieldName = a field in @structure
306 	 *     target = the target value of the fixation
307 	 *
308 	 * Returns: %TRUE if the structure could be fixated
309 	 */
310 	public bool fixateFieldNearestDouble(string fieldName, double target)
311 	{
312 		return gst_structure_fixate_field_nearest_double(gstStructure, Str.toStringz(fieldName), target) != 0;
313 	}
314 
315 	/**
316 	 * Fixates a #GstStructure by changing the given field to the nearest
317 	 * fraction to @target_numerator/@target_denominator that is a subset
318 	 * of the existing field.
319 	 *
320 	 * Params:
321 	 *     fieldName = a field in @structure
322 	 *     targetNumerator = The numerator of the target value of the fixation
323 	 *     targetDenominator = The denominator of the target value of the fixation
324 	 *
325 	 * Returns: %TRUE if the structure could be fixated
326 	 */
327 	public bool fixateFieldNearestFraction(string fieldName, int targetNumerator, int targetDenominator)
328 	{
329 		return gst_structure_fixate_field_nearest_fraction(gstStructure, Str.toStringz(fieldName), targetNumerator, targetDenominator) != 0;
330 	}
331 
332 	/**
333 	 * Fixates a #GstStructure by changing the given field to the nearest
334 	 * integer to @target that is a subset of the existing field.
335 	 *
336 	 * Params:
337 	 *     fieldName = a field in @structure
338 	 *     target = the target value of the fixation
339 	 *
340 	 * Returns: %TRUE if the structure could be fixated
341 	 */
342 	public bool fixateFieldNearestInt(string fieldName, int target)
343 	{
344 		return gst_structure_fixate_field_nearest_int(gstStructure, Str.toStringz(fieldName), target) != 0;
345 	}
346 
347 	/**
348 	 * Fixates a #GstStructure by changing the given @field_name field to the given
349 	 * @target string if that field is not fixed yet.
350 	 *
351 	 * Params:
352 	 *     fieldName = a field in @structure
353 	 *     target = the target value of the fixation
354 	 *
355 	 * Returns: %TRUE if the structure could be fixated
356 	 */
357 	public bool fixateFieldString(string fieldName, string target)
358 	{
359 		return gst_structure_fixate_field_string(gstStructure, Str.toStringz(fieldName), Str.toStringz(target)) != 0;
360 	}
361 
362 	alias foreac = foreach_;
363 	/**
364 	 * Calls the provided function once for each field in the #GstStructure. The
365 	 * function must not modify the fields. Also see gst_structure_map_in_place()
366 	 * and gst_structure_filter_and_map_in_place().
367 	 *
368 	 * Params:
369 	 *     func = a function to call for each field
370 	 *     userData = private data
371 	 *
372 	 * Returns: %TRUE if the supplied function returns %TRUE For each of the fields,
373 	 *     %FALSE otherwise.
374 	 */
375 	public bool foreach_(GstStructureForeachFunc func, void* userData)
376 	{
377 		return gst_structure_foreach(gstStructure, func, userData) != 0;
378 	}
379 
380 	/**
381 	 * Frees a #GstStructure and all its fields and values. The structure must not
382 	 * have a parent when this function is called.
383 	 */
384 	public void free()
385 	{
386 		gst_structure_free(gstStructure);
387 		ownedRef = false;
388 	}
389 
390 	/**
391 	 * This is useful in language bindings where unknown #GValue types are not
392 	 * supported. This function will convert the %GST_TYPE_ARRAY into a newly
393 	 * allocated #GValueArray and return it through @array. Be aware that this is
394 	 * slower then getting the #GValue directly.
395 	 *
396 	 * Params:
397 	 *     fieldname = the name of a field
398 	 *     array = a pointer to a #GValueArray
399 	 *
400 	 * Returns: %TRUE if the value could be set correctly. If there was no field
401 	 *     with @fieldname or the existing field did not contain a %GST_TYPE_ARRAY,
402 	 *     this function returns %FALSE.
403 	 */
404 	public bool getArray(string fieldname, out ValueArray array)
405 	{
406 		GValueArray* outarray = null;
407 
408 		auto p = gst_structure_get_array(gstStructure, Str.toStringz(fieldname), &outarray) != 0;
409 
410 		array = ObjectG.getDObject!(ValueArray)(outarray);
411 
412 		return p;
413 	}
414 
415 	/**
416 	 * Sets the boolean pointed to by @value corresponding to the value of the
417 	 * given field.  Caller is responsible for making sure the field exists
418 	 * and has the correct type.
419 	 *
420 	 * Params:
421 	 *     fieldname = the name of a field
422 	 *     value = a pointer to a #gboolean to set
423 	 *
424 	 * Returns: %TRUE if the value could be set correctly. If there was no field
425 	 *     with @fieldname or the existing field did not contain a boolean, this
426 	 *     function returns %FALSE.
427 	 */
428 	public bool getBoolean(string fieldname, out bool value)
429 	{
430 		int outvalue;
431 
432 		auto p = gst_structure_get_boolean(gstStructure, Str.toStringz(fieldname), &outvalue) != 0;
433 
434 		value = (outvalue == 1);
435 
436 		return p;
437 	}
438 
439 	/**
440 	 * Sets the clock time pointed to by @value corresponding to the clock time
441 	 * of the given field.  Caller is responsible for making sure the field exists
442 	 * and has the correct type.
443 	 *
444 	 * Params:
445 	 *     fieldname = the name of a field
446 	 *     value = a pointer to a #GstClockTime to set
447 	 *
448 	 * Returns: %TRUE if the value could be set correctly. If there was no field
449 	 *     with @fieldname or the existing field did not contain a #GstClockTime, this
450 	 *     function returns %FALSE.
451 	 */
452 	public bool getClockTime(string fieldname, out GstClockTime value)
453 	{
454 		return gst_structure_get_clock_time(gstStructure, Str.toStringz(fieldname), &value) != 0;
455 	}
456 
457 	/**
458 	 * Sets the date pointed to by @value corresponding to the date of the
459 	 * given field.  Caller is responsible for making sure the field exists
460 	 * and has the correct type.
461 	 *
462 	 * On success @value will point to a newly-allocated copy of the date which
463 	 * should be freed with g_date_free() when no longer needed (note: this is
464 	 * inconsistent with e.g. gst_structure_get_string() which doesn't return a
465 	 * copy of the string).
466 	 *
467 	 * Params:
468 	 *     fieldname = the name of a field
469 	 *     value = a pointer to a #GDate to set
470 	 *
471 	 * Returns: %TRUE if the value could be set correctly. If there was no field
472 	 *     with @fieldname or the existing field did not contain a data, this function
473 	 *     returns %FALSE.
474 	 */
475 	public bool getDate(string fieldname, out Date value)
476 	{
477 		GDate* outvalue = null;
478 
479 		auto p = gst_structure_get_date(gstStructure, Str.toStringz(fieldname), &outvalue) != 0;
480 
481 		value = new Date(outvalue);
482 
483 		return p;
484 	}
485 
486 	/**
487 	 * Sets the datetime pointed to by @value corresponding to the datetime of the
488 	 * given field. Caller is responsible for making sure the field exists
489 	 * and has the correct type.
490 	 *
491 	 * On success @value will point to a reference of the datetime which
492 	 * should be unreffed with gst_date_time_unref() when no longer needed
493 	 * (note: this is inconsistent with e.g. gst_structure_get_string()
494 	 * which doesn't return a copy of the string).
495 	 *
496 	 * Params:
497 	 *     fieldname = the name of a field
498 	 *     value = a pointer to a #GstDateTime to set
499 	 *
500 	 * Returns: %TRUE if the value could be set correctly. If there was no field
501 	 *     with @fieldname or the existing field did not contain a data, this function
502 	 *     returns %FALSE.
503 	 */
504 	public bool getDateTime(string fieldname, out DateTime value)
505 	{
506 		GstDateTime* outvalue = null;
507 
508 		auto p = gst_structure_get_date_time(gstStructure, Str.toStringz(fieldname), &outvalue) != 0;
509 
510 		value = ObjectG.getDObject!(DateTime)(outvalue);
511 
512 		return p;
513 	}
514 
515 	/**
516 	 * Sets the double pointed to by @value corresponding to the value of the
517 	 * given field.  Caller is responsible for making sure the field exists
518 	 * and has the correct type.
519 	 *
520 	 * Params:
521 	 *     fieldname = the name of a field
522 	 *     value = a pointer to a gdouble to set
523 	 *
524 	 * Returns: %TRUE if the value could be set correctly. If there was no field
525 	 *     with @fieldname or the existing field did not contain a double, this
526 	 *     function returns %FALSE.
527 	 */
528 	public bool getDouble(string fieldname, out double value)
529 	{
530 		return gst_structure_get_double(gstStructure, Str.toStringz(fieldname), &value) != 0;
531 	}
532 
533 	/**
534 	 * Sets the int pointed to by @value corresponding to the value of the
535 	 * given field.  Caller is responsible for making sure the field exists,
536 	 * has the correct type and that the enumtype is correct.
537 	 *
538 	 * Params:
539 	 *     fieldname = the name of a field
540 	 *     enumtype = the enum type of a field
541 	 *     value = a pointer to an int to set
542 	 *
543 	 * Returns: %TRUE if the value could be set correctly. If there was no field
544 	 *     with @fieldname or the existing field did not contain an enum of the given
545 	 *     type, this function returns %FALSE.
546 	 */
547 	public bool getEnum(string fieldname, GType enumtype, out int value)
548 	{
549 		return gst_structure_get_enum(gstStructure, Str.toStringz(fieldname), enumtype, &value) != 0;
550 	}
551 
552 	/**
553 	 * Finds the field with the given name, and returns the type of the
554 	 * value it contains.  If the field is not found, G_TYPE_INVALID is
555 	 * returned.
556 	 *
557 	 * Params:
558 	 *     fieldname = the name of the field
559 	 *
560 	 * Returns: the #GValue of the field
561 	 */
562 	public GType getFieldType(string fieldname)
563 	{
564 		return gst_structure_get_field_type(gstStructure, Str.toStringz(fieldname));
565 	}
566 
567 	/**
568 	 * Read the GstFlagSet flags and mask out of the structure into the
569 	 * provided pointers.
570 	 *
571 	 * Params:
572 	 *     fieldname = the name of a field
573 	 *     valueFlags = a pointer to a guint for the flags field
574 	 *     valueMask = a pointer to a guint for the mask field
575 	 *
576 	 * Returns: %TRUE if the values could be set correctly. If there was no field
577 	 *     with @fieldname or the existing field did not contain a GstFlagSet, this
578 	 *     function returns %FALSE.
579 	 *
580 	 * Since: 1.6
581 	 */
582 	public bool getFlagset(string fieldname, out uint valueFlags, out uint valueMask)
583 	{
584 		return gst_structure_get_flagset(gstStructure, Str.toStringz(fieldname), &valueFlags, &valueMask) != 0;
585 	}
586 
587 	/**
588 	 * Sets the integers pointed to by @value_numerator and @value_denominator
589 	 * corresponding to the value of the given field.  Caller is responsible
590 	 * for making sure the field exists and has the correct type.
591 	 *
592 	 * Params:
593 	 *     fieldname = the name of a field
594 	 *     valueNumerator = a pointer to an int to set
595 	 *     valueDenominator = a pointer to an int to set
596 	 *
597 	 * Returns: %TRUE if the values could be set correctly. If there was no field
598 	 *     with @fieldname or the existing field did not contain a GstFraction, this
599 	 *     function returns %FALSE.
600 	 */
601 	public bool getFraction(string fieldname, out int valueNumerator, out int valueDenominator)
602 	{
603 		return gst_structure_get_fraction(gstStructure, Str.toStringz(fieldname), &valueNumerator, &valueDenominator) != 0;
604 	}
605 
606 	/**
607 	 * Sets the int pointed to by @value corresponding to the value of the
608 	 * given field.  Caller is responsible for making sure the field exists
609 	 * and has the correct type.
610 	 *
611 	 * Params:
612 	 *     fieldname = the name of a field
613 	 *     value = a pointer to an int to set
614 	 *
615 	 * Returns: %TRUE if the value could be set correctly. If there was no field
616 	 *     with @fieldname or the existing field did not contain an int, this function
617 	 *     returns %FALSE.
618 	 */
619 	public bool getInt(string fieldname, out int value)
620 	{
621 		return gst_structure_get_int(gstStructure, Str.toStringz(fieldname), &value) != 0;
622 	}
623 
624 	/**
625 	 * Sets the #gint64 pointed to by @value corresponding to the value of the
626 	 * given field. Caller is responsible for making sure the field exists
627 	 * and has the correct type.
628 	 *
629 	 * Params:
630 	 *     fieldname = the name of a field
631 	 *     value = a pointer to a #gint64 to set
632 	 *
633 	 * Returns: %TRUE if the value could be set correctly. If there was no field
634 	 *     with @fieldname or the existing field did not contain a #gint64, this function
635 	 *     returns %FALSE.
636 	 *
637 	 * Since: 1.4
638 	 */
639 	public bool getInt64(string fieldname, out long value)
640 	{
641 		return gst_structure_get_int64(gstStructure, Str.toStringz(fieldname), &value) != 0;
642 	}
643 
644 	/**
645 	 * This is useful in language bindings where unknown #GValue types are not
646 	 * supported. This function will convert the %GST_TYPE_LIST into a newly
647 	 * allocated GValueArray and return it through @array. Be aware that this is
648 	 * slower then getting the #GValue directly.
649 	 *
650 	 * Params:
651 	 *     fieldname = the name of a field
652 	 *     array = a pointer to a #GValueArray
653 	 *
654 	 * Returns: %TRUE if the value could be set correctly. If there was no field
655 	 *     with @fieldname or the existing field did not contain a %GST_TYPE_LIST, this
656 	 *     function returns %FALSE.
657 	 *
658 	 *     Since 1.12
659 	 */
660 	public bool getList(string fieldname, out ValueArray array)
661 	{
662 		GValueArray* outarray = null;
663 
664 		auto p = gst_structure_get_list(gstStructure, Str.toStringz(fieldname), &outarray) != 0;
665 
666 		array = ObjectG.getDObject!(ValueArray)(outarray);
667 
668 		return p;
669 	}
670 
671 	/**
672 	 * Get the name of @structure as a string.
673 	 *
674 	 * Returns: the name of the structure.
675 	 */
676 	public string getName()
677 	{
678 		return Str.toString(gst_structure_get_name(gstStructure));
679 	}
680 
681 	/**
682 	 * Get the name of @structure as a GQuark.
683 	 *
684 	 * Returns: the quark representing the name of the structure.
685 	 */
686 	public GQuark getNameId()
687 	{
688 		return gst_structure_get_name_id(gstStructure);
689 	}
690 
691 	/**
692 	 * Finds the field corresponding to @fieldname, and returns the string
693 	 * contained in the field's value.  Caller is responsible for making
694 	 * sure the field exists and has the correct type.
695 	 *
696 	 * The string should not be modified, and remains valid until the next
697 	 * call to a gst_structure_*() function with the given structure.
698 	 *
699 	 * Params:
700 	 *     fieldname = the name of a field
701 	 *
702 	 * Returns: a pointer to the string or %NULL when the
703 	 *     field did not exist or did not contain a string.
704 	 */
705 	public string getString(string fieldname)
706 	{
707 		return Str.toString(gst_structure_get_string(gstStructure, Str.toStringz(fieldname)));
708 	}
709 
710 	/**
711 	 * Sets the uint pointed to by @value corresponding to the value of the
712 	 * given field.  Caller is responsible for making sure the field exists
713 	 * and has the correct type.
714 	 *
715 	 * Params:
716 	 *     fieldname = the name of a field
717 	 *     value = a pointer to a uint to set
718 	 *
719 	 * Returns: %TRUE if the value could be set correctly. If there was no field
720 	 *     with @fieldname or the existing field did not contain a uint, this function
721 	 *     returns %FALSE.
722 	 */
723 	public bool getUint(string fieldname, out uint value)
724 	{
725 		return gst_structure_get_uint(gstStructure, Str.toStringz(fieldname), &value) != 0;
726 	}
727 
728 	/**
729 	 * Sets the #guint64 pointed to by @value corresponding to the value of the
730 	 * given field. Caller is responsible for making sure the field exists
731 	 * and has the correct type.
732 	 *
733 	 * Params:
734 	 *     fieldname = the name of a field
735 	 *     value = a pointer to a #guint64 to set
736 	 *
737 	 * Returns: %TRUE if the value could be set correctly. If there was no field
738 	 *     with @fieldname or the existing field did not contain a #guint64, this function
739 	 *     returns %FALSE.
740 	 *
741 	 * Since: 1.4
742 	 */
743 	public bool getUint64(string fieldname, out ulong value)
744 	{
745 		return gst_structure_get_uint64(gstStructure, Str.toStringz(fieldname), &value) != 0;
746 	}
747 
748 	/**
749 	 * Parses the variable arguments and reads fields from @structure accordingly.
750 	 * valist-variant of gst_structure_get(). Look at the documentation of
751 	 * gst_structure_get() for more details.
752 	 *
753 	 * Params:
754 	 *     firstFieldname = the name of the first field to read
755 	 *     args = variable arguments
756 	 *
757 	 * Returns: %TRUE, or %FALSE if there was a problem reading any of the fields
758 	 */
759 	public bool getValist(string firstFieldname, void* args)
760 	{
761 		return gst_structure_get_valist(gstStructure, Str.toStringz(firstFieldname), args) != 0;
762 	}
763 
764 	/**
765 	 * Get the value of the field with name @fieldname.
766 	 *
767 	 * Params:
768 	 *     fieldname = the name of the field to get
769 	 *
770 	 * Returns: the #GValue corresponding to the field with the given
771 	 *     name.
772 	 */
773 	public Value getValue(string fieldname)
774 	{
775 		auto p = gst_structure_get_value(gstStructure, Str.toStringz(fieldname));
776 
777 		if(p is null)
778 		{
779 			return null;
780 		}
781 
782 		return ObjectG.getDObject!(Value)(cast(GValue*) p);
783 	}
784 
785 	/**
786 	 * Check if @structure contains a field named @fieldname.
787 	 *
788 	 * Params:
789 	 *     fieldname = the name of a field
790 	 *
791 	 * Returns: %TRUE if the structure contains a field with the given name
792 	 */
793 	public bool hasField(string fieldname)
794 	{
795 		return gst_structure_has_field(gstStructure, Str.toStringz(fieldname)) != 0;
796 	}
797 
798 	/**
799 	 * Check if @structure contains a field named @fieldname and with GType @type.
800 	 *
801 	 * Params:
802 	 *     fieldname = the name of a field
803 	 *     type = the type of a value
804 	 *
805 	 * Returns: %TRUE if the structure contains a field with the given name and type
806 	 */
807 	public bool hasFieldTyped(string fieldname, GType type)
808 	{
809 		return gst_structure_has_field_typed(gstStructure, Str.toStringz(fieldname), type) != 0;
810 	}
811 
812 	/**
813 	 * Checks if the structure has the given name
814 	 *
815 	 * Params:
816 	 *     name = structure name to check for
817 	 *
818 	 * Returns: %TRUE if @name matches the name of the structure.
819 	 */
820 	public bool hasName(string name)
821 	{
822 		return gst_structure_has_name(gstStructure, Str.toStringz(name)) != 0;
823 	}
824 
825 	/**
826 	 * Parses the variable arguments and reads fields from @structure accordingly.
827 	 * valist-variant of gst_structure_id_get(). Look at the documentation of
828 	 * gst_structure_id_get() for more details.
829 	 *
830 	 * Params:
831 	 *     firstFieldId = the quark of the first field to read
832 	 *     args = variable arguments
833 	 *
834 	 * Returns: %TRUE, or %FALSE if there was a problem reading any of the fields
835 	 */
836 	public bool idGetValist(GQuark firstFieldId, void* args)
837 	{
838 		return gst_structure_id_get_valist(gstStructure, firstFieldId, args) != 0;
839 	}
840 
841 	/**
842 	 * Get the value of the field with GQuark @field.
843 	 *
844 	 * Params:
845 	 *     field = the #GQuark of the field to get
846 	 *
847 	 * Returns: the #GValue corresponding to the field with the given
848 	 *     name identifier.
849 	 */
850 	public Value idGetValue(GQuark field)
851 	{
852 		auto p = gst_structure_id_get_value(gstStructure, field);
853 
854 		if(p is null)
855 		{
856 			return null;
857 		}
858 
859 		return ObjectG.getDObject!(Value)(cast(GValue*) p);
860 	}
861 
862 	/**
863 	 * Check if @structure contains a field named @field.
864 	 *
865 	 * Params:
866 	 *     field = #GQuark of the field name
867 	 *
868 	 * Returns: %TRUE if the structure contains a field with the given name
869 	 */
870 	public bool idHasField(GQuark field)
871 	{
872 		return gst_structure_id_has_field(gstStructure, field) != 0;
873 	}
874 
875 	/**
876 	 * Check if @structure contains a field named @field and with GType @type.
877 	 *
878 	 * Params:
879 	 *     field = #GQuark of the field name
880 	 *     type = the type of a value
881 	 *
882 	 * Returns: %TRUE if the structure contains a field with the given name and type
883 	 */
884 	public bool idHasFieldTyped(GQuark field, GType type)
885 	{
886 		return gst_structure_id_has_field_typed(gstStructure, field, type) != 0;
887 	}
888 
889 	/**
890 	 * va_list form of gst_structure_id_set().
891 	 *
892 	 * Params:
893 	 *     fieldname = the name of the field to set
894 	 *     varargs = variable arguments
895 	 */
896 	public void idSetValist(GQuark fieldname, void* varargs)
897 	{
898 		gst_structure_id_set_valist(gstStructure, fieldname, varargs);
899 	}
900 
901 	/**
902 	 * Sets the field with the given GQuark @field to @value.  If the field
903 	 * does not exist, it is created.  If the field exists, the previous
904 	 * value is replaced and freed.
905 	 *
906 	 * Params:
907 	 *     field = a #GQuark representing a field
908 	 *     value = the new value of the field
909 	 */
910 	public void idSetValue(GQuark field, Value value)
911 	{
912 		gst_structure_id_set_value(gstStructure, field, (value is null) ? null : value.getValueStruct());
913 	}
914 
915 	/**
916 	 * Sets the field with the given GQuark @field to @value.  If the field
917 	 * does not exist, it is created.  If the field exists, the previous
918 	 * value is replaced and freed.
919 	 *
920 	 * Params:
921 	 *     field = a #GQuark representing a field
922 	 *     value = the new value of the field
923 	 */
924 	public void idTakeValue(GQuark field, Value value)
925 	{
926 		gst_structure_id_take_value(gstStructure, field, (value is null) ? null : value.getValueStruct());
927 	}
928 
929 	/**
930 	 * Intersects @struct1 and @struct2 and returns the intersection.
931 	 *
932 	 * Params:
933 	 *     struct2 = a #GstStructure
934 	 *
935 	 * Returns: Intersection of @struct1 and @struct2
936 	 */
937 	public Structure intersect(Structure struct2)
938 	{
939 		auto p = gst_structure_intersect(gstStructure, (struct2 is null) ? null : struct2.getStructureStruct());
940 
941 		if(p is null)
942 		{
943 			return null;
944 		}
945 
946 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p, true);
947 	}
948 
949 	/**
950 	 * Tests if the two #GstStructure are equal.
951 	 *
952 	 * Params:
953 	 *     structure2 = a #GstStructure.
954 	 *
955 	 * Returns: %TRUE if the two structures have the same name and field.
956 	 */
957 	public bool isEqual(Structure structure2)
958 	{
959 		return gst_structure_is_equal(gstStructure, (structure2 is null) ? null : structure2.getStructureStruct()) != 0;
960 	}
961 
962 	/**
963 	 * Checks if @subset is a subset of @superset, i.e. has the same
964 	 * structure name and for all fields that are existing in @superset,
965 	 * @subset has a value that is a subset of the value in @superset.
966 	 *
967 	 * Params:
968 	 *     superset = a potentially greater #GstStructure
969 	 *
970 	 * Returns: %TRUE if @subset is a subset of @superset
971 	 */
972 	public bool isSubset(Structure superset)
973 	{
974 		return gst_structure_is_subset(gstStructure, (superset is null) ? null : superset.getStructureStruct()) != 0;
975 	}
976 
977 	/**
978 	 * Calls the provided function once for each field in the #GstStructure. In
979 	 * contrast to gst_structure_foreach(), the function may modify but not delete the
980 	 * fields. The structure must be mutable.
981 	 *
982 	 * Params:
983 	 *     func = a function to call for each field
984 	 *     userData = private data
985 	 *
986 	 * Returns: %TRUE if the supplied function returns %TRUE For each of the fields,
987 	 *     %FALSE otherwise.
988 	 */
989 	public bool mapInPlace(GstStructureMapFunc func, void* userData)
990 	{
991 		return gst_structure_map_in_place(gstStructure, func, userData) != 0;
992 	}
993 
994 	/**
995 	 * Get the number of fields in the structure.
996 	 *
997 	 * Returns: the number of fields in the structure
998 	 */
999 	public int nFields()
1000 	{
1001 		return gst_structure_n_fields(gstStructure);
1002 	}
1003 
1004 	/**
1005 	 * Get the name of the given field number, counting from 0 onwards.
1006 	 *
1007 	 * Params:
1008 	 *     index = the index to get the name of
1009 	 *
1010 	 * Returns: the name of the given field number
1011 	 */
1012 	public string nthFieldName(uint index)
1013 	{
1014 		return Str.toString(gst_structure_nth_field_name(gstStructure, index));
1015 	}
1016 
1017 	/**
1018 	 * Removes all fields in a GstStructure.
1019 	 */
1020 	public void removeAllFields()
1021 	{
1022 		gst_structure_remove_all_fields(gstStructure);
1023 	}
1024 
1025 	/**
1026 	 * Removes the field with the given name.  If the field with the given
1027 	 * name does not exist, the structure is unchanged.
1028 	 *
1029 	 * Params:
1030 	 *     fieldname = the name of the field to remove
1031 	 */
1032 	public void removeField(string fieldname)
1033 	{
1034 		gst_structure_remove_field(gstStructure, Str.toStringz(fieldname));
1035 	}
1036 
1037 	/**
1038 	 * va_list form of gst_structure_remove_fields().
1039 	 *
1040 	 * Params:
1041 	 *     fieldname = the name of the field to remove
1042 	 *     varargs = %NULL-terminated list of more fieldnames to remove
1043 	 */
1044 	public void removeFieldsValist(string fieldname, void* varargs)
1045 	{
1046 		gst_structure_remove_fields_valist(gstStructure, Str.toStringz(fieldname), varargs);
1047 	}
1048 
1049 	/**
1050 	 * This is useful in language bindings where unknown GValue types are not
1051 	 * supported. This function will convert a @array to %GST_TYPE_ARRAY and set
1052 	 * the field specified by @fieldname.  Be aware that this is slower then using
1053 	 * %GST_TYPE_ARRAY in a #GValue directly.
1054 	 *
1055 	 * Since 1.12
1056 	 *
1057 	 * Params:
1058 	 *     fieldname = the name of a field
1059 	 *     array = a pointer to a #GValueArray
1060 	 */
1061 	public void setArray(string fieldname, ValueArray array)
1062 	{
1063 		gst_structure_set_array(gstStructure, Str.toStringz(fieldname), (array is null) ? null : array.getValueArrayStruct());
1064 	}
1065 
1066 	/**
1067 	 * This is useful in language bindings where unknown GValue types are not
1068 	 * supported. This function will convert a @array to %GST_TYPE_LIST and set
1069 	 * the field specified by @fieldname. Be aware that this is slower then using
1070 	 * %GST_TYPE_LIST in a #GValue directly.
1071 	 *
1072 	 * Since 1.12
1073 	 *
1074 	 * Params:
1075 	 *     fieldname = the name of a field
1076 	 *     array = a pointer to a #GValueArray
1077 	 */
1078 	public void setList(string fieldname, ValueArray array)
1079 	{
1080 		gst_structure_set_list(gstStructure, Str.toStringz(fieldname), (array is null) ? null : array.getValueArrayStruct());
1081 	}
1082 
1083 	/**
1084 	 * Sets the name of the structure to the given @name.  The string
1085 	 * provided is copied before being used. It must not be empty, start with a
1086 	 * letter and can be followed by letters, numbers and any of "/-_.:".
1087 	 *
1088 	 * Params:
1089 	 *     name = the new name of the structure
1090 	 */
1091 	public void setName(string name)
1092 	{
1093 		gst_structure_set_name(gstStructure, Str.toStringz(name));
1094 	}
1095 
1096 	/**
1097 	 * Sets the parent_refcount field of #GstStructure. This field is used to
1098 	 * determine whether a structure is mutable or not. This function should only be
1099 	 * called by code implementing parent objects of #GstStructure, as described in
1100 	 * the MT Refcounting section of the design documents.
1101 	 *
1102 	 * Params:
1103 	 *     refcount = a pointer to the parent's refcount
1104 	 *
1105 	 * Returns: %TRUE if the parent refcount could be set.
1106 	 */
1107 	public bool setParentRefcount(int* refcount)
1108 	{
1109 		return gst_structure_set_parent_refcount(gstStructure, refcount) != 0;
1110 	}
1111 
1112 	/**
1113 	 * va_list form of gst_structure_set().
1114 	 *
1115 	 * Params:
1116 	 *     fieldname = the name of the field to set
1117 	 *     varargs = variable arguments
1118 	 */
1119 	public void setValist(string fieldname, void* varargs)
1120 	{
1121 		gst_structure_set_valist(gstStructure, Str.toStringz(fieldname), varargs);
1122 	}
1123 
1124 	/**
1125 	 * Sets the field with the given name @field to @value.  If the field
1126 	 * does not exist, it is created.  If the field exists, the previous
1127 	 * value is replaced and freed.
1128 	 *
1129 	 * Params:
1130 	 *     fieldname = the name of the field to set
1131 	 *     value = the new value of the field
1132 	 */
1133 	public void setValue(string fieldname, Value value)
1134 	{
1135 		gst_structure_set_value(gstStructure, Str.toStringz(fieldname), (value is null) ? null : value.getValueStruct());
1136 	}
1137 
1138 	/**
1139 	 * Sets the field with the given name @field to @value.  If the field
1140 	 * does not exist, it is created.  If the field exists, the previous
1141 	 * value is replaced and freed. The function will take ownership of @value.
1142 	 *
1143 	 * Params:
1144 	 *     fieldname = the name of the field to set
1145 	 *     value = the new value of the field
1146 	 */
1147 	public void takeValue(string fieldname, Value value)
1148 	{
1149 		gst_structure_take_value(gstStructure, Str.toStringz(fieldname), (value is null) ? null : value.getValueStruct());
1150 	}
1151 
1152 	/**
1153 	 * Converts @structure to a human-readable string representation.
1154 	 *
1155 	 * For debugging purposes its easier to do something like this:
1156 	 * |[<!-- language="C" -->
1157 	 * GST_LOG ("structure is %" GST_PTR_FORMAT, structure);
1158 	 * ]|
1159 	 * This prints the structure in human readable form.
1160 	 *
1161 	 * The current implementation of serialization will lead to unexpected results
1162 	 * when there are nested #GstCaps / #GstStructure deeper than one level.
1163 	 *
1164 	 * Free-function: g_free
1165 	 *
1166 	 * Returns: a pointer to string allocated by g_malloc().
1167 	 *     g_free() after usage.
1168 	 */
1169 	public override string toString()
1170 	{
1171 		auto retStr = gst_structure_to_string(gstStructure);
1172 
1173 		scope(exit) Str.freeString(retStr);
1174 		return Str.toString(retStr);
1175 	}
1176 
1177 	/**
1178 	 * Creates a #GstStructure from a string representation.
1179 	 * If end is not %NULL, a pointer to the place inside the given string
1180 	 * where parsing ended will be returned.
1181 	 *
1182 	 * Free-function: gst_structure_free
1183 	 *
1184 	 * Params:
1185 	 *     string_ = a string representation of a #GstStructure.
1186 	 *     end = pointer to store the end of the string in.
1187 	 *
1188 	 * Returns: a new #GstStructure or %NULL
1189 	 *     when the string could not be parsed. Free with
1190 	 *     gst_structure_free() after use.
1191 	 */
1192 	public static Structure fromString(string string_, out string end)
1193 	{
1194 		char* outend = null;
1195 
1196 		auto p = gst_structure_from_string(Str.toStringz(string_), &outend);
1197 
1198 		end = Str.toString(outend);
1199 
1200 		if(p is null)
1201 		{
1202 			return null;
1203 		}
1204 
1205 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p, true);
1206 	}
1207 }