## GstContext GstContext — Lightweight objects to represent element contexts |

## Synopsis

    #include <gst/gst.h>

                        GstContext;
    GstContext *        gst_context_new                     (const gchar *context_type,
                                                             gboolean persistent);
    GstContext *        gst_context_ref                     (GstContext *context);
    void                gst_context_unref                   (GstContext *context);
    GstContext *        gst_context_copy                    (const GstContext *context);
    const gchar *       gst_context_get_context_type        (const GstContext *context);
    gboolean            gst_context_has_context_type        (const GstContext *context,
                                                             const gchar *context_type);
    gboolean            gst_context_is_persistent           (const GstContext *context);
    const GstStructure * gst_context_get_structure          (const GstContext *context);
    GstStructure *      gst_context_writable_structure      (GstContext *context);
    #define             gst_context_make_writable           (context)
    #define             gst_context_is_writable             (context)
    gboolean            gst_context_replace                 (GstContext **old_context,
                                                             GstContext *new_context);

## Description

GstContext is a container object used to store contexts like a device context, a display server connection and similar concepts that should be shared between multiple elements.

Applications can set a context on a complete pipeline by using `gst_element_set_context()`, which will then be propagated to all child elements. Elements can handle these in GstElement::`set_context()` and merge them with the context information they already have.

When an element needs a context it will do the following actions in this order until one step succeeds: 1) Check if the element already has a context 2) Query downstream with GST_QUERY_CONTEXT for the context 2) Query upstream with GST_QUERY_CONTEXT for the context 3) Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required context types and afterwards check if a usable context was set now 4) Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message on the bus.

Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously known context on the element that asks for it if possible. Otherwise the application should provide one if it can.

## Details

### GstContext

    typedef struct _GstContext GstContext;

### gst_context_new ()

    GstContext *        gst_context_new                     (const gchar *context_type,
                                                             gboolean persistent);

Create a new context.

`persistent` : | Persistent context
Returns : | The new context. [transfer full]

Since 1.2

### gst_context_ref ()

    GstContext *        gst_context_ref                     (GstContext *context);

Convenience macro to increase the reference count of the context.

`context` : | the context to ref
Returns : | `context` (for convenience when doing assignments)

### gst_context_unref ()

    void                gst_context_unref                   (GstContext *context);

Convenience macro to decrease the reference count of the context, possibly freeing it.

`context` : | the context to unref

### gst_context_copy ()

    GstContext *        gst_context_copy                    (const GstContext *context);

Creates a copy of the context. Returns a copy of the context.

`context` : | the context to copy
Returns : | a new copy of `context`. MT safe. [transfer full]

### gst_context_get_context_type ()

    const gchar *       gst_context_get_context_type        (const GstContext *context);

Get the type of `context`.

`context` : | The GstContext.
Returns : | The type of the context.

Since 1.2

### gst_context_has_context_type ()

    gboolean            gst_context_has_context_type        (const GstContext *context,
                                                             const gchar *context_type);

Checks if `context` has `context_type`.

`context` : | The GstContext.
`context_type` : | Context type to check.
Returns : | `TRUE` if `context` has `context_type`.

Since 1.2

### gst_context_is_persistent ()

    gboolean            gst_context_is_persistent           (const GstContext *context);

Check if `context` is persistent.

`context` : | The GstContext.
Returns : | `TRUE` if the context is persistent.

Since 1.2

### gst_context_get_structure ()

    const GstStructure * gst_context_get_structure          (const GstContext *context);

Access the structure of the context.

`context` : | The GstContext.
Returns : | The structure of the context. The structure is still owned by the context, which means that you should not modify it, free it and that the pointer becomes invalid when you free the context. [transfer none]

Since 1.2

### gst_context_writable_structure ()

    GstStructure *      gst_context_writable_structure      (GstContext *context);

Get a writable version of the structure.

`context` : | The GstContext.
Returns : | The structure of the context. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event. This function checks if `context` is writable.

Since 1.2

### gst_context_make_writable()

    #define         gst_context_make_writable(context)  GST_CONTEXT_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (context)))

Checks if a context is writable. If not, a writable copy is made and returned.

`context` : | the context to make writable. [transfer full]
Returns : | a context (possibly a duplicate) that is writable. MT safe. [transfer full]

### gst_context_is_writable()

    #define         gst_context_is_writable(context)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (context))

Tests if you can safely write into a context's structure or validly modify the seqnum and timestamp fields.

`context` : | a GstContext

### gst_context_replace ()

    gboolean            gst_context_replace                 (GstContext **old_context,
                                                             GstContext *new_context);

Modifies a pointer to a GstContext to point to a different GstContext. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old context is unreffed, the new one is reffed).

Either `new_context` or the GstContext pointed to by `old_context` may be NULL.

`old_context` : | pointer to a pointer to a GstContext to be replaced. [inout][transfer full]
`new_context` : | pointer to a GstContext that will replace the context pointed to by `old_context`. [allow-none][transfer none]
Returns : | TRUE if `new_context` was different from `old_context`

## See Also

GstMiniObject, GstElement