$Id$

Currently its only save to link/unlink elements/pad when pipeline is in READY.
Belowe some thoughts. See http://bugzilla.gnome.org/show_bug.cgi?id=435487
for patches.

= current api =

gboolean gst_element_link   (GstElement *src, GstElement *dest);
void     gst_element_unlink (GstElement *src, GstElement *dest);

gst_element_link_many, gst_element_unlink_many, gst_element_link_filtered,
gst_element_link_pads, gst_element_unlink_pads, gst_element_link_pads_filtered

GstPadLinkReturn gst_pad_link (GstPad *srcpad, GstPad *sinkpad);
gboolean         gst_pad_unlink (GstPad *srcpad, GstPad *sinkpad);

= use cases =

== inserting an element ==

* we have: e1 ! e4
* we want: e1 ! e2 ! e3 ! e4
* we want: e1 ! e2      ! e4

gst_element_insert_linked(e1, e2, e3, e4); // e2 == e3 allowed
gst_pads_insert_link (e1.src, e2.sink, e3.src, e4.sink);
  disconnect e1.src, e1.src.peer
  disconnect e4.sink, e4.sink.peer
  connect e1.src, e2.sink
  connect e3.src, e4.sink

== removing an element ==

* we have: e1 ! e2 ! e3
* we want: e1 ! e3

gst_element_remove_linked(e2);
gst_pads_remove_link (e1.src, e3.sink);
  disconnect e1.src, e1.src.peer
  disconnect e3.sink, e3.sink.peer
  connect e1.src, e3.sink

== swapping out an elelment ==

* we have: e1 ! e2 ! e6
* we have: e1 ! e2 ! e3 ! e6
* we want: e1 ! e4 ! e5 ! e6
* we want: e1 ! e3      ! e6

gst_element_swap_linked(e1, e4, e5, e6);
gst_pads_insert_link (e1.src, e4.sink, e5.src, e6.sink);
  disconnect e1.src, e1.src.peer (=e2.sink)
  disconnect e6.sink, e6.sink.peer
  connect e1.src, e4.sink
  connect e5.src, e6.sink

= thoughts =
* I don't think we need api for pads
* Should current api check for the state?
* do we want to swapp multiple elements at once

== events ==
* tee and adder need special treatment
  * both would need to cache an accumulated segment
  * tee
    * would also cache tags
    * when linkfunc is called, it can send out the segment and the tags
    * when all pads got unlinked it could clear the segment
  * adder
    * when linkfunc gets called it sends a seek-event

= ideas =
== dynlinkpoint ==
* use cases
  * its meant to be used with one side disconnected to allow to connect elements
    at runtime
  * it can be used in a pipeline to remove/insert elements at runtime
* element with 1 source- and 1 sinkpad
* when both connected it passes data through
* if src is not connected it drops received buffers
* if sink is not connected
  * it does not push
  * it creates silence on pull
* events
  * it caches events
    * down: newsegment, tags, buffersize
    * up: seek (needs to be modified)
  * when other-pad get connected it pushes events depending on direction