[gstreamermm] Gst::Bus: minor changes

[Marcin Kolny <mkolny src gnome org>]

commit 98bca5a28c6f847f6518f51f5ad64a3445fe3b38
Author: Marcin Kolny <marcin kolny gmail com>
Date:   Mon May 16 17:57:57 2016 +0200

    Gst::Bus: minor changes
    
        * gstreamer/src/bus.{ccg|hg}: minors.
        * gstreamer/src/gst_docs_override.xml: override some documentation,
          to avoid pm warnings.

 gstreamer/src/bus.ccg               |    3 +-
 gstreamer/src/bus.hg                |   11 +--
 gstreamer/src/gst_docs_override.xml |  172 +++++++++++++++++++++++++++++++++++
 3 files changed, 175 insertions(+), 11 deletions(-)
---
diff --git a/gstreamer/src/bus.ccg b/gstreamer/src/bus.ccg
index 74d3159..34bab7f 100644
--- a/gstreamer/src/bus.ccg
+++ b/gstreamer/src/bus.ccg
@@ -1,6 +1,6 @@
 /* gstreamermm - a C++ wrapper for gstreamer
  *
- * Copyright 2008 The gstreamermm Development Team
+ * Copyright 2008-2016 The gstreamermm Development Team
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -17,7 +17,6 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-#include <gst/gst.h>
 _PINCLUDE(glibmm/private/object_p.h)
 _PINCLUDE(gstreamermm/private/object_p.h)
 
diff --git a/gstreamer/src/bus.hg b/gstreamer/src/bus.hg
index 6a7c247..ed003a5 100644
--- a/gstreamer/src/bus.hg
+++ b/gstreamer/src/bus.hg
@@ -1,6 +1,6 @@
 /* gstreamermm - a C++ wrapper for gstreamer
  *
- * Copyright 2008 The gstreamermm Development Team
+ * Copyright 2008-2016 The gstreamermm Development Team
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -17,7 +17,6 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-#include <gst/gst.h>
 #include <gstreamermm/object.h>
 #include <gstreamermm/clock.h>
 #include <gstreamermm/message.h>
@@ -33,12 +32,6 @@ class Message;
 
 _WRAP_ENUM(BusFlags, GstBusFlags)
 
-/** The result values for a Gst::Bus::SlotMessageSync.
- * - Gst::BUS_DROP - Drop the message.
- * - Gst::BUS_PASS - Pass the message to the async queue.
- * - Gst::BUS_ASYNC - Pass message to async queue, continue if message is
- * handled.
- */
 _WRAP_ENUM(BusSyncReply, GstBusSyncReply)
 
 /** A class that encompasses the GStreamer asynchronous message bus subsystem.
@@ -81,7 +74,7 @@ _WRAP_ENUM(BusSyncReply, GstBusSyncReply)
  * Note that a Gst::Pipeline will set its bus into flushing state when
  * changing from READY to NULL state.
  *
- * Last reviewed on 2006-03-12 (0.10.5)
+ * Last reviewed on 2016-05-16 (1.8.0)
  */
 class Bus : public Object
 {
diff --git a/gstreamer/src/gst_docs_override.xml b/gstreamer/src/gst_docs_override.xml
index c55dc14..2122b9a 100644
--- a/gstreamer/src/gst_docs_override.xml
+++ b/gstreamer/src/gst_docs_override.xml
@@ -162,4 +162,176 @@ members must be set.
 <return></return>
 </function>
 
+<function name="gst_bus_poll">
+<description>
+Poll the bus for messages. Will block while waiting for messages to come.
+You can specify a maximum time to poll with the @timeout parameter. If
+ timeout is negative, this function will block indefinitely.
+
+All messages not in @events will be popped off the bus and will be ignored.
+It is not possible to use message enums beyond #GST_MESSAGE_EXTENDED in the
+ events mask
+
+Because poll is implemented using the &quot;message&quot; signal enabled by
+gst_bus_add_signal_watch(), calling gst_bus_poll() will cause the &quot;message&quot;
+signal to be emitted for every message that poll sees. Thus a &quot;message&quot;
+signal handler will see the same messages that this function sees -- neither
+will steal messages from the other.
+
+This function will run a main loop from the default main context when
+polling.
+
+You should never use this function, since it is pure evil. This is
+especially true for GUI applications based on Gtk+ or Qt, but also for any
+other non-trivial application that uses the GLib main loop. As this function
+runs a GLib main loop, any callback attached to the default GLib main
+context may be invoked. This could be timeouts, GUI events, I/O events etc.;
+even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks
+may do things you do not expect, e.g. destroy the main application window or
+some other resource; change other application state; display a dialog and
+run another main loop until the user clicks it away. In short, using this
+function may add a lot of complexity to your code through unexpected
+re-entrancy and unexpected changes to your application's state.
+
+For 0 timeouts use gst_bus_pop_filtered() instead of this function; for
+other short timeouts use gst_bus_timed_pop_filtered(); everything else is
+better handled by setting up an asynchronous bus watch and doing things
+from there.
+
+
+</description>
+<parameters>
+<parameter name="bus">
+<parameter_description> a #GstBus
+</parameter_description>
+</parameter>
+<parameter name="events">
+<parameter_description> a mask of #GstMessageType, representing the set of message types to
+poll for (note special handling of extended message types below)
+</parameter_description>
+</parameter>
+<parameter name="timeout">
+<parameter_description> the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll
+indefinitely.
+</parameter_description>
+</parameter>
+</parameters>
+<return> the message that was received,
+or %NULL if the poll timed out. The message is taken from the
+bus.
+</return>
+</function>
+
+<function name="gst_bus_pop">
+<description>
+Get a message from the bus.
+
+
+</description>
+<parameters>
+<parameter name="bus">
+<parameter_description> a #GstBus to pop
+</parameter_description>
+</parameter>
+</parameters>
+<return> the #GstMessage that is on the
+bus, or %NULL if the bus is empty. The message is taken from
+the bus.
+
+MT safe.
+</return>
+</function>
+
+<function name="gst_bus_pop_filtered">
+<description>
+Get a message matching @type from the bus.  Will discard all messages on
+the bus that do not match @type and that have been posted before the first
+message that does match @type.  If there is no message matching @type on
+the bus, all messages will be discarded. It is not possible to use message
+enums beyond #GST_MESSAGE_EXTENDED in the @events mask.
+
+
+</description>
+<parameters>
+<parameter name="bus">
+<parameter_description> a #GstBus to pop
+</parameter_description>
+</parameter>
+<parameter name="types">
+<parameter_description> message types to take into account
+</parameter_description>
+</parameter>
+</parameters>
+<return> the next #GstMessage matching
+ type that is on the bus, or %NULL if the bus is empty or there
+is no message matching @type. The message is taken from the bus.
+
+MT safe.
+</return>
+</function>
+
+<function name="gst_bus_timed_pop">
+<description>
+Get a message from the bus, waiting up to the specified timeout.
+
+If @timeout is 0, this function behaves like gst_bus_pop(). If @timeout is
+#GST_CLOCK_TIME_NONE, this function will block forever until a message was
+posted on the bus.
+
+
+</description>
+<parameters>
+<parameter name="bus">
+<parameter_description> a #GstBus to pop
+</parameter_description>
+</parameter>
+<parameter name="timeout">
+<parameter_description> a timeout
+</parameter_description>
+</parameter>
+</parameters>
+<return> the #GstMessage that is on the
+bus after the specified timeout or %NULL if the bus is empty
+after the timeout expired.  The message is taken from the bus.
+
+MT safe.
+</return>
+</function>
+
+
+<function name="gst_bus_timed_pop_filtered">
+<description>
+Get a message from the bus whose type matches the message type mask @types,
+waiting up to the specified timeout (and discarding any messages that do not
+match the mask provided).
+
+If @timeout is 0, this function behaves like gst_bus_pop_filtered(). If
+ timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a
+matching message was posted on the bus.
+
+
+</description>
+<parameters>
+<parameter name="bus">
+<parameter_description> a #GstBus to pop from
+</parameter_description>
+</parameter>
+<parameter name="timeout">
+<parameter_description> a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever
+</parameter_description>
+</parameter>
+<parameter name="types">
+<parameter_description> message types to take into account, GST_MESSAGE_ANY for any type
+</parameter_description>
+</parameter>
+</parameters>
+<return> a #GstMessage matching the
+filter in @types, or %NULL if no matching message was found on
+the bus until the timeout expired. The message is taken from
+the bus.
+
+MT safe.
+</return>
+</function>
+
 </root>