## GstData

GstData — Abstract structure for information that is passed among elements

## Synopsis

    #include <gst/gst.h>

    #define     GST_DATA                        (data)
    #define     GST_DATA_TYPE                   (data)
    #define     GST_DATA_FLAGS                  (data)
    #define     GST_DATA_FLAG_SHIFT             (flag)
    #define     GST_DATA_FLAG_UNSET             (data,flag)
                GstData;
    void        (*GstDataFreeFunction)          (GstData *data);
    GstData*    (*GstDataCopyFunction)          (const GstData *data);
    enum        GstDataFlags;
    #define     GST_DATA_REFCOUNT               (data)
    #define     GST_DATA_REFCOUNT_VALUE         (data)
    #define     GST_DATA_COPY_FUNC              (data)
    #define     GST_DATA_FREE_FUNC              (data)
    void        gst_data_init                   (GstData *data,
                                                 GType type,
                                                 guint16 flags,
                                                 GstDataFreeFunction free,
                                                 GstDataCopyFunction copy);
    void        gst_data_dispose                (GstData *data);
    void        gst_data_copy_into              (const GstData *data,
                                                 GstData *target);
    GstData*    gst_data_copy                   (const GstData *data);
    gboolean    gst_data_is_writable            (GstData *data);
    GstData*    gst_data_copy_on_write          (GstData *data);
    GstData*    gst_data_ref                    (GstData *data);
    GstData*    gst_data_ref_by_count           (GstData *data,
                                                 gint count);
    void        gst_data_unref                  (GstData *data);

## Description

This abstract structure provides a common base for GstBuffer, GstBufferPool and GstEvent. It is the main data type that is passed along in a pipeline. GstData provides refcounting, freeing and copying for its child classes.

## Details

### GST_DATA()

    #define GST_DATA(data)		((GstData*)(data))

Cast a pointer to a GstData

`data` : | The pointer to cast

### GST_DATA_TYPE()

    #define GST_DATA_TYPE(data)	(GST_DATA(data)->type)

Get the type of the GstData

`data` : | The data to get the type of

### GST_DATA_FLAGS()

    #define GST_DATA_FLAGS(data)		(GST_DATA(data)->flags)

Get the flags of this GstData

`data` : | The data to get the flags of

### GST_DATA_FLAG_SHIFT()

    #define GST_DATA_FLAG_SHIFT(flag)	(1<<(flag))

Shift a given flag so that it can be used in an or operation

`flag` : | The flag to shift

### GST_DATA_FLAG_UNSET()

    #define GST_DATA_FLAG_UNSET(data,flag) 	G_STMT_START{ (GST_DATA_FLAGS(data) &= ~(1<<(flag))); }G_STMT_END

Unset the given flag

`data` : | The data to unset the flag of
`flag` : | The flag to unset

### GstData

    typedef struct {
      GType 		 type;

      /* refcounting */
      GstAtomicInt		 refcount;

      guint16		 flags;

      /* utility function pointers, can override default */
      GstDataFreeFunction 	 free;		/* free the data */
      GstDataCopyFunction 	 copy;		/* copy the data */

      gpointer _gst_reserved[GST_PADDING];
    } GstData;

The base structure

GType `type`; | The type of this data.
GstAtomicInt `refcount`; | A refcount
guint16 `flags`; | The flags of this GstData
GstDataFreeFunction `free`; | A pointer to a custom free function
GstDataCopyFunction `copy`; | A pointer to a custom copy function
gpointer `_gst_reserved`[GST_PADDING]; | for future extensions

### GstDataFreeFunction ()

    void        (*GstDataFreeFunction)          (GstData *data);

The signature of the free function. Subclasses should provide a free function with this signature and pass it in the `gst_data_init()` function.

`data` : | The GstData to free

### GstDataCopyFunction ()

    GstData*    (*GstDataCopyFunction)          (const GstData *data);

The signature of the copy function. Subclasses should provide a copy function with this signature and pass it in the `gst_data_init()` function.

`data` : | The GstData to copy
Returns : | A new GstData that is a copy of data

### enum GstDataFlags

    typedef enum
    {
      GST_DATA_READONLY 	= 1,

      /* insert more */
      GST_DATA_FLAG_LAST 	= 8
    } GstDataFlags;

Various flags that can be set on a GstData

`GST_DATA_READONLY` | The data is readonly
`GST_DATA_FLAG_LAST` | Subclasses can add additional flags starting from this offset

### GST_DATA_REFCOUNT()

    #define GST_DATA_REFCOUNT(data)			((GST_DATA(data))->refcount)

Get access to the refcount field of the GstData

`data` : | The GstData to get the refcount field of

### GST_DATA_REFCOUNT_VALUE()

    #define GST_DATA_REFCOUNT_VALUE(data)		(gst_atomic_int_read (&(GST_DATA(data))->refcount))

Get the current refcount value

`data` : | The GstData to query

### GST_DATA_COPY_FUNC()

    #define GST_DATA_COPY_FUNC(data) 		(GST_DATA(data)->copy)

Get access to the copy function of the data

`data` : | The data to query

### GST_DATA_FREE_FUNC()

    #define GST_DATA_FREE_FUNC(data) 		(GST_DATA(data)->free)

Get access to the free function of the data

`data` : | The data to query

### gst_data_init ()

    void        gst_data_init                   (GstData *data,
                                                 GType type,
                                                 guint16 flags,
                                                 GstDataFreeFunction free,
                                                 GstDataCopyFunction copy);

Initialize the given data structure with the given parameters. The free and copy function will be called when this data is freed or copied respectively.

`data` : | a GstData to initialize
`type` : | the type of this data
`flags` : | flags for this data
`free` : | a free function
`copy` : | a copy function

### gst_data_dispose ()

    void        gst_data_dispose                (GstData *data);

Free all the resources allocated in the `gst_data_init()` function, mainly used by subclass implementors.

`data` : | a GstData to dispose

### gst_data_copy_into ()

    void        gst_data_copy_into              (const GstData *data,
                                                 GstData *target);

Copy the GstData into the specified target GstData structure. Thos method is mainly used by subclasses when they want to copy the relevant GstData info.

`data` : | a GstData to copy
`target` : | the target GstData to copy into

### gst_data_copy ()

    GstData*    gst_data_copy                   (const GstData *data);

Copies the given GstData. This function will call the custom subclass copy function or return NULL if no function was provided by the subclass.

`data` : | a GstData to copy
Returns : | a copy of the data or NULL if the data cannot be copied. The refcount of the original buffer is not changed so you should unref it when you don't need it anymore.

### gst_data_is_writable ()

    gboolean    gst_data_is_writable            (GstData *data);

Query if the gstdata needs to be copied before it can safely be modified.

`data` : | a GstData to copy
Returns : | FALSE if the given GstData is potentially shared and needs to be copied before it can be modified safely.

### gst_data_copy_on_write ()

    GstData*    gst_data_copy_on_write          (GstData *data);

Copies the given GstData if the refcount is greater than 1 so that the GstData object can be written to safely.

`data` : | a GstData to copy
Returns : | a copy of the data if the refcount is > 1 or the buffer is marked READONLY, data if the refcount == 1, or NULL if the data could not be copied. The refcount of the original buffer is decreased when a copy is made, so you are not supposed to use it after a call to this function.

### gst_data_ref ()

    GstData*    gst_data_ref                    (GstData *data);

Increments the reference count of this data.

`data` : | a GstData to reference
Returns : | the data

### gst_data_ref_by_count ()

    GstData*    gst_data_ref_by_count           (GstData *data,
                                                 gint count);

Increments the reference count of this data by the given number.

`data` : | a GstData to reference
`count` : | the number to increment the reference count by
Returns : | the data

### gst_data_unref ()

    void        gst_data_unref                  (GstData *data);

Decrements the refcount of this data. If the refcount is zero, the data will be freed.

When you add data to a pipeline, the pipeline takes ownership of the data. When the data has been used by some plugin, it must `unref()`s it. Applications usually don't need to `unref()` anything.

`data` : | a GstData to unreference

## See Also

GstBuffer, GstBufferPool, GstEvent