## libbtcore

libbtcore — core library of the buzztard application framework

## Synopsis

    #include <libbtcore/core.h>

    #define             BT_IS_GVALUE                        (v)
    #define             BT_IS_STRING                        (a)
    guint               bt_cpu_load_get_current             (void);
    void                bt_init                             (int *argc,
                                                             char **argv[]);
    void                bt_init_add_option_groups           (GOptionContext * const ctx);
    gboolean            bt_init_check                       (int *argc,
                                                             char **argv[],
                                                             GError **err);
    GOptionGroup *      bt_init_get_option_group            (void);
    void                bt_deinit                           (void);
    extern const unsigned int bt_major_version;
    extern const unsigned int bt_micro_version;
    extern const unsigned int bt_minor_version;
    #define             return_if_disposed
    #define             return_val_if_disposed              (a)
    #define             safe_string                         (a)
    #define             G_OBJECT_REF_COUNT                  (obj)
    #define             G_POINTER_ALIAS                     (type,
                                                             var)
    GType               bt_g_type_get_base_type             (const GType type);
    #define             g_object_try_ref                    (obj)
    #define             g_object_try_unref                  (obj)
    #define             g_object_try_weak_ref               (obj)
    #define             g_object_try_weak_unref             (obj)
    gboolean            bt_bin_activate_tee_chain           (GstBin *bin,
                                                             GstElement *tee,
                                                             GList *analyzers,
                                                             gboolean is_playing);
    gboolean            bt_bin_deactivate_tee_chain         (GstBin *bin,
                                                             GstElement *tee,
                                                             GList *analyzers,
                                                             gboolean is_playing);
    GList *             bt_gst_check_core_elements          (void);
    GList *             bt_gst_check_elements               (GList *list);
    const gchar *       bt_gst_debug_pad_link_return        (GstPadLinkReturn link_res,
                                                             GstPad *src_pad,
                                                             GstPad *sink_pad);
    gboolean            bt_gst_element_factory_can_sink_media_type
                                                            (GstElementFactory *factory,
                                                             const gchar *name);
    GList *             bt_gst_registry_get_element_factories_matching_all_categories
                                                            (const gchar *class_filter);
    GList *             bt_gst_registry_get_element_names_matching_all_categories
                                                            (const gchar *class_filter);

## Description

The library offers base objects such as BtApplication and BtSong.

## Details

### BT_IS_GVALUE()

    #define BT_IS_GVALUE(v) (G_VALUE_TYPE(v)!=G_TYPE_INVALID)

checks if the supplied gvalue is initialized (not all fields zero).

`v` : | pointer to a GValue

### BT_IS_STRING()

    #define BT_IS_STRING(a) (a && *a)

checks if the supplied string pointer is not `NULL` and contains not just '\0'

`a` : | string pointer

### bt_cpu_load_get_current ()

    guint               bt_cpu_load_get_current             (void);

Determines the current CPU load.

Returns : | CPU usage as integer ranging from 0% to 100%

### bt_init ()

    void                bt_init                             (int *argc,
                                                             char **argv[]);

Initializes the Buzztard Core library.

### Note

This function will terminate your program if it was unable to initialize the core for some reason. If you want your program to fall back, use `bt_init_check()` instead.

WARNING: This function does not work in the same way as corresponding functions in other glib-style libraries, such as `gtk_init()`. In particular, unknown command line options cause this function to abort program execution.

`argc` : | pointer to application's argc. [inout]
`argv` : | pointer to application's argv. [array length=argc][inout]

### bt_init_add_option_groups ()

    void                bt_init_add_option_groups           (GOptionContext * const ctx);

Adds all option groups to the main context the core library will pull in.

`ctx` : | main option context

### bt_init_check ()

    gboolean            bt_init_check                       (int *argc,
                                                             char **argv[],
                                                             GError **err);

Initializes the Buzztard core library.

This function will return `FALSE` if Buzztard core could not be initialized for some reason. If you want your program to fail fatally, use `bt_init()` instead.

`argc` : | pointer to application's argc. [inout]
`argv` : | pointer to application's argv. [array length=argc][inout]
`err` : | pointer to a GError to which a message will be posted on error
Returns : | `TRUE` if Buzztard core could be initialized.

### bt_init_get_option_group ()

    GOptionGroup *      bt_init_get_option_group            (void);

Returns a GOptionGroup with libbtcore's argument specifications. The group is set up to use standard GOption callbacks, so when using this group in combination with GOption parsing methods, all argument parsing and initialization is automated.

This function is useful if you want to integrate libbtcore with other libraries that use GOption (see `g_option_context_add_group()` ).

Returns : | a pointer to a GOption group. Should be dereferenced after use.

### bt_deinit ()

    void                bt_deinit                           (void);

It is normally not needed to call this function in a normal application as the resources will automatically be freed when the program terminates. This function is therefore mostly used by testsuites and other memory profiling tools.

### bt_major_version

    extern const unsigned int bt_major_version;

buzztard version stamp, major part; determined from BT_MAJOR_VERSION

### bt_micro_version

    extern const unsigned int bt_micro_version;

buzztard version stamp, micro part; determined from BT_MICRO_VERSION

### bt_minor_version

    extern const unsigned int bt_minor_version;

buzztard version stamp, minor part; determined from BT_MINOR_VERSION

### return_if_disposed

    #define return_if_disposed() if(self->priv->dispose_has_run) return

Checks `self->priv->dispose_has_run` and if `TRUE` returns. This macro is handy to use at the start of all class routines such as `GObjectClass.get_property()`, `GObjectClass.set_property()`, `GObjectClass.dispose()`.

### return_val_if_disposed()

    #define return_val_if_disposed(a) if(self->priv->dispose_has_run) return(a)

Checks `self->priv->dispose_has_run` and if `TRUE` returns with the supplied arg `a`. This macro is handy to use at the start of e.g. idle handlers.

`a` : | return value

### safe_string()

    #define safe_string(a) ((gchar *)(a)?(gchar *)(a):"")

passed the supplied string through or return an empty string when it is NULL

`a` : | string pointer
Returns : | the given string or an empty string in the case of a NULL argument

### G_OBJECT_REF_COUNT()

    #define G_OBJECT_REF_COUNT(obj) ((obj)?((G_OBJECT(obj))->ref_count):0)

Read the objects reference counter. Implemented as a macro, so don't use expressions for `obj`.

`obj` : | the object (may be `NULL`)
Returns : | the reference counter.

### G_POINTER_ALIAS()

    #define             G_POINTER_ALIAS(type,var)

Defines a anonymous union to handle gcc-4.1s type punning warning that one gets when using e.g. `g_object_try_weak_ref()`

`type` : | the type
`var` : | the variable name

### bt_g_type_get_base_type ()

    GType               bt_g_type_get_base_type             (const GType type);

Call `g_type_parent()` as long as it returns a parent.

`type` : | a GType
Returns : | the super parent type, aka base type.

### g_object_try_ref()

    #define             g_object_try_ref(obj)

If the supplied object is not `NULL` then reference it via `g_object_ref()`.

`obj` : | the object to reference
Returns : | the referenced object or `NULL`

### g_object_try_unref()

    #define             g_object_try_unref(obj)

If the supplied object is not `NULL` then release the reference via `g_object_unref()`.

`obj` : | the object to release the reference

### g_object_try_weak_ref()

    #define             g_object_try_weak_ref(obj)

If the supplied object is not `NULL` then reference it via `g_object_add_weak_pointer()`.

`obj` : | the object to reference

### g_object_try_weak_unref()

    #define             g_object_try_weak_unref(obj)

If the supplied object is not `NULL` then release the reference via `g_object_remove_weak_pointer()`.

`obj` : | the object to release the reference

### bt_bin_activate_tee_chain ()

    gboolean            bt_bin_activate_tee_chain           (GstBin *bin,
                                                             GstElement *tee,
                                                             GList *analyzers,
                                                             gboolean is_playing);

Add the elements from `analyzers` to the `bin` and link them. Handle pad blocking in playing mode.

Return: `TRUE` for success

`bin` : | the bin
`tee` : | the tee to connect the chain to
`analyzers` : | the list of analyzers
`is_playing` : | wheter the pipeline is streaming data

### bt_bin_deactivate_tee_chain ()

    gboolean            bt_bin_deactivate_tee_chain         (GstBin *bin,
                                                             GstElement *tee,
                                                             GList *analyzers,
                                                             gboolean is_playing);

Add the elements from `analyzers` to the `bin` and link them. Handle pad blocking in playing mode.

Return: `TRUE` for success

`bin` : | the bin
`tee` : | the tee to connect the chain to
`analyzers` : | the list of analyzers
`is_playing` : | wheter the pipeline is streaming data

### bt_gst_check_core_elements ()

    GList *             bt_gst_check_core_elements          (void);

Check if all core elements exist.

Returns : | a list of elements that does not exist, `NULL` if all elements exist. The list is static, don't free.

### bt_gst_check_elements ()

    GList *             bt_gst_check_elements               (GList *list);

Check if the given elements exist.

`list` : | a GList with element names
Returns : | a list of element-names which do not exist, `NULL` if all elements exist

### bt_gst_debug_pad_link_return ()

    const gchar *       bt_gst_debug_pad_link_return        (GstPadLinkReturn link_res,
                                                             GstPad *src_pad,
                                                             GstPad *sink_pad);

Format a nice debug message from failed pad links.

`link_res` : | pad link result
`src_pad` : | the source pad
`sink_pad` : | the sink pad
Returns : | the message. The returned string has to be used before the can be called again, otherwise the previous reult will be overwritten.

### bt_gst_element_factory_can_sink_media_type ()

    gboolean            bt_gst_element_factory_can_sink_media_type
                                                            (GstElementFactory *factory,
                                                             const gchar *name);

Check if the sink pads of the given `factory` are compatible with the given `name`. The `name` can e.g. be "audio/x-raw-int".

`factory` : | element factory to check
`name` : | caps type name
Returns : | `TRUE` if the pads are compatible.

### bt_gst_registry_get_element_factories_matching_all_categories ()

    GList *             bt_gst_registry_get_element_factories_matching_all_categories
                                                            (const gchar *class_filter);

Iterates over all available elements and filters by categories given in `class_filter`.

`class_filter` : | path for filtering (e.g. "Sink/Audio")
Returns : | list of element factories, use `gst_plugin_feature_list_free()` after use.

Since 0.6

### bt_gst_registry_get_element_names_matching_all_categories ()

    GList *             bt_gst_registry_get_element_names_matching_all_categories
                                                            (const gchar *class_filter);

Iterates over all available elements and filters by categories given in `class_filter`.

`class_filter` : | path for filtering (e.g. "Sink/Audio")
Returns : | list of read-only element names, g_list_free after use.