From 626fcb3707ffa9bcbaa96ac6cedf4fbc9e476dbc Mon Sep 17 00:00:00 2001
From: Wim Taymans <wim.taymans@collabora.co.uk>
Date: Tue, 16 Oct 2012 11:20:59 +0200
Subject: [PATCH] pwg: add section about query function

---
 docs/pwg/building-boiler.xml  | 10 ++++-
 docs/pwg/building-queryfn.xml | 72 +++++++++++++++++++++++++++++++++++
 docs/pwg/pwg.xml              |  2 +
 3 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 docs/pwg/building-queryfn.xml

diff --git a/docs/pwg/building-boiler.xml b/docs/pwg/building-boiler.xml
index 7cba279de7..77d78ce73f 100644
--- a/docs/pwg/building-boiler.xml
+++ b/docs/pwg/building-boiler.xml
@@ -378,6 +378,7 @@ gst_my_filter_init (GstMyFilter * filter)
       correct template would look like this:
     </para>
     <programlisting>
+<![CDATA[
 static GstStaticPadTemplate sink_factory =
 GST_STATIC_PAD_TEMPLATE (
   "sink",
@@ -390,6 +391,7 @@ GST_STATIC_PAD_TEMPLATE (
       "rate = (int) [ 8000, 96000 ]"
   )
 );
+]]>
     </programlisting>
     <para>
       Values surrounded by curly brackets (<quote>{</quote> and
@@ -428,7 +430,9 @@ GST_STATIC_PAD_TEMPLATE (
       Also, in this function, any supported element type in the plugin should
       be registered.
     </para>
-    <programlisting><!-- example-begin register.func -->
+    <programlisting>
+<!-- example-begin register.func -->
+<![CDATA[
 static gboolean
 plugin_init (GstPlugin *plugin)
 {
@@ -448,7 +452,9 @@ GST_PLUGIN_DEFINE (
   "GStreamer",
   "http://gstreamer.net/"
 )
-    <!-- example-end register.func --></programlisting>
+]]>
+<!-- example-end register.func -->
+    </programlisting>
     <para>
       Note that the information returned by the plugin_init() function will be
       cached in a central registry. For this reason, it is important that the
diff --git a/docs/pwg/building-queryfn.xml b/docs/pwg/building-queryfn.xml
new file mode 100644
index 0000000000..ad2e943a33
--- /dev/null
+++ b/docs/pwg/building-queryfn.xml
@@ -0,0 +1,72 @@
+
+<!-- ############ chapter ############# -->
+
+<chapter id="chapter-building-queryfn">
+  <title>The query function</title>
+  <para>
+    Through the query function, your element will receive queries that it
+    has to reply to. These are queries like position, duration but also
+    about the supported formats and scheduling modes your element supports.
+    Queries can travel both upstream and downstream, so you can receive them
+    on sink pads as well as source pads. 
+  </para>
+  <para>
+    Below follows a very simple query function that we install on the source
+    pad of our element.
+  </para>
+  <programlisting>
+<![CDATA[
+static gboolean gst_my_filter_src_query (GstPad    *pad,
+                                         GstObject *parent,
+                                         GstQuery  *query);
+
+[..]
+
+static void
+gst_my_filter_init (GstMyFilter * filter)
+{
+[..]
+  /* configure event function on the pad before adding
+   * the pad to the element */
+  gst_pad_set_event_function (filter->srcpad,
+      gst_my_filter_src_event);
+[..]
+}
+
+static gboolean
+gst_my_filter_src_query (GstPad    *pad,
+		         GstObject *parent,
+		         GstQuery  *query)
+{
+  gboolean ret;
+  GstMyFilter *filter = GST_MY_FILTER (parent);
+
+  switch (GST_QUERY_TYPE (query)) {
+    case GST_QUERY_POSITION:
+      /* we should report the current position */
+      [...]
+      break;
+    case GST_QUERY_DURATION:
+      /* we should report the duration here */
+      [...]
+      break;
+    case GST_QUERY_CAPS:
+      /* we should report the supported caps here */
+      [...]
+      break;
+    default:
+      /* just call the default handler */
+      ret = gst_pad_query_default (pad, parent, query);
+      break;
+  }
+  return ret;
+}
+]]>
+  </programlisting>
+  <para>
+    It is a good idea to call the default query handler
+    <function>gst_pad_query_default ()</function> for unknown queries.
+    Depending on the query type, the default handler will forward 
+    the query or simply unref it.
+  </para>
+</chapter>
diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml
index e504e50265..4f79709682 100644
--- a/docs/pwg/pwg.xml
+++ b/docs/pwg/pwg.xml
@@ -18,6 +18,7 @@
 <!ENTITY BUILDING_PADS        SYSTEM "building-pads.xml">
 <!ENTITY BUILDING_CHAINFN     SYSTEM "building-chainfn.xml">
 <!ENTITY BUILDING_EVENTFN     SYSTEM "building-eventfn.xml">
+<!ENTITY BUILDING_QUERYFN     SYSTEM "building-queryfn.xml">
 <!ENTITY BUILDING_STATE       SYSTEM "building-state.xml">
 <!ENTITY BUILDING_PROPS       SYSTEM "building-props.xml">
 <!ENTITY BUILDING_SIGNALS     SYSTEM "building-signals.xml">
@@ -120,6 +121,7 @@
     &BUILDING_PADS;
     &BUILDING_CHAINFN;
     &BUILDING_EVENTFN;
+    &BUILDING_QUERYFN;
     &BUILDING_STATE;
     &BUILDING_PROPS;
     &BUILDING_SIGNALS;