MIRAGE_DebugContext object

## MIRAGE_DebugContext object MIRAGE_DebugContext object — Debug context object |

## Synopsis

    #include <mirage.h>

    enum                MIRAGE_DebugMasks;
    #define             MIRAGE_DEBUG                        (obj, lvl, msg...)
                        MIRAGE_DebugContext;
    gboolean            mirage_debug_context_set_debug_mask (MIRAGE_DebugContext *self,
                                                             gint debug_mask,
                                                             GError **error);
    gboolean            mirage_debug_context_get_debug_mask (MIRAGE_DebugContext *self,
                                                             gint *debug_mask,
                                                             GError **error);
    gboolean            mirage_debug_context_set_domain     (MIRAGE_DebugContext *self,
                                                             gchar *domain,
                                                             GError **error);
    gboolean            mirage_debug_context_get_domain     (MIRAGE_DebugContext *self,
                                                             gchar **domain,
                                                             GError **error);
    gboolean            mirage_debug_context_set_name       (MIRAGE_DebugContext *self,
                                                             gchar *name,
                                                             GError **error);
    gboolean            mirage_debug_context_get_name       (MIRAGE_DebugContext *self,
                                                             gchar **name,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_DebugContext

## Description

libMirage supports changing of debug message verbosity on fly, without the need to restart the application. To achieve this, MIRAGE_DebugContext objects are used.

As implied by its name, the object itself is a context that can be attached to any object that is derived from MIRAGE_Object. It stores a name string, debug name string and integer value representing debug mask. The idea behind debug context is to have a container object that a MIRAGE_Object can pass to its children. This way, when debug context's debug mask is changed, the change is automatically propagated to the children as well, because they all share the same context.

It should be noted that a MIRAGE_DebugContext object is just a container providing name and debug mask, while the actual debug message functionality is implemented by a MIRAGE_Object.

## Details

### enum MIRAGE_DebugMasks

    typedef enum {
        /* Debug types */
        MIRAGE_DEBUG_ERROR    = 0x00F1,
        MIRAGE_DEBUG_WARNING  = 0x00F2,
        /* Debug masks */
        MIRAGE_DEBUG_GOBJECT  = 0x0001,
        MIRAGE_DEBUG_CHAIN    = 0x0002,
        MIRAGE_DEBUG_PARSER   = 0x0004,
        MIRAGE_DEBUG_DISC     = 0x0008,
        MIRAGE_DEBUG_SESSION  = 0x0010,
        MIRAGE_DEBUG_TRACK    = 0x0020,
        MIRAGE_DEBUG_SECTOR   = 0x0040,
        MIRAGE_DEBUG_FRAGMENT = 0x0080,
        MIRAGE_DEBUG_CDTEXT   = 0x0100,
    } MIRAGE_DebugMasks;

Debug message types and debug masks used to control verbosity of various parts of libMirage.

All masks except `MIRAGE_DEBUG_ERROR` and `MIRAGE_DEBUG_WARNING` can be combined together to control verbosity of libMirage.

`MIRAGE_DEBUG_ERROR` | error message
`MIRAGE_DEBUG_WARNING` | warning message
`MIRAGE_DEBUG_GOBJECT` | message belonging to GObject functions
`MIRAGE_DEBUG_CHAIN` | message belonging to change propagation chain
`MIRAGE_DEBUG_PARSER` | message belonging to parser
`MIRAGE_DEBUG_DISC` | message belonging to disc
`MIRAGE_DEBUG_SESSION` | message belonging to session
`MIRAGE_DEBUG_TRACK` | message belonging to track
`MIRAGE_DEBUG_SECTOR` | message belonging to sector
`MIRAGE_DEBUG_FRAGMENT` | message belonging to fragment
`MIRAGE_DEBUG_CDTEXT` | message belonging to CD-TEXT encoder/decoder

### MIRAGE_DEBUG()

    #define             MIRAGE_DEBUG(obj, lvl, msg...)

Debugging macro, provided for convenience. It performs cast to MIRAGE_Object on `obj`, then calls `mirage_object_debug_message()` with debug level `lvl` and debug message `msg`....

`obj` : | object
`lvl` : | debug level
`msg...` : | debug message

### MIRAGE_DebugContext

    typedef struct _MIRAGE_DebugContext MIRAGE_DebugContext;

Contains private data only, and should be accessed using the functions below.

### mirage_debug_context_set_debug_mask ()

    gboolean            mirage_debug_context_set_debug_mask (MIRAGE_DebugContext *self,
                                                             gint debug_mask,
                                                             GError **error);

Sets debug context's debug mask.

`self` : | a MIRAGE_DebugContext
`debug_mask` : | debug mask
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_debug_context_get_debug_mask ()

    gboolean            mirage_debug_context_get_debug_mask (MIRAGE_DebugContext *self,
                                                             gint *debug_mask,
                                                             GError **error);

Retrieves debug context's debug mask.

`self` : | a MIRAGE_DebugContext
`debug_mask` : | location to store debug mask
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_debug_context_set_domain ()

    gboolean            mirage_debug_context_set_domain     (MIRAGE_DebugContext *self,
                                                             gchar *domain,
                                                             GError **error);

Sets debug context's domain name to `domain`.

`self` : | a MIRAGE_DebugContext
`domain` : | domain name
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_debug_context_get_domain ()

    gboolean            mirage_debug_context_get_domain     (MIRAGE_DebugContext *self,
                                                             gchar **domain,
                                                             GError **error);

Retrieves debug context's domain name.

A copy of domain name is stored into `domain`; it should be freed with `g_free()` when no longer needed.

`self` : | a MIRAGE_DebugContext
`domain` : | location to store domain name
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_debug_context_set_name ()

    gboolean            mirage_debug_context_set_name       (MIRAGE_DebugContext *self,
                                                             gchar *name,
                                                             GError **error);

Sets debug context's name to `name`.

`self` : | a MIRAGE_DebugContext
`name` : | name
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_debug_context_get_name ()

    gboolean            mirage_debug_context_get_name       (MIRAGE_DebugContext *self,
                                                             gchar **name,
                                                             GError **error);

Retrieves debug context's name.

A copy of name is stored into `name`; it should be freed with `g_free()` when no longer needed.

`self` : | a MIRAGE_DebugContext
`name` : | location to store name
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MIRAGE_Object