Here is a sequence diagram of a standard client interaction with the
Farsight API:


Client
   | session_factory_make
   |------------>FarsightSession
   |                    |
   | list_supported_codecs
   |------------------->|
   |<- - - - - - - - - -|
   |                    |
   | create_stream      |
   |------------------->|
   |                    |--------------> FarsightStream
   |                    |                       |
   |<- - - - - - - - - -|                       |
   |                    X                       |
   | set_source                                 |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | set_sink                                   |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | set_remote_candidate_list                  |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
(
optional
   |                                            |
   | add_remote_candidate                       |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | remove_remote_candidate                    |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | prepare_transports                         |
   |------------------------------------------->|  [ open port, enumerate local
                                                   interfaces, determine
                                                   external ip/ports (if), start
                                                   relay server (if). This
                                                   process has to keep listening
                                                   forever for new local
                                                   interfaces ]
   |                                            |
   |                      new-native-candidate  |
   |<-------------------------------------------|
   |                                            |
   |                native-candidates-prepared  |
   |<-------------------------------------------|
   |                                            |
(
optional
   |                                            |
   | get_native_candidate_list                  |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | get_native_candidate                       |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
)
   |                                            |
   | set_active_candidate_pair                  |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
)
   |                                            | [ Start state machine for the
                                                    transport candidates, if one
                                                    of them is a relay server,
                                                    we might want to set that
                                                    immediatly as the active
                                                    candiate with
                                                    set_active_candidate_pair()
                                                    Setting the active candidate
                                                    pair should inform the
                                                    plugin to place it at the
                                                    top of the candidate-pair
                                                    list ]
   |                                            |
   |                                            |
   | start_candidate_validation                 |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | stop_candidate_validation                  |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   |                  new-active-candidate-pair | [ 1..n times ]
   |<-------------------------------------------|
   |                                            |
   | codec-changed                              |
   |<-------------------------------------------|

(MAYBE
   |                                            |
   | set_codec_choice                           |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |                                            |
   | codec-changed                              |
   |<-------------------------------------------|
)
   |                                            |
   | state-changed(PLAYING,SENDING & RECEIVEING)|
   |<-------------------------------------------|
.....................................................
   |                                            |
   | stop                                       |
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|


FarsightStream States
---------------------
have source  {YES. NO}

have sink {YES, NO}

native transports {UNPREPARED, PREPARING, PREPARED}

have remote transport candidates  {YES, NO}

native and remote transports paired  {YES, NO}

made choice of remotes transports  {YES. NO}

have remotes choice of native transports {YES, NO}

have remotes codec list {YES, NO}

{PLAYING,STOPPED}

stream direction {SEND ONLY, RECEIVE ONLY, BOTH DIRECTIONS}

set of local codecs to use {FarsightCodecList}

current codec choice {id}

/** Useful sequence diagram drawing bits... */ 
   |                    |                       |
   |                                            |
   |<-------------------------------------------|
   |------------------------------------------->|
   |<- - - - - - - - - - - - - - - - - - - - - -|
   |------------------->|
   |<-------------------|
   |<- - - - - - - - - -|
