1 files changed, 72 insertions, 0 deletions
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>