info: expose debugging printf functions

Other gst libraries and/or elements may want to add some debug logging to an
external debug system or implement delayed debugging for performance reasons.

Exposes the internal __gst_vasprintf as gst_info_vasprintf which has a fallback
to g_vasprintf if the debug system is disabled.

API: gst_info_vasprintf
API: gst_info_strdup_vprintf
API: gst_info_strdup_printf

https://bugzilla.gnome.org/show_bug.cgi?id=760421

diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index c3f4cc0..b15d037 100644 (file)
--- a/docs/gst/gstreamer-sections.txt
+++ b/docs/gst/gstreamer-sections.txt
@@ -1359,6 +1359,9 @@ GST_SEGMENT_FORMAT
 gst_debug_bin_to_dot_data
 gst_debug_bin_to_dot_file
 gst_debug_bin_to_dot_file_with_ts
+gst_info_vasprintf
+gst_info_strdup_vprintf
+gst_info_strdup_printf
 <SUBSECTION Standard>
 GST_TYPE_DEBUG_COLOR_FLAGS
 GST_TYPE_DEBUG_COLOR_MODE

diff --git a/gst/gstinfo.c b/gst/gstinfo.c
index 49b3696..e891eb4 100644 (file)
--- a/gst/gstinfo.c
+++ b/gst/gstinfo.c
@@ -2243,6 +2243,91 @@ __gst_info_fallback_vasprintf (char **result, char const *format, va_list args)
 }
 #endif
 
+/**
+ * gst_info_vasprintf:
+ * @result: (out): the resulting string
+ * @format: a printf style format string
+ * @args: the va_list of printf arguments for @format
+ *
+ * Allocates and fills a string large enough (including the terminating null
+ * byte) to hold the specified printf style @format and @args.
+ *
+ * This function deals with the GStreamer specific printf specifiers
+ * #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT.  If you do not have these specifiers
+ * in your @format string, you do not need to use this function and can use
+ * alternatives such as g_vasprintf().
+ *
+ * Free @result with g_free().
+ *
+ * Returns: the length of the string allocated into @result or -1 on any error
+ *
+ * Since: 1.8
+ */
+gint
+gst_info_vasprintf (gchar ** result, const gchar * format, va_list args)
+{
+  /* This will fallback to __gst_info_fallback_vasprintf() via a #define in
+   * gst_private.h if the debug system is disabled which will remove the gst
+   * specific printf format specifiers */
+  return __gst_vasprintf (result, format, args);
+}
+
+/**
+ * gst_info_strdup_vprintf:
+ * @format: a printf style format string
+ * @args: the va_list of printf arguments for @format
+ *
+ * Allocates, fills and returns a null terminated string from the printf style
+ * @format string and @args.
+ *
+ * See gst_info_vasprintf() for when this function is required.
+ *
+ * Free with g_free().
+ *
+ * Returns: a newly allocated null terminated string or %NULL on any error
+ *
+ * Since: 1.8
+ */
+gchar *
+gst_info_strdup_vprintf (const gchar * format, va_list args)
+{
+  gchar *ret;
+
+  if (gst_info_vasprintf (&ret, format, args) < 0)
+    ret = NULL;
+
+  return ret;
+}
+
+/**
+ * gst_info_strdup_printf:
+ * @format: a printf style format string
+ * @...: the printf arguments for @format
+ *
+ * Allocates, fills and returns a null terminated string from the printf style
+ * @format string and corresponding arguments.
+ *
+ * See gst_info_vasprintf() for when this function is required.
+ *
+ * Free with g_free().
+ *
+ * Returns: a newly allocated null terminated string or %NULL on any error
+ *
+ * Since: 1.8
+ */
+gchar *
+gst_info_strdup_printf (const gchar * format, ...)
+{
+  gchar *ret;
+  va_list args;
+
+  va_start (args, format);
+  ret = gst_info_strdup_vprintf (format, args);
+  va_end (args);
+
+  return ret;
+}
+
 #ifdef GST_ENABLE_FUNC_INSTRUMENTATION
 /* FIXME make this thread specific */
 static GSList *stack_trace = NULL;

diff --git a/gst/gstinfo.h b/gst/gstinfo.h
index bc7580d..6ef058d 100644 (file)
--- a/gst/gstinfo.h
+++ b/gst/gstinfo.h
@@ -396,6 +396,11 @@ GSList *        gst_debug_get_all_categories       (void);
 gchar * gst_debug_construct_term_color (guint colorinfo);
 gint    gst_debug_construct_win_color  (guint colorinfo);
 
+gint    gst_info_vasprintf              (gchar ** result,
+                                         const gchar * format,
+                                         va_list args) G_GNUC_PRINTF (2, 0);
+gchar * gst_info_strdup_vprintf         (const gchar *format, va_list args) G_GNUC_PRINTF (1, 0);
+gchar * gst_info_strdup_printf          (const gchar *format, ...) G_GNUC_PRINTF (1, 2);
 
 #ifndef GST_DISABLE_GST_DEBUG