/* GStreamer

 * Copyright (C) 2003 David A. Schleef <ds@schleef.org>

 *

 * gststructure.c: lists of { GQuark, GValue } tuples

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Library General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Library General Public License for more details.

 *

 * You should have received a copy of the GNU Library General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

/**

 * SECTION:gststructure

 * @short_description: Generic structure containing fields of names and values

 * @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery

 *

 * A #GstStructure is a collection of key/value pairs. The keys are expressed

 * as GQuarks and the values can be of any GType.

 *

 * In addition to the key/value pairs, a #GstStructure also has a name. The name

 * starts with a letter and can be folled by letters, numbers and any of "/-_.:".

 * 

 * #GstStructure is used by various GStreamer subsystems to store information

 * in a flexible and extensible way. A #GstStructure does not have a refcount

 * because it usually is part of a higher level object such as #GstCaps. It

 * provides a means to enforce mutability using the refcount of the parent

 * with the gst_structure_set_parent_refcount() method.

 *

 * A #GstStructure can be created with gst_structure_empty_new() or

 * gst_structure_new(), which both take a name and an optional set of

 * key/value pairs along with the types of the values.

 * 

 * Field values can be changed with gst_structure_set_value() or

 * gst_structure_set().

 *

 * Field values can be retrieved with gst_structure_get_value() or the more

 * convenient gst_structure_get_*() functions.

 *

 * Fields can be removed with gst_structure_remove_field() or

 * gst_structure_remove_fields().

 *

 */

#ifdef HAVE_CONFIG_H

#include "config.h"

#endif

#include <string.h>

#include "gst_private.h"

#include <gst/gst.h>

#include <gobject/gvaluecollector.h>

#ifdef __SYMBIAN32__

#include <glib_global.h>

#endif

typedef struct _GstStructureField GstStructureField;

struct _GstStructureField

{

  GQuark name;

  GValue value;

};

#define GST_STRUCTURE_FIELD(structure, index) \

    &g_array_index((structure)->fields, GstStructureField, (index))

#define IS_MUTABLE(structure) \

    (!(structure)->parent_refcount || \

     g_atomic_int_get ((structure)->parent_refcount) == 1)

static void gst_structure_set_field (GstStructure * structure,

    GstStructureField * field);

static GstStructureField *gst_structure_get_field (const GstStructure *

    structure, const gchar * fieldname);

static GstStructureField *gst_structure_id_get_field (const GstStructure *

    structure, GQuark field);

static void gst_structure_transform_to_string (const GValue * src_value,

    GValue * dest_value);

static GstStructure *gst_structure_copy_conditional (const GstStructure *

    structure);

static gboolean gst_structure_parse_value (gchar * str, gchar ** after,

    GValue * value, GType default_type);

static gboolean gst_structure_parse_simple_string (gchar * s, gchar ** end);

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GType

gst_structure_get_type (void)

{

  static GType gst_structure_type = 0;

  if (G_UNLIKELY (gst_structure_type == 0)) {

    gst_structure_type = g_boxed_type_register_static ("GstStructure",

        (GBoxedCopyFunc) gst_structure_copy_conditional,

        (GBoxedFreeFunc) gst_structure_free);

    g_value_register_transform_func (gst_structure_type, G_TYPE_STRING,

        gst_structure_transform_to_string);

  }

  return gst_structure_type;

}

static GstStructure *

gst_structure_id_empty_new_with_size (GQuark quark, guint prealloc)

{

  GstStructure *structure;

  structure->type = gst_structure_get_type ();

  structure->name = quark;

  structure->fields =

  return structure;

}

/**

 * gst_structure_id_empty_new:

 * @quark: name of new structure

 *

 * Creates a new, empty #GstStructure with the given name as a GQuark.

 *

 * Returns: a new, empty #GstStructure

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstStructure *

gst_structure_id_empty_new (GQuark quark)

{

  g_return_val_if_fail (quark != 0, NULL);

  return gst_structure_id_empty_new_with_size (quark, 0);

}

static gboolean

gst_structure_validate_name (const gchar * name)

{

  const gchar *s;

  g_return_val_if_fail (name != NULL, FALSE);

  /* FIXME 0.11: use g_ascii_isalpha() */

    GST_WARNING ("Invalid character '%c' at offset 0 in structure name: %s",

        *name, name);

    return FALSE;

  }

  /* FIXME 0.11: don't allow spaces */

  /* FIXME: test name string more */

  s = &name[1];

  while (*s && (g_ascii_isalnum (*s) || strchr ("/-_.:+ ", *s) != NULL))

    s++;

    GST_WARNING ("Invalid character '%c' at offset %lu in structure name: %s",

        *s, ((gulong) s - (gulong) name), name);

    return FALSE;

  }

  return TRUE;

}

/**

 * gst_structure_empty_new:

 * @name: name of new structure

 *

 * Creates a new, empty #GstStructure with the given @name.

 *

 * See gst_structure_set_name() for constraints on the @name parameter.

 *

 * Returns: a new, empty #GstStructure

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstStructure *

gst_structure_empty_new (const gchar * name)

{

  g_return_val_if_fail (gst_structure_validate_name (name), NULL);

  return gst_structure_id_empty_new_with_size (g_quark_from_string (name), 0);

}

/**

 * gst_structure_new:

 * @name: name of new structure

 * @firstfield: name of first field to set

 * @...: additional arguments

 *

 * Creates a new #GstStructure with the given name.  Parses the

 * list of variable arguments and sets fields to the values listed.

 * Variable arguments should be passed as field name, field type,

 * and value.  Last variable argument should be NULL.

 *

 * Returns: a new #GstStructure

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstStructure *

gst_structure_new (const gchar * name, const gchar * firstfield, ...)

{

  GstStructure *structure;

  va_list varargs;

  g_return_val_if_fail (name != NULL, NULL);

  va_start (varargs, firstfield);

  structure = gst_structure_new_valist (name, firstfield, varargs);

  va_end (varargs);

  return structure;

}

/**

 * gst_structure_new_valist:

 * @name: name of new structure

 * @firstfield: name of first field to set

 * @varargs: variable argument list

 *

 * Creates a new #GstStructure with the given @name.  Structure fields

 * are set according to the varargs in a manner similar to

 * gst_structure_new().

 *

 * See gst_structure_set_name() for constraints on the @name parameter.

 *

 * Returns: a new #GstStructure

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstStructure *

gst_structure_new_valist (const gchar * name,

    const gchar * firstfield, va_list varargs)

{

  GstStructure *structure;

  g_return_val_if_fail (name != NULL, NULL);

  structure = gst_structure_empty_new (name);

  if (structure)

    gst_structure_set_valist (structure, firstfield, varargs);

  return structure;

}

/**

 * gst_structure_set_parent_refcount:

 * @structure: a #GstStructure

 * @refcount: a pointer to the parent's refcount

 *

 * Sets the parent_refcount field of #GstStructure. This field is used to

 * determine whether a structure is mutable or not. This function should only be

 * called by code implementing parent objects of #GstStructure, as described in

 * the MT Refcounting section of the design documents.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

{

  g_return_if_fail (structure != NULL);

  /* if we have a parent_refcount already, we can only clear

   * if with a NULL refcount */

  if (structure->parent_refcount)

    g_return_if_fail (refcount == NULL);

  else

    g_return_if_fail (refcount != NULL);

  structure->parent_refcount = refcount;

}

/**

 * gst_structure_copy:

 * @structure: a #GstStructure to duplicate

 *

 * Duplicates a #GstStructure and all its fields and values.

 *

 * Returns: a new #GstStructure.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstStructure *

gst_structure_copy (const GstStructure * structure)

{

  GstStructure *new_structure;

  GstStructureField *field;

  g_return_val_if_fail (structure != NULL, NULL);

  new_structure =

      gst_structure_id_empty_new_with_size (structure->name,

      structure->fields->len);

    GstStructureField new_field = { 0 };

    field = GST_STRUCTURE_FIELD (structure, i);

    new_field.name = field->name;

    gst_value_init_and_copy (&new_field.value, &field->value);

    g_array_append_val (new_structure->fields, new_field);

  }

  return new_structure;

}

/**

 * gst_structure_free:

 * @structure: the #GstStructure to free

 *

 * Frees a #GstStructure and all its fields and values. The structure must not

 * have a parent when this function is called.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_structure_free (GstStructure * structure)

{

  GstStructureField *field;

  g_return_if_fail (structure != NULL);

  g_return_if_fail (structure->parent_refcount == NULL);

    field = GST_STRUCTURE_FIELD (structure, i);

    if (G_IS_VALUE (&field->value)) {

      g_value_unset (&field->value);

    }

  }

  g_array_free (structure->fields, TRUE);

#ifdef USE_POISONING

  memset (structure, 0xff, sizeof (GstStructure));

#endif

}

/**

 * gst_structure_get_name:

 * @structure: a #GstStructure

 *

 * Get the name of @structure as a string.

 *

 * Returns: the name of the structure.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

const gchar *

gst_structure_get_name (const GstStructure * structure)

{

  g_return_val_if_fail (structure != NULL, NULL);

  return g_quark_to_string (structure->name);

}

/**

 * gst_structure_has_name:

 * @structure: a #GstStructure

 * @name: structure name to check for

 *

 * Checks if the structure has the given name

 *

 * Returns: TRUE if @name matches the name of the structure.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gboolean

gst_structure_has_name (const GstStructure * structure, const gchar * name)

{

  const gchar *structure_name;

  g_return_val_if_fail (structure != NULL, FALSE);

  g_return_val_if_fail (name != NULL, FALSE);

  /* getting the string is cheap and comparing short strings is too

   * should be faster than getting the quark for name and comparing the quarks

   */

  structure_name = g_quark_to_string (structure->name);

  return (structure_name && strcmp (structure_name, name) == 0);

}

/**

 * gst_structure_get_name_id:

 * @structure: a #GstStructure

 *

 * Get the name of @structure as a GQuark.

 *

 * Returns: the quark representing the name of the structure.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GQuark

gst_structure_get_name_id (const GstStructure * structure)

{

  g_return_val_if_fail (structure != NULL, 0);

  return structure->name;

}

/**

 * gst_structure_set_name:

 * @structure: a #GstStructure

 * @name: the new name of the structure

 *

 * Sets the name of the structure to the given @name.  The string

 * provided is copied before being used. It must not be empty, start with a

 * letter and can be followed by letters, numbers and any of "/-_.:".

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_structure_set_name (GstStructure * structure, const gchar * name)

{

  g_return_if_fail (structure != NULL);

  g_return_if_fail (IS_MUTABLE (structure));

  g_return_if_fail (gst_structure_validate_name (name));

  structure->name = g_quark_from_string (name);

}

/**

 * gst_structure_id_set_value:

 * @structure: a #GstStructure

 * @field: a #GQuark representing a field

 * @value: the new value of the field

 *

 * Sets the field with the given GQuark @field to @value.  If the field

 * does not exist, it is created.  If the field exists, the previous

 * value is replaced and freed.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_structure_id_set_value (GstStructure * structure,

    GQuark field, const GValue * value)

{

  GstStructureField gsfield = { 0, {0,} };

  g_return_if_fail (structure != NULL);

  g_return_if_fail (G_IS_VALUE (value));

  g_return_if_fail (IS_MUTABLE (structure));

  gsfield.name = field;

  gst_value_init_and_copy (&gsfield.value, value);

  gst_structure_set_field (structure, &gsfield);

}

/**

 * gst_structure_set_value:

 * @structure: a #GstStructure

 * @fieldname: the name of the field to set

 * @value: the new value of the field

 *

 * Sets the field with the given name @field to @value.  If the field

 * does not exist, it is created.  If the field exists, the previous

 * value is replaced and freed.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_structure_set_value (GstStructure * structure,

    const gchar * fieldname, const GValue * value)

{

  g_return_if_fail (structure != NULL);

  g_return_if_fail (fieldname != NULL);

  g_return_if_fail (G_IS_VALUE (value));

  g_return_if_fail (IS_MUTABLE (structure));