## GstProps

GstProps — Properties

## Synopsis

    #include <gst/gst.h>

    struct      GstProps;
    enum        GstPropsType;
    #define     GST_TYPE_PROPS
    #define     GST_MAKE_FOURCC                 (a,b,c,d)
    #define     GST_STR_FOURCC                  (f)
    #define     GST_PROPS_LIST                  (...)
    #define     GST_PROPS_GLIST                 (a)
    #define     GST_PROPS_INT                   (a)
    #define     GST_PROPS_INT_ANY
    #define     GST_PROPS_INT_RANGE             (a,b)
    #define     GST_PROPS_INT_NEGATIVE
    #define     GST_PROPS_FOURCC                (a)
    #define     GST_PROPS_BOOLEAN               (a)
    #define     GST_PROPS_STRING                (a)
    #define     GST_PROPS_FLOAT                 (a)
    #define     GST_PROPS_FLOAT_RANGE           (a,b)
    #define     GST_PROPS_INT_POSITIVE
    struct      GstPropsEntry;
    GstProps*   gst_props_new                   (const gchar *firstname,
                                                 ...);
    GstProps*   gst_props_newv                  (const gchar *firstname,
                                                 va_list var_args);
    GstProps*   gst_props_empty_new             (void);
    GstProps*   gst_props_merge                 (GstProps *props,
                                                 GstProps *tomerge);
    GstProps*   gst_props_copy                  (GstProps *props);
    GstProps*   gst_props_copy_on_write         (GstProps *props);
    void        gst_props_destroy               (GstProps *props);
    GstProps*   gst_props_ref                   (GstProps *props);
    GstProps*   gst_props_unref                 (GstProps *props);
    gboolean    gst_props_check_compatibility   (GstProps *fromprops,
                                                 GstProps *toprops);
    gboolean    gst_props_has_property          (GstProps *props,
                                                 const gchar *name);
    GList*      gst_props_normalize             (GstProps *props);
    GstProps*   gst_props_set                   (GstProps *props,
                                                 const gchar *name,
                                                 ...);
    gboolean    gst_props_get                   (GstProps *props,
                                                 gchar *first_name,
                                                 ...);
    gboolean    gst_props_get_safe              (GstProps *props,
                                                 gchar *first_name,
                                                 ...);
    gboolean    gst_props_has_fixed_property    (GstProps *props,
                                                 const gchar *name);
    gboolean    gst_props_has_property_typed    (GstProps *props,
                                                 const gchar *name,
                                                 GstPropsType type);
    GstProps*   gst_props_intersect             (GstProps *props1,
                                                 GstProps *props2);
    void        gst_props_debug                 (GstProps *props);
    xmlNodePtr  gst_props_save_thyself          (GstProps *props,
                                                 xmlNodePtr parent);
    GstProps*   gst_props_load_thyself          (xmlNodePtr parent);
    const GstPropsEntry* gst_props_get_entry    (GstProps *props,
                                                 const gchar *name);
    void        gst_props_add_entry             (GstProps *props,
                                                 GstPropsEntry *entry);
    GstPropsEntry* gst_props_entry_new          (const gchar *name,
                                                 ...);
    gboolean    gst_props_entry_get             (const GstPropsEntry *entry,
                                                 ...);
    GstPropsType gst_props_entry_get_type       (const GstPropsEntry *entry);
    gboolean    gst_props_entry_get_boolean     (const GstPropsEntry *entry,
                                                 gboolean *val);
    gboolean    gst_props_entry_get_float       (const GstPropsEntry *entry,
                                                 gfloat *val);
    gboolean    gst_props_entry_get_float_range (const GstPropsEntry *entry,
                                                 gfloat *min,
                                                 gfloat *max);
    gboolean    gst_props_entry_get_fourcc_int  (const GstPropsEntry *entry,
                                                 guint32 *val);
    gboolean    gst_props_entry_get_int         (const GstPropsEntry *entry,
                                                 gint *val);
    gboolean    gst_props_entry_get_int_range   (const GstPropsEntry *entry,
                                                 gint *min,
                                                 gint *max);
    gboolean    gst_props_entry_get_list        (const GstPropsEntry *entry,
                                                 const GList **val);
    const gchar* gst_props_entry_get_name       (const GstPropsEntry *entry);
    gboolean    gst_props_entry_get_string      (const GstPropsEntry *entry,
                                                 const gchar **val);
    GstPropsType gst_props_entry_get_type       (const GstPropsEntry *entry);
    gboolean    gst_props_entry_is_fixed        (const GstPropsEntry *entry);

## Description

GstProps is used to attach certain properties to a pad. Properties are usually used in conjunction with GstCaps.

## Details

### struct GstProps

    struct GstProps {

      gint   refcount;
      gint   flags;

      GList *properties;            /* real property entries for this property */
    };

The props structure

gint `refcount` | a refcount for this struct
gint `flags` |
GList *`properties` | the properties

### enum GstPropsType

    typedef enum {
       GST_PROPS_END_TYPE = 0,

       GST_PROPS_INVALID_TYPE,

       GST_PROPS_INT_TYPE,
       GST_PROPS_FLOAT_TYPE,
       GST_PROPS_FOURCC_TYPE,
       GST_PROPS_BOOLEAN_TYPE,
       GST_PROPS_STRING_TYPE,

       GST_PROPS_VAR_TYPE,   /* after this marker start the variable properties */

       GST_PROPS_LIST_TYPE,
       GST_PROPS_GLIST_TYPE,
       GST_PROPS_FLOAT_RANGE_TYPE,
       GST_PROPS_INT_RANGE_TYPE,

       GST_PROPS_LAST_TYPE = GST_PROPS_END_TYPE + 16
    } GstPropsType;

The property type

### GST_TYPE_PROPS

    #define GST_TYPE_PROPS	(_gst_props_type)

The GType of the props boxed type, for use in GValues.

### GST_MAKE_FOURCC()

    #define GST_MAKE_FOURCC(a,b,c,d) 	(guint32)((a)|(b)<<8|(c)<<16|(d)<<24)

Create a FOURCC value that can easily be used to construct a fourcc property.

      ...
      "format", GST_PROPS_FOURCC (GST_MAKE_FOURCC ('Y','U','Y','2')),
      ...

`a` : | first fourcc byte
`b` : | second fourcc byte
`c` : | third fourcc byte
`d` : | fourth fourcc byte

### GST_STR_FOURCC()

    #define GST_STR_FOURCC(f)		(guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))

Create a FOURCC value from a string. example:

      ...
      "format", GST_PROPS_FOURCC (GST_STR_FOURCC ("YUY2")),
      ...

`f` : | the string describing the fourcc value.

### GST_PROPS_LIST()

    #define     GST_PROPS_LIST(...)

Create a list of properties.

`...` : | the list of GstProps

### GST_PROPS_GLIST()

    #define GST_PROPS_GLIST(a) 		GST_PROPS_GLIST_TYPE,(a)

Create a list from a GList of GstPropsEntry.

`a` : | A GList of props entries

### GST_PROPS_INT()

    #define GST_PROPS_INT(a) 		GST_PROPS_INT_TYPE,(a)

Create an integer property.

`a` : | the integer property

### GST_PROPS_INT_ANY

    #define GST_PROPS_INT_ANY		GST_PROPS_INT_RANGE(G_MININT,G_MAXINT)

Create an integer property that can hold any int.

### GST_PROPS_INT_RANGE()

    #define GST_PROPS_INT_RANGE(a,b) 	GST_PROPS_INT_RANGE_TYPE,(a),(b)

Create an integer range property.

`a` : | the min value for the range
`b` : | the max value for the range

### GST_PROPS_INT_NEGATIVE

    #define GST_PROPS_INT_NEGATIVE		GST_PROPS_INT_RANGE(G_MININT,0)

Create an integer property that can hold negative ints.

### GST_PROPS_FOURCC()

    #define GST_PROPS_FOURCC(a) 		GST_PROPS_FOURCC_TYPE,(a)

Construct a fourcc property out of four bytes.

`a` : | a fourcc value usualy created with GST_FOURCC_MAKE()

### GST_PROPS_BOOLEAN()

    #define GST_PROPS_BOOLEAN(a) 		GST_PROPS_BOOLEAN_TYPE,(a)

Create a boolean property.

`a` : | the boolean property

### GST_PROPS_STRING()

    #define GST_PROPS_STRING(a) 		GST_PROPS_STRING_TYPE,(a)

Create a string value.

`a` : | the string value.

### GST_PROPS_FLOAT()

    #define GST_PROPS_FLOAT(a) 		GST_PROPS_FLOAT_TYPE,((float)(a))

Create a floating point value.

`a` : | the float value

### GST_PROPS_FLOAT_RANGE()

    #define GST_PROPS_FLOAT_RANGE(a,b) 	GST_PROPS_FLOAT_RANGE_TYPE,((float)(a)),((float)(b))

Create a float range value.

`a` : | lower float bounds
`b` : | upper float bounds

### GST_PROPS_INT_POSITIVE

    #define GST_PROPS_INT_POSITIVE		GST_PROPS_INT_RANGE(0,G_MAXINT)

Create an integer property that can hold positive ints.

### struct GstPropsEntry

    struct GstPropsEntry;

An entry hols one key/value pair.

### gst_props_new ()

    GstProps*   gst_props_new                   (const gchar *firstname,
                                                 ...);

Create a new property from the given key/value pairs

`firstname` : | the first property name
`...` : | the property values
Returns : | the new property

### gst_props_newv ()

    GstProps*   gst_props_newv                  (const gchar *firstname,
                                                 va_list var_args);

Create a new property from the list of entries.

`firstname` : | the first property name
`var_args` : | the property values
Returns : | the new property created from the list of entries

### gst_props_empty_new ()

    GstProps*   gst_props_empty_new             (void);

Create a new empty property.

Returns : | the new property

### gst_props_merge ()

    GstProps*   gst_props_merge                 (GstProps *props,
                                                 GstProps *tomerge);

Merge the properties of tomerge into props.

`props` : | the property to merge into
`tomerge` : | the property to merge
Returns : | the new merged property

### gst_props_copy ()

    GstProps*   gst_props_copy                  (GstProps *props);

Copy the property structure.

`props` : | the props to copy
Returns : | the new property that is a copy of the original one.

### gst_props_copy_on_write ()

    GstProps*   gst_props_copy_on_write         (GstProps *props);

Copy the property structure if the refcount is >1.

`props` : | the props to copy on write
Returns : | A new props that can be safely written to.

### gst_props_destroy ()

    void        gst_props_destroy               (GstProps *props);

Destroy the property, freeing all the memory that was allocated.

`props` : | the props to destroy

### gst_props_ref ()

    GstProps*   gst_props_ref                   (GstProps *props);

Increase the refcount of the property structure.

`props` : | the props to ref
Returns : | handle to refed props.

### gst_props_unref ()

    GstProps*   gst_props_unref                 (GstProps *props);

Decrease the refcount of the property structure, destroying the property if the refcount is 0.

`props` : | the props to unref
Returns : | handle to unrefed props or NULL when it was destroyed.

### gst_props_check_compatibility ()

    gboolean    gst_props_check_compatibility   (GstProps *fromprops,
                                                 GstProps *toprops);

Checks whether two capabilities are compatible.

`fromprops` : | a property
`toprops` : | a property
Returns : | TRUE if compatible, FALSE otherwise

### gst_props_has_property ()

    gboolean    gst_props_has_property          (GstProps *props,
                                                 const gchar *name);

Checks if a given props has a property with the given name.

`props` : | the props to check
`name` : | the name of the key to find
Returns : | TRUE if the property was found, FALSE otherwise.

### gst_props_normalize ()

    GList*      gst_props_normalize             (GstProps *props);

Unrolls all lists in the given GstProps. This is usefull if you want to loop over the props.

`props` : | a property
Returns : | A GList with the unrolled props entries. g_list_free after usage.

### gst_props_set ()

    GstProps*   gst_props_set                   (GstProps *props,
                                                 const gchar *name,
                                                 ...);

Modifies the value of the given entry in the props struct. For the optional args, use GST_PROPS_FOO, where FOO is INT, STRING, etc. This macro expands to a variable number of arguments, hence the lack of precision in the function prototype. No terminating NULL is necessary as only one property can be changed.

`props` : | the props to modify
`name` : | the name of the entry to modify
`...` : | The prop entry.
Returns : | the new modified property structure.

### gst_props_get ()

    gboolean    gst_props_get                   (GstProps *props,
                                                 gchar *first_name,
                                                 ...);

Gets the contents of the props into given key/value pairs. Make sure you pass a NULL terminated list.

`props` : | the props to query
`first_name` : | the first key
`...` : | a pointer to a datastructure that can hold the value.
Returns : | TRUE if all of the props entries could be fetched.

### gst_props_get_safe ()

    gboolean    gst_props_get_safe              (GstProps *props,
                                                 gchar *first_name,
                                                 ...);

Gets the contents of the props into given key/value pairs.

`props` : | the props to query
`first_name` : | the first key
`...` : | a pointer to a datastructure that can hold the value.
Returns : | TRUE if all of the props entries could be fetched.

### gst_props_has_fixed_property ()

    gboolean    gst_props_has_fixed_property    (GstProps *props,
                                                 const gchar *name);

Checks if a given props has a property with the given name that is also fixed, ie. is not a list or a range.

`props` : | the props to check
`name` : | the name of the key to find
Returns : | TRUE if the property was found, FALSE otherwise.

### gst_props_has_property_typed ()

    gboolean    gst_props_has_property_typed    (GstProps *props,
                                                 const gchar *name,
                                                 GstPropsType type);

Checks if a given props has a property with the given name and the given type.

`props` : | the props to check
`name` : | the name of the key to find
`type` : | the type of the required property
Returns : | TRUE if the property was found, FALSE otherwise.

### gst_props_intersect ()

    GstProps*   gst_props_intersect             (GstProps *props1,
                                                 GstProps *props2);

Calculates the intersection bewteen two GstProps.

`props1` : | a property
`props2` : | another property
Returns : | a GstProps with the intersection or NULL if the intersection is empty. The new GstProps is floating and must be unreffed afetr use.

### gst_props_debug ()

    void        gst_props_debug                 (GstProps *props);

Dump the contents of the given properties into the DEBUG log.

`props` : | the props to debug

### gst_props_save_thyself ()

    xmlNodePtr  gst_props_save_thyself          (GstProps *props,
                                                 xmlNodePtr parent);

Saves the property into an XML representation.

`props` : | a property to save
`parent` : | the parent XML tree
Returns : | the new XML tree

### gst_props_load_thyself ()

    GstProps*   gst_props_load_thyself          (xmlNodePtr parent);

Creates a new property out of an XML tree.

`parent` : | the XML tree to load from
Returns : | the new property

### gst_props_get_entry ()

    const GstPropsEntry* gst_props_get_entry    (GstProps *props,
                                                 const gchar *name);

Get the props entry with the geven name

`props` : | the props to query
`name` : | the name of the entry to get
Returns : | The props entry with the geven name or NULL when the entry was not found.

### gst_props_add_entry ()

    void        gst_props_add_entry             (GstProps *props,
                                                 GstPropsEntry *entry);

Addes the given propsentry to the props

`props` : | the property to add the entry to
`entry` : | the entry to add

### gst_props_entry_new ()

    GstPropsEntry* gst_props_entry_new          (const gchar *name,
                                                 ...);

Create a new property entry with the given key/value.

`name` : | the name of the props entry
`...` : | the value of the entry
Returns : | the new entry.

### gst_props_entry_get ()

    gboolean    gst_props_entry_get             (const GstPropsEntry *entry,
                                                 ...);

Gets the contents of the entry.

`entry` : | the props entry to query
`...` : | a pointer to a type that can hold the value.
Returns : | TRUE is the props entry could be fetched.

### gst_props_entry_get_type ()

    GstPropsType gst_props_entry_get_type       (const GstPropsEntry *entry);

`entry` : |
Returns : |

### gst_props_entry_get_boolean ()

    gboolean    gst_props_entry_get_boolean     (const GstPropsEntry *entry,
                                                 gboolean *val);

Get the contents of the entry into the given gboolean.

`entry` : | the props entry to query
`val` : | a pointer to a gboolean to hold the value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_float ()

    gboolean    gst_props_entry_get_float       (const GstPropsEntry *entry,
                                                 gfloat *val);

Get the contents of the entry into the given gfloat.

`entry` : | the props entry to query
`val` : | a pointer to a gfloat to hold the value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_float_range ()

    gboolean    gst_props_entry_get_float_range (const GstPropsEntry *entry,
                                                 gfloat *min,
                                                 gfloat *max);

Get the contents of the entry into the given gfloats.

`entry` : | the props entry to query
`min` : | a pointer to a gfloat to hold the minimun value.
`max` : | a pointer to a gfloat to hold the maximum value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_fourcc_int ()

    gboolean    gst_props_entry_get_fourcc_int  (const GstPropsEntry *entry,
                                                 guint32 *val);

Get the contents of the entry into the given guint32.

`entry` : | the props entry to query
`val` : | a pointer to a guint32 to hold the value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_int ()

    gboolean    gst_props_entry_get_int         (const GstPropsEntry *entry,
                                                 gint *val);

Get the contents of the entry into the given gint.

`entry` : | the props entry to query
`val` : | a pointer to a gint to hold the value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_int_range ()

    gboolean    gst_props_entry_get_int_range   (const GstPropsEntry *entry,
                                                 gint *min,
                                                 gint *max);

Get the contents of the entry into the given gints.

`entry` : | the props entry to query
`min` : | a pointer to a gint to hold the minimun value.
`max` : | a pointer to a gint to hold the maximum value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_list ()

    gboolean    gst_props_entry_get_list        (const GstPropsEntry *entry,
                                                 const GList **val);

Get the contents of the entry into the given GList.

`entry` : | the props entry to query
`val` : | a pointer to a GList to hold the value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_name ()

    const gchar* gst_props_entry_get_name       (const GstPropsEntry *entry);

Get the name of the given props entry.

`entry` : | the props entry to query
Returns : | The name of the props entry.

### gst_props_entry_get_string ()

    gboolean    gst_props_entry_get_string      (const GstPropsEntry *entry,
                                                 const gchar **val);

Get the contents of the entry into the given gchar*.

`entry` : | the props entry to query
`val` : | a pointer to a gchar* to hold the value.
Returns : | TRUE is the value could be fetched. FALSE if the entry is not of given type or did not exist.

### gst_props_entry_get_type ()

    GstPropsType gst_props_entry_get_type       (const GstPropsEntry *entry);

`entry` : |
Returns : |

### gst_props_entry_is_fixed ()

    gboolean    gst_props_entry_is_fixed        (const GstPropsEntry *entry);

Checks if the props entry is fixe, ie. is not a list or a range.

`entry` : | the props entry to query
Returns : | TRUE is the props entry is fixed.

## See Also

GstCaps