<chapter id="chapter-links-api">
  <title>Linking elements</title>
  <sect1 id="section-link-basic">
   <title>Making simple links</title>
   <para> 
     You can link two pads with:
   </para>
   <programlisting>
 GstPad *srcpad, *sinkpad;

 srcpad = gst_element_get_pad (element1, "src");
 sinpad = gst_element_get_pad (element2, "sink");

 // link them
 gst_pad_link (srcpad, sinkpad);
   ....
 // and unlink them
 gst_pad_unlink (srcpad, sinkpad);

  </programlisting>
   <para> 
     A convenient shortcut for the above code is done with the gst_element_link_pads ()
     function:
   </para>
  <programlisting>

 // link them
 gst_element_link_pads (element1, "src", element2, "sink");
   ....
 // and unlink them
 gst_element_unlink_pads (element1, "src", element2, "sink");

  </programlisting>
   <para>
     An even more convenient shortcut but only works for single-source, single-sink elements is the
     gst_element_link () function:
   </para>
  <programlisting>

 // link them
 gst_element_link (element1, element2);
   ....
 // and unlink them
 gst_element_unlink (element1, element2);

  </programlisting>
   <para>
     If you have more than one element to link, the gst_element_link_many () function takes
     a NULL-terminated list of elements.  Again this only works for single-source single-sink
     elements:
   </para>
  <programlisting>

 // link them
 gst_element_link_many (element1, element2, element3, element4, NULL);
   ....
 // and unlink them
 gst_element_unlink_many (element1, element2, element3, element4, NULL);

  </programlisting>
   <para> 
     You can query if a pad is linked with
     <function>GST_PAD_IS_LINKED (pad)</function>. 
   </para>
   <para> 
     To query for the <ulink type="http"
     url="../../gstreamer/html/GstPad.html"><classname>GstPad</classname></ulink>
     a pad is linked to, use <function>gst_pad_get_peer (pad)</function>.
   </para>
  </sect1>

  <sect1 id="section-link-filtered">
   <title>Making filtered links</title>
    <para>
      You can also force a specific media type on the link by using
      <function>gst_pad_link_filtered ()</function>
      and <function>gst_element_link_filtered ()</function> with capabilities.
      See <xref linkend="section-caps"/> for
      an explanation of capabilities.
    </para>
  </sect1>

</chapter>