## GstInfo

GstInfo — info/debugging/error handling

## Synopsis

    #include <gst/gst.h>

    const gchar* gst_get_category_name          (gint category);
    guint32     gst_info_get_categories         (void);
    void        gst_info_set_categories         (guint32 categories);
    void        gst_info_enable_category        (gint category);
    void        gst_info_disable_category       (gint category);
    void        gst_default_info_handler        (gint category,
                                                 gboolean incore,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);
    #define     GST_INFO_ENABLED
    #define     GST_INFO                        (cat,...)
    #define     GST_INFO_ELEMENT                (cat,element,...)
    guint32     gst_debug_get_categories        (void);
    void        gst_debug_set_categories        (guint32 categories);
    void        gst_debug_enable_category       (gint category);
    void        gst_debug_disable_category      (gint category);
    #define     GST_DEBUG_ENTER                 (...)
    #define     GST_DEBUG_LEAVE                 (...)
    #define     GST_DEBUG                       (cat, ...)
    #define     GST_DEBUG_FUNCPTR               (ptr)
    #define     GST_DEBUG_FUNCPTR_NAME          (ptr)
    #define     GST_DEBUG_PAD_NAME              (pad)
    #define     GST_DEBUG_THREAD_ARGS           (id)
    #define     GST_DEBUG_THREAD_FORMAT
    #define     GST_DEBUG_ELEMENT               (cat, element, ...)
    #define     GST_ERROR                       (element,...)
    #define     GST_ERROR_OBJECT                (element,object,...)
    void        (*GstDebugHandler)              (gint category,
                                                 gboolean core,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);
    void        gst_default_debug_handler       (gint category,
                                                 gboolean incore,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);
    void        gst_default_error_handler       (gchar *file,
                                                 gchar *function,
                                                 gint line,
                                                 gchar *debug_string,
                                                 void *element,
                                                 void *object,
                                                 gchar *string);
    void        (*GstInfoHandler)               (gint category,
                                                 gboolean incore,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);
    void        (*GstErrorHandler)              (gchar *file,
                                                 gchar *function,
                                                 gint line,
                                                 gchar *debug_string,
                                                 void *element,
                                                 void *object,
                                                 gchar *string);

## Description

gstinfo.c contains a number of debuggins subsystems.

The INFO subsystem is used to provide informative printouts to application and plugin developers. These messages can be enabled and disabled via a category system, which is a bitmask enabling you to turn on and off any subset of categories.

The DEBUG subsystem is similar, but is intended for core developers and those writing more complex pipelines or filters. It uses the same category system, but must be enabled at configure time else it's not compiled into the library. autogen.sh automatically enables the DEBUG subsystem.

The ERROR subsystem doesn't use categories, but will print out a more verbose message, and attempt to print out a stack trace of the error before aborting the application.

## Details

### gst_get_category_name ()

    const gchar* gst_get_category_name          (gint category);

Return a string containing the name of the category

`category` : | the category to return the name of
Returns : | string containing the name of the category

### gst_info_get_categories ()

    guint32     gst_info_get_categories         (void);

Return the current bitmask of enabled INFO categories The bit for any given category is (1 << GST_CAT_...).

Returns : | the current bitmask of enabled INFO categories The bit for any given category is (1 << GST_CAT_...).

### gst_info_set_categories ()

    void        gst_info_set_categories         (guint32 categories);

Enable the output of INFO categories based on the given bitmask. The bit for any given category is (1 << GST_CAT_...).

`categories` : | bitmask of INFO categories to enable

### gst_info_enable_category ()

    void        gst_info_enable_category        (gint category);

Enables the given GST_CAT_... INFO category.

`category` : | the category to enable

### gst_info_disable_category ()

    void        gst_info_disable_category       (gint category);

Disables the given GST_CAT_... INFO category.

`category` : | the category to disable

### gst_default_info_handler ()

    void        gst_default_info_handler        (gint category,
                                                 gboolean incore,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);

Prints out the INFO mesage in a variant of the following form:

FIXME: description should be fixed INFO:gst_function:542(args): [elementname] something neat happened

`category` : | category of the INFO message
`incore` : | if the info handler is for core code.
`file` : | the file the INFO occurs in
`function` : | the function the INFO occurs in
`line` : | the line number in the file
`debug_string` : | the current debug_string in the function, if any
`element` : | pointer to the GstElement in question
`string` : | the actual INFO string

### GST_INFO_ENABLED

    #define GST_INFO_ENABLED

When defined, INFO printouts are compiled into the library.

### GST_INFO()

    #define     GST_INFO(cat,...)

Print out any information usable at run-time by application developers.

`cat` : | the GST_CAT_... category for the information
`...` : | printf arguments

### GST_INFO_ELEMENT()

    #define     GST_INFO_ELEMENT(cat,element,...)

Print out information like GST_INFO, but with an element pointer to clarify things.

`cat` : | the GST_CAT_... category for the information
`element` : | pointer to the GstElement in question
`...` : | printf arguments

### gst_debug_get_categories ()

    guint32     gst_debug_get_categories        (void);

Return the current bitmask of enabled DEBUG categories

Returns : | the current bitmask of enabled DEBUG categories The bit for any given category is (1 << GST_CAT_...).

### gst_debug_set_categories ()

    void        gst_debug_set_categories        (guint32 categories);

Enable the output of DEBUG categories based on the given bitmask. The bit for any given category is (1 << GST_CAT_...).

`categories` : | bitmask of DEBUG categories to enable

### gst_debug_enable_category ()

    void        gst_debug_enable_category       (gint category);

Enables the given GST_CAT_... DEBUG category.

`category` : | the category to enable

### gst_debug_disable_category ()

    void        gst_debug_disable_category      (gint category);

Disables the given GST_CAT_... DEBUG category.

`category` : | the category to disable

### GST_DEBUG_ENTER()

    #define     GST_DEBUG_ENTER(...)

Called at the beginning of a function, it simply prints out a DEBUG string of "entering" in addition to the given string.

`...` : | printf arguments

### GST_DEBUG_LEAVE()

    #define     GST_DEBUG_LEAVE(...)

Called at the end of a function, it simply prints out a DEBUG string of "leaving" in addition to the given string.

`...` : | printf arguments

### GST_DEBUG()

    #define     GST_DEBUG(cat, ...)

Print out debugging information.

`cat` : | the GST_CAT_... the debug falls within
`...` : | printf arguments

### GST_DEBUG_FUNCPTR()

    #define     GST_DEBUG_FUNCPTR(ptr)

Add a function to the global function pointer table used for debugging.

`ptr` : | The pointer to add to the function table.

### GST_DEBUG_FUNCPTR_NAME()

    #define     GST_DEBUG_FUNCPTR_NAME(ptr)

Get the name of the given function pointer by looking up its name in the global function table.

`ptr` : | The pointer to look up.

### GST_DEBUG_PAD_NAME()

    #define     GST_DEBUG_PAD_NAME(pad)

Print out debugging statements for a pad.

`pad` : | The pad to debug.

### GST_DEBUG_THREAD_ARGS()

    #define     GST_DEBUG_THREAD_ARGS(id)

Part of the colorized debug functions for threads

`id` : | The thread id.

### GST_DEBUG_THREAD_FORMAT

    #define     GST_DEBUG_THREAD_FORMAT

Part of the colorized debug functions for threads

### GST_DEBUG_ELEMENT()

    #define     GST_DEBUG_ELEMENT(cat, element, ...)

Print out usefull debugging info of an element.

`cat` : | The category of this debugging statement.
`element` : | The element to debug.
`...` : | printf arguments

### GST_ERROR()

    #define     GST_ERROR(element,...)

Print out an error condition and abort the application.

`element` : | the GstElement in question
`...` : | printf arguments

### GST_ERROR_OBJECT()

    #define     GST_ERROR_OBJECT(element,object,...)

Print out an error condition and abort the application.

`element` : | the GstElement in question
`object` : | pointer to a 'contributing' object
`...` : | printf arguments

### GstDebugHandler ()

    void        (*GstDebugHandler)              (gint category,
                                                 gboolean core,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);

The debug handler

`category` : |
`core` : |
`file` : |
`function` : |
`line` : |
`debug_string` : |
`element` : |
`string` : |

### gst_default_debug_handler ()

    void        gst_default_debug_handler       (gint category,
                                                 gboolean incore,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);

Prints out the DEBUG mesage in a variant of the following form:

DEBUG(pid:cid):gst_function:542(args): [elementname] something neat happened

`category` : | category of the DEBUG message
`incore` : | if the debug handler is for core code.
`file` : | the file the DEBUG occurs in
`function` : | the function the DEBUG occurs in
`line` : | the line number in the file
`debug_string` : | the current debug_string in the function, if any
`element` : | pointer to the GstElement in question
`string` : | the actual DEBUG string

### gst_default_error_handler ()

    void        gst_default_error_handler       (gchar *file,
                                                 gchar *function,
                                                 gint line,
                                                 gchar *debug_string,
                                                 void *element,
                                                 void *object,
                                                 gchar *string);

Prints out the given ERROR string in a variant of the following format:

***** GStreamer ERROR ***** in file gstsomething.c at gst_function:399(arg) Element: /pipeline/thread/element.src Error: peer is null! ***** attempting to stack trace.... *****

At the end, it attempts to print the stack trace via GDB.

`file` : | the file the ERROR occurs in
`function` : | the function the INFO occurs in
`line` : | the line number in the file
`debug_string` : | the current debug_string in the function, if any
`element` : | pointer to the GstElement in question
`object` : | pointer to a related object
`string` : | the actual ERROR string

### GstInfoHandler ()

    void        (*GstInfoHandler)               (gint category,
                                                 gboolean incore,
                                                 const gchar *file,
                                                 const gchar *function,
                                                 gint line,
                                                 const gchar *debug_string,
                                                 void *element,
                                                 gchar *string);

The info handler

`category` : |
`incore` : |
`file` : |
`function` : |
`line` : |
`debug_string` : |
`element` : |
`string` : |

### GstErrorHandler ()

    void        (*GstErrorHandler)              (gchar *file,
                                                 gchar *function,
                                                 gint line,
                                                 gchar *debug_string,
                                                 void *element,
                                                 void *object,
                                                 gchar *string);

The error handler

`file` : |
`function` : |
`line` : |
`debug_string` : |
`element` : |
`object` : |
`string` : |