/* GStreamer

 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>

 *                    2000 Wim Taymans <wtay@chello.be>

 *                    2003 Benjamin Otte <in7y118@public.uni-hamburg.de>

 *

 * gstinfo.h: debugging functions

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Library General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Library General Public License for more details.

 *

 * You should have received a copy of the GNU Library General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

#ifndef __GSTINFO_H__

#define __GSTINFO_H__

#include <glib.h>

#include <glib-object.h>

#include <gst/gstconfig.h>

#ifndef M_PI

#define M_PI  3.14159265358979323846

#endif

G_BEGIN_DECLS

/**

 * GstDebugLevel:

 * @GST_LEVEL_NONE: No debugging level specified or desired. Used to deactivate

 *  debugging output.

 * @GST_LEVEL_ERROR: Error messages are to be used only when an error occured

 *  that stops the application from keeping working correctly.

 *  An examples is gst_element_error, which outputs a message with this priority.

 *  It does not mean that the application is terminating as with g_errror.

 * @GST_LEVEL_WARNING: Warning messages are to inform about abnormal behaviour

 *  that could lead to problems or weird behaviour later on. An example of this

 *  would be clocking issues ("your computer is pretty slow") or broken input

 *  data ("Can't synchronize to stream.")

 * @GST_LEVEL_INFO: Informational messages should be used to keep the developer

 *  updated about what is happening.

 *  Examples where this should be used are when a typefind function has

 *  successfully determined the type of the stream or when an mp3 plugin detects

 *  the format to be used. ("This file has mono sound.")

 * @GST_LEVEL_DEBUG: Debugging messages should be used when something common

 *  happens that is not the expected default behavior.

 *  An example would be notifications about state changes or receiving/sending of

 *  events.

 * @GST_LEVEL_LOG: Log messages are messages that are very common but might be

 *  useful to know. As a rule of thumb a pipeline that is iterating as expected

 *  should never output anzthing else but LOG messages.

 *  Examples for this are referencing/dereferencing of objects or cothread switches.

 * @GST_LEVEL_COUNT: The number of defined debugging levels.

 *

 * The level defines the importance of a debugging message. The more important a

 * message is, the greater the probability that the debugging system outputs it.

 */

typedef enum {

  GST_LEVEL_NONE = 0,

  GST_LEVEL_ERROR,

  GST_LEVEL_WARNING,

  GST_LEVEL_INFO,

  GST_LEVEL_DEBUG,

  GST_LEVEL_LOG,

  /* add more */

  GST_LEVEL_COUNT

} GstDebugLevel;

/**

 * GST_LEVEL_DEFAULT:

 *

 * Defines the default debugging level to be used with GStreamer. It is normally

 * set to #GST_LEVEL_NONE so nothing get printed.

 * As it can be configured at compile time, developer builds may chose to

 * override that though.

 * You can use this as an argument to gst_debug_set_default_threshold() to

 * reset the debugging output to default behaviour.

 */

#ifndef GST_LEVEL_DEFAULT

#define GST_LEVEL_DEFAULT GST_LEVEL_NONE

#endif

/* defines for format (colors etc)

 * don't change them around, it uses terminal layout

 * Terminal color strings:

 * 00=none 01=bold 04=underscore 05=blink 07=reverse 08=concealed

 * Text color codes:

 * 30=black 31=red 32=green 33=yellow 34=blue 35=magenta 36=cyan 37=white

 * Background color codes:

 * 40=black 41=red 42=green 43=yellow 44=blue 45=magenta 46=cyan 47=white

 */

/**

 * GstDebugColorFlags:

 * @GST_DEBUG_FG_BLACK: Use black as foreground color.

 * @GST_DEBUG_FG_RED: Use red as foreground color.

 * @GST_DEBUG_FG_GREEN: Use green as foreground color.

 * @GST_DEBUG_FG_YELLOW: Use yellow as foreground color.

 * @GST_DEBUG_FG_BLUE: Use blue as foreground color.

 * @GST_DEBUG_FG_MAGENTA: Use magenta as foreground color.

 * @GST_DEBUG_FG_CYAN: Use cyan as foreground color.

 * @GST_DEBUG_FG_WHITE: Use white as foreground color.

 * @GST_DEBUG_BG_BLACK: Use black as background color.

 * @GST_DEBUG_BG_RED: Use red as background color.

 * @GST_DEBUG_BG_GREEN: Use green as background color.

 * @GST_DEBUG_BG_YELLOW: Use yellow as background color.

 * @GST_DEBUG_BG_BLUE: Use blue as background color.

 * @GST_DEBUG_BG_MAGENTA: Use magenta as background color.

 * @GST_DEBUG_BG_CYAN: Use cyan as background color.

 * @GST_DEBUG_BG_WHITE: Use white as background color.

 * @GST_DEBUG_BOLD: Make the output bold.

 * @GST_DEBUG_UNDERLINE: Underline the output.

 *

 * These are some terminal style flags you can use when creating your

 * debugging categories to make them stand out in debugging output.

 */

typedef enum {

  /* colors */

  GST_DEBUG_FG_BLACK		= 0x0000,

  GST_DEBUG_FG_RED		= 0x0001,

  GST_DEBUG_FG_GREEN		= 0x0002,

  GST_DEBUG_FG_YELLOW		= 0x0003,

  GST_DEBUG_FG_BLUE		= 0x0004,

  GST_DEBUG_FG_MAGENTA		= 0x0005,

  GST_DEBUG_FG_CYAN		= 0x0006,

  GST_DEBUG_FG_WHITE		= 0x0007,

  /* background colors */

  GST_DEBUG_BG_BLACK		= 0x0000,

  GST_DEBUG_BG_RED		= 0x0010,

  GST_DEBUG_BG_GREEN		= 0x0020,

  GST_DEBUG_BG_YELLOW		= 0x0030,

  GST_DEBUG_BG_BLUE		= 0x0040,

  GST_DEBUG_BG_MAGENTA		= 0x0050,

  GST_DEBUG_BG_CYAN		= 0x0060,

  GST_DEBUG_BG_WHITE		= 0x0070,

  /* other formats */

  GST_DEBUG_BOLD		= 0x0100,

  GST_DEBUG_UNDERLINE		= 0x0200

} GstDebugColorFlags;

#define GST_DEBUG_FG_MASK	(0x000F)

#define GST_DEBUG_BG_MASK	(0x00F0)

#define GST_DEBUG_FORMAT_MASK	(0xFF00)

typedef struct _GstDebugCategory GstDebugCategory;

/**

 * GstDebugCategory:

 *

 * This is the struct that describes the categories. Once initialized with

 * #GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.

 */

struct _GstDebugCategory {

  /*< private >*/

  gint                  threshold;

  guint			color;		/* see defines above */

  const gchar *		name;

  const gchar *		description;

};

/********** some convenience macros for debugging **********/

/**

 * GST_STR_NULL:

 * @str: The string to check.

 *

 * Macro to use when a string must not be NULL, but may be NULL. If the string

 * is NULL, "(NULL)" is printed instead.

 * In GStreamer printf string arguments may not be NULL, because on some

 * platforms (ie Solaris) the libc crashes in that case. This includes debugging

 * strings.

 */

#define GST_STR_NULL(str) ((str) ? (str) : "(NULL)")

/* FIXME, not MT safe */

/**

 * GST_DEBUG_PAD_NAME:

 * @pad: The pad to debug.

 *

 * Evaluates to 2 strings, that describe the pad. Often used in debugging

 * statements.

 */

#define GST_DEBUG_PAD_NAME(pad) \

  (pad != NULL) ?  \

  ((GST_OBJECT_PARENT(pad) != NULL) ? \

  GST_STR_NULL (GST_OBJECT_NAME (GST_OBJECT_PARENT(pad))) : \

  "''" ) : "''", \

  (pad != NULL) ? GST_STR_NULL (GST_OBJECT_NAME (pad)) : "''"

/**

 * GST_FUNCTION:

 *

 * This macro should evaluate to the name of the current function and be should

 * be defined when configuring your project, as it is compiler dependant. If it

 * is not defined, some default value is used. It is used to provide debugging

 * output with the function name of the message.

 */

#ifndef GST_FUNCTION

#  define GST_FUNCTION     ((const char*) (__FUNCTION__))

#  define GST_FUNCTION     ((const char*) (__func__))

#else

#endif

#endif /* ifndef GST_FUNCTION */

typedef struct _GstDebugMessage GstDebugMessage;

/**

 * GstLogFunction:

 * @category: a #GstDebugCategory

 * @level: a #GstDebugLevel

 * @file: file name

 * @function: function name

 * @line: line number

 * @object: a #GObject

 * @message: the message

 * @data: user data for the log function

 *

 * Function prototype for a logging function that can be registered with

 * gst_debug_add_log_function().

 * Use G_GNUC_NO_INSTRUMENT on that function.

 */

typedef void (*GstLogFunction)  (GstDebugCategory * category,

                                 GstDebugLevel      level,

                                 const gchar      * file,

                                 const gchar      * function,

                                 gint               line,

                                 GObject          * object,

                                 GstDebugMessage  * message,

                                 gpointer           data);

#ifndef GST_DISABLE_GST_DEBUG

/* FIXME 0.11: move this into private headers */

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            _gst_debug_init (void);

#ifdef GST_USING_PRINTF_EXTENSION

/* not using G_GNUC_PRINTF, since gcc will choke on GST_PTR_FORMAT being %P */

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void		    gst_debug_log            (GstDebugCategory * category,

                                          GstDebugLevel      level,

                                          const gchar      * file,

                                          const gchar      * function,

                                          gint               line,

                                          GObject          * object,

                                          const gchar      * format,

                                          ...) G_GNUC_NO_INSTRUMENT;

#else /* GST_USING_PRINTF_EXTENSION */

void		    gst_debug_log            (GstDebugCategory * category,

                                          GstDebugLevel      level,

                                          const gchar      * file,

                                          const gchar      * function,

                                          gint               line,

                                          GObject          * object,

                                          const gchar      * format,

                                          ...) G_GNUC_PRINTF (7, 8) G_GNUC_NO_INSTRUMENT;

#endif /* GST_USING_PRINTF_EXTENSION */

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_log_valist     (GstDebugCategory * category,

                                          GstDebugLevel      level,

                                          const gchar      * file,

                                          const gchar      * function,

                                          gint	              line,

                                          GObject          * object,

                                          const gchar      * format,

                                          va_list            args) G_GNUC_NO_INSTRUMENT;

#ifdef __SYMBIAN32__

IMPORT_C

#endif

const gchar   * gst_debug_message_get    (GstDebugMessage  * message);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_log_default    (GstDebugCategory * category,

                                          GstDebugLevel      level,

                                          const gchar      * file,

                                          const gchar      * function,

                                          gint               line,

                                          GObject          * object,

                                          GstDebugMessage  * message,

                                          gpointer           unused) G_GNUC_NO_INSTRUMENT;

#ifdef __SYMBIAN32__

IMPORT_C

#endif

G_CONST_RETURN gchar *

                gst_debug_level_get_name (GstDebugLevel level);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_add_log_function            (GstLogFunction func,

                                                       gpointer       data);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

guint           gst_debug_remove_log_function         (GstLogFunction func);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

guint           gst_debug_remove_log_function_by_data (gpointer       data);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_set_active  (gboolean active);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

gboolean        gst_debug_is_active   (void);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_set_colored (gboolean colored);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

gboolean        gst_debug_is_colored  (void);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_set_default_threshold	    (GstDebugLevel level);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

GstDebugLevel   gst_debug_get_default_threshold	    (void);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_set_threshold_for_name    (const gchar * name,

                                                     GstDebugLevel level);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void            gst_debug_unset_threshold_for_name  (const gchar * name);

/**

 * GST_DEBUG_CATEGORY:

 * @cat: the category

 *

 * Defines a GstDebugCategory variable.

 * This macro expands to nothing if debugging is disabled.

 */

#define GST_DEBUG_CATEGORY(cat) GstDebugCategory *cat = NULL

/**

 * GST_DEBUG_CATEGORY_EXTERN:

 * @cat: the category

 *

 * Declares a GstDebugCategory variable as extern. Use in header files.

 * This macro expands to nothing if debugging is disabled.

 */

#define GST_DEBUG_CATEGORY_EXTERN(cat) extern GstDebugCategory *cat

/**

 * GST_DEBUG_CATEGORY_STATIC:

 * @cat: the category

 *

 * Defines a static GstDebugCategory variable.

 * This macro expands to nothing if debugging is disabled.

 */

#define GST_DEBUG_CATEGORY_STATIC(cat) static GstDebugCategory *cat = NULL

#ifdef __SYMBIAN32__

IMPORT_C

#endif

GstDebugCategory *_gst_debug_category_new (const gchar * name,

                                           guint         color,

                                           const gchar * description);

/**

 * GST_DEBUG_CATEGORY_INIT:

 * @cat: the category to initialize.

 * @name: the name of the category.

 * @color: the colors to use for a color representation or 0 for no color.

 * @description: optional description of the category.

 *

 * Initializes a new #GstDebugCategory with the given properties and set to

 * the default threshold.

 *

 * <note>

 * <para>

 * This macro expands to nothing if debugging is disabled.

 * </para>

 * <para>

 * When naming your category, please follow the following conventions to ensure

 * that the pattern matching for categories works as expected. It is not

 * earth-shattering if you don't follow these conventions, but it would be nice

 * for everyone.

 * </para>

 * <para>

 * If you define a category for a plugin or a feature of it, name the category

 * like the feature. So if you wanted to write a "filesrc" element, you would

 * name the category "filesrc". Use lowercase letters only.

 * If you define more than one category for the same element, append an

 * underscore and an identifier to your categories, like this: "filesrc_cache"

 * </para>

 * <para>

 * If you create a library or an application using debugging categories, use a

 * common prefix followed by an underscore for all your categories. GStreamer

 * uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure

 * to include uppercase letters.

 * </para>

 * </note>

 */

#define GST_DEBUG_CATEGORY_INIT(cat,name,color,description) G_STMT_START{\

  if (cat == NULL)							\

    cat = _gst_debug_category_new (name,color,description);		\

}G_STMT_END

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void	gst_debug_category_free		(GstDebugCategory *	category);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void	gst_debug_category_set_threshold (GstDebugCategory *	category,

					 GstDebugLevel		level);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

void	gst_debug_category_reset_threshold(GstDebugCategory *	category);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

GstDebugLevel

	gst_debug_category_get_threshold (GstDebugCategory *	category);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

G_CONST_RETURN gchar *

	gst_debug_category_get_name	(GstDebugCategory *	category);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

guint	gst_debug_category_get_color	(GstDebugCategory *	category);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

G_CONST_RETURN gchar *

	gst_debug_category_get_description (GstDebugCategory *	category);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

GSList *

        gst_debug_get_all_categories	(void);

#ifdef __SYMBIAN32__

IMPORT_C

#endif