FarsightStream

## FarsightStream FarsightStream — A object that represents and manages a single real-time audio/video stream. |

## Synopsis

                FarsightStream;
    enum        FarsightCandidateType;
    enum        FarsightNetworkProtocol;
                FarsightTransportInfo;
    enum        FarsightStreamDirection;
    enum        FarsightStreamState;
    enum        FarsightStreamError;
    enum        FarsightStreamDTMFEvent;
    void        farsight_stream_prepare_transports
                                                (FarsightStream *self);
    void        farsight_stream_add_remote_candidate
                                                (FarsightStream *self,
                                                 const GList *remote_candidate);
    GList*      farsight_stream_get_native_candidate
                                                (FarsightStream *self,
                                                 const gchar *candidate_id);
    const GList* farsight_stream_get_native_candidate_list
                                                (FarsightStream *self);
    void        farsight_stream_remove_remote_candidate
                                                (FarsightStream *self,
                                                 const gchar *remote_candidate_id);
    void        farsight_stream_set_remote_candidate_list
                                                (FarsightStream *self,
                                                 const GList *remote_candidates);
    gboolean    farsight_stream_set_active_candidate_pair
                                                (FarsightStream *self,
                                                 const gchar *native_candidate_id,
                                                 const gchar *remote_candidate_id);
    void        farsight_stream_set_remote_codecs
                                                (FarsightStream *self,
                                                 const GList *codecs);
    gint        farsight_stream_get_active_codec
                                                (FarsightStream *self);
    void        farsight_stream_set_active_codec
                                                (FarsightStream *self,
                                                 gint id);
    void        farsight_stream_set_codec_preference_list
                                                (FarsightStream *self,
                                                 FarsightCodecPreference codec_pref[]);
    const GList* farsight_stream_get_local_codecs
                                                (FarsightStream *self);
    GList*      farsight_stream_get_codec_intersection
                                                (FarsightStream *self);
    gboolean    farsight_stream_set_sink        (FarsightStream *self,
                                                 GstElement *sink);
    GstElement* farsight_stream_get_sink        (FarsightStream *self);
    gboolean    farsight_stream_set_sink_filter (FarsightStream *self,
                                                 GstCaps *filter);
    gboolean    farsight_stream_set_source      (FarsightStream *self,
                                                 GstElement *source);
    GstElement* farsight_stream_get_source      (FarsightStream *self);
    gboolean    farsight_stream_set_source_filter
                                                (FarsightStream *self,
                                                 GstCaps *filter);
    GstElement* farsight_stream_get_pipeline    (FarsightStream *self);
    gboolean    farsight_stream_set_pipeline    (FarsightStream *self,
                                                 GstElement *pipeline);
    FarsightMediaType farsight_stream_get_media_type
                                                (FarsightStream *self);
    gboolean    farsight_stream_start           (FarsightStream *self);
    void        farsight_stream_stop            (FarsightStream *self);
    FarsightStreamDirection farsight_stream_get_direction
                                                (FarsightStream *self);
    FarsightStreamState farsight_stream_get_state
                                                (FarsightStream *self);
    void        farsight_stream_signal_error    (FarsightStream *self,
                                                 FarsightStreamError err,
                                                 const gchar *mesg);
    void        farsight_stream_signal_native_candidates_prepared
                                                (FarsightStream *self);
    void        farsight_stream_signal_new_active_candidate_pair
                                                (FarsightStream *self,
                                                 const gchar *native_candidate_id,
                                                 const gchar *remote_candidate_id);
    void        farsight_stream_signal_new_native_candidate
                                                (FarsightStream *self,
                                                 const gchar *candidate_id);
    void        farsight_stream_signal_codec_changed
                                                (FarsightStream *self,
                                                 int codec_id);
    void        farsight_stream_signal_state_changed
                                                (FarsightStream *self,
                                                 FarsightStreamState state,
                                                 FarsightStreamDirection direction);
    gboolean    farsight_stream_start_telephony_event
                                                (FarsightStream *self,
                                                 guint8 ev,
                                                 guint8 volume);
    gboolean    farsight_stream_stop_telephony_event
                                                (FarsightStream *self);

## Object Hierarchy

      GObject
       +----FarsightStream

## Properties

      "direction"            guint                 : Read / Write / Construct Only
      "media-type"           guint                 : Read / Write / Construct Only

## Signals

    "codec-changed"
                void        user_function      (FarsightStream *self,
                                                gint            codec_id,
                                                gpointer        user_data)      : Run last
    "error"     void        user_function      (FarsightStream *self,
                                                gint            type,
                                                gchar          *message,
                                                gpointer        user_data)      : Run last
    "native-candidates-prepared"
                void        user_function      (FarsightStream *self,
                                                gpointer        user_data)      : Run last
    "new-active-candidate-pair"
                void        user_function      (FarsightStream *self,
                                                gchar          *native_candidate_id,
                                                gchar          *remote_candidate_id,
                                                gpointer        user_data)                : Run last
    "new-native-candidate"
                void        user_function      (FarsightStream *self,
                                                gchar          *candidate_id,
                                                gpointer        user_data)         : Run last
    "sink-pad-ready"
                void        user_function      (FarsightStream *self,
                                                gpointer        pad,
                                                gpointer        user_data)      : Run last
    "state-changed"
                void        user_function      (FarsightStream *self,
                                                gint            state,
                                                gint            direction,
                                                gpointer        user_data)      : Run last

## Description

## Details

### FarsightStream

    typedef struct _FarsightStream FarsightStream;

A object that represents and manages a single real-time audio/video stream.

### enum FarsightCandidateType

    typedef enum
    {
      FARSIGHT_CANDIDATE_TYPE_LOCAL,   /* A local address */
      FARSIGHT_CANDIDATE_TYPE_DERIVED, /* An address derived by some method such as
                                        * STUN which should reach the local client
                                        */
      FARSIGHT_CANDIDATE_TYPE_RELAY    /* An external stream relay */
    } FarsightCandidateType;

An enum for the type of candidate used/reported

`FARSIGHT_CANDIDATE_TYPE_LOCAL` | A local address
`FARSIGHT_CANDIDATE_TYPE_DERIVED` | An address derived by some method such as STUN which should reach the local client
`FARSIGHT_CANDIDATE_TYPE_RELAY` | An external stream relay

### enum FarsightNetworkProtocol

    typedef enum
    {
      FARSIGHT_NETWORK_PROTOCOL_UDP,
      FARSIGHT_NETWORK_PROTOCOL_TCP
    } FarsightNetworkProtocol;

An enum for the base IP protocol used for a FarsightStream

`FARSIGHT_NETWORK_PROTOCOL_UDP` | A UDP based protocol
`FARSIGHT_NETWORK_PROTOCOL_TCP` | A TCP based protocol

### FarsightTransportInfo

    typedef struct {
      const gchar *candidate_id;
      guint component;
      const gchar *ip;
      guint16 port;
      FarsightNetworkProtocol proto;
      const gchar *proto_subtype;
      const gchar *proto_profile;
      float preference;
      FarsightCandidateType type;
      const gchar *username;
      const gchar *password;
    } FarsightTransportInfo;

Struct to hold information about a possible stream network transport.

const gchar *`candidate_id`; | string identifier of the candidate of which this transport is a part.
guint `component`; | number indicating which component of the candidate is formed by this transport
const gchar *`ip`; | IP in dotted format
guint16 `port`; | Port to use
FarsightNetworkProtocol `proto`; | FarsightNetworkProtocol for ip protocol to use as transport
const gchar *`proto_subtype`; | a string specifying subtype of this protocol type if needed
const gchar *`proto_profile`; | a string specifying a profile type for this protocol, if applicable
float `preference`; | Value between
FarsightCandidateType `type`; | Type of candidate
const gchar *`username`; | Username to use to connect to client if necessary, NULL otherwise
const gchar *`password`; | Username to use to connect to client if necessary, NULL otherwise

### enum FarsightStreamDirection

    typedef enum
    {
      FARSIGHT_STREAM_DIRECTION_NONE,
      FARSIGHT_STREAM_DIRECTION_SENDONLY,
      FARSIGHT_STREAM_DIRECTION_RECEIVEONLY,
      FARSIGHT_STREAM_DIRECTION_BOTH,
      FARSIGHT_STREAM_DIRECTION_LAST
    } FarsightStreamDirection;

Enum for the direction of a FarsightStream

`FARSIGHT_STREAM_DIRECTION_NONE` | No stream direction defined.
`FARSIGHT_STREAM_DIRECTION_SENDONLY` | Stream only sends to the other client.
`FARSIGHT_STREAM_DIRECTION_RECEIVEONLY` | Stream only recives from the other client
`FARSIGHT_STREAM_DIRECTION_BOTH` | Stream is bidirectional.
`FARSIGHT_STREAM_DIRECTION_LAST` |

### enum FarsightStreamState

    typedef enum
    {
      FARSIGHT_STREAM_STATE_DISCONNECTED,
      FARSIGHT_STREAM_STATE_CONNECTING,
      FARSIGHT_STREAM_STATE_CONNECTED
    } FarsightStreamState;

An enum used to signal the state of a FarsightStream

`FARSIGHT_STREAM_STATE_DISCONNECTED` | The stream is not connected
`FARSIGHT_STREAM_STATE_CONNECTING` | The stream is trying to establish a connection
`FARSIGHT_STREAM_STATE_CONNECTED` | The stream is connected and can start streaming.

### enum FarsightStreamError

    typedef enum
    {
      FARSIGHT_STREAM_ERROR_EOS,
      FARSIGHT_STREAM_UNKNOWN_ERROR,
      FARSIGHT_STREAM_ERROR_UNKNOWN = FARSIGHT_STREAM_UNKNOWN_ERROR,
      FARSIGHT_STREAM_ERROR_TIMEOUT,
      FARSIGHT_STREAM_ERROR_NETWORK,
      FARSIGHT_STREAM_ERROR_PIPELINE_SETUP,
      FARSIGHT_STREAM_ERROR_RESOURCE,
      FARSIGHT_STREAM_ERROR_LAST = FARSIGHT_STREAM_ERROR_RESOURCE
    } FarsightStreamError;

An enum used to signal errors that occur on a FarsightStream

`FARSIGHT_STREAM_ERROR_EOS` | The stream was erronously ended
`FARSIGHT_STREAM_UNKNOWN_ERROR` | An unknown error has occured (depricated)
`FARSIGHT_STREAM_ERROR_UNKNOWN` | An unknown error has occured
`FARSIGHT_STREAM_ERROR_TIMEOUT` | Timed out on attempt to establish a connection
`FARSIGHT_STREAM_ERROR_NETWORK` | A network error has occured
`FARSIGHT_STREAM_ERROR_PIPELINE_SETUP` | An error has occured while setting up the required pipeline
`FARSIGHT_STREAM_ERROR_RESOURCE` | An error has occured on a required resource
`FARSIGHT_STREAM_ERROR_LAST` |

### enum FarsightStreamDTMFEvent

    typedef enum
    {
      FARSIGHT_DTMF_EVENT_0 = 0,
      FARSIGHT_DTMF_EVENT_1 = 1,
      FARSIGHT_DTMF_EVENT_2 = 2,
      FARSIGHT_DTMF_EVENT_3 = 3,
      FARSIGHT_DTMF_EVENT_4 = 4,
      FARSIGHT_DTMF_EVENT_5 = 5,
      FARSIGHT_DTMF_EVENT_6 = 6,
      FARSIGHT_DTMF_EVENT_7 = 7,
      FARSIGHT_DTMF_EVENT_8 = 8,
      FARSIGHT_DTMF_EVENT_9 = 9,
      FARSIGHT_DTMF_EVENT_STAR = 10,
      FARSIGHT_DTMF_EVENT_POUND = 11,
      FARSIGHT_DTMF_EVENT_A = 12,
      FARSIGHT_DTMF_EVENT_B = 13,
      FARSIGHT_DTMF_EVENT_C = 14,
      FARSIGHT_DTMF_EVENT_D = 15
    } FarsightStreamDTMFEvent;

An enum that represents the different DTMF event that can be sent to a FarsightStream. The values corresponds those those defined in RFC 4733 The rest of the possibles values are in the IANA registry at: http://www.iana.org/assignments/audio-telephone-event-registry

### farsight_stream_prepare_transports ()

    void        farsight_stream_prepare_transports
                                                (FarsightStream *self);

Prepare a stream for connection. This function should enumerate local interfaces, open any ports and determine external ip/ports (STUN), start relay server (TURN).

It should also set a callback function for taking appropriate action when a new local interface has been detected by connecting to signal new-native-candiate.

`self` : | a FarsightStream

### farsight_stream_add_remote_candidate ()

    void        farsight_stream_add_remote_candidate
                                                (FarsightStream *self,
                                                 const GList *remote_candidate);

Adds the given list of transports (forming one candidate) to the list of remote candidates

`self` : | a FarsightStream
`remote_candidate` : | a GList of FarsightTransportInfo

### farsight_stream_get_native_candidate ()

    GList*      farsight_stream_get_native_candidate
                                                (FarsightStream *self,
                                                 const gchar *candidate_id);

Returns a specific native candidate

`self` : | a FarsightStream
`candidate_id` : | a string indicating the candidate id
Returns : | a GList of FarsightTransportInfo for the given native candidate. This GList must be freed using farsight_transport_list_destroy when not needed anymore.

### farsight_stream_get_native_candidate_list ()

    const GList* farsight_stream_get_native_candidate_list
                                                (FarsightStream *self);

Get list of native candidates for this stream

`self` : | a FarsightStream
Returns : | GList of FarsightTransportInfo

### farsight_stream_remove_remote_candidate ()

    void        farsight_stream_remove_remote_candidate
                                                (FarsightStream *self,
                                                 const gchar *remote_candidate_id);

Removes the given remote candidate from the remote candidate list

`self` : | a FarsightStream
`remote_candidate_id` : | a string representing a remote candidate id

### farsight_stream_set_remote_candidate_list ()

    void        farsight_stream_set_remote_candidate_list
                                                (FarsightStream *self,
                                                 const GList *remote_candidates);

Sets a list of remote candidates

`self` : | a FarsightStream
`remote_candidates` : | a GList of FarsightTransportInfo

### farsight_stream_set_active_candidate_pair ()

    gboolean    farsight_stream_set_active_candidate_pair
                                                (FarsightStream *self,
                                                 const gchar *native_candidate_id,
                                                 const gchar *remote_candidate_id);

Sets the given candidate pair as the active candidate pair, and emits the "new-active-candidate-pair" signal.

`self` : | a FarsightStream
`native_candidate_id` : | a string representing a native candidate id
`remote_candidate_id` : | a string representing a remote candidate id
Returns : | TRUE if sucessfully set the active candidate pair

### farsight_stream_set_remote_codecs ()

    void        farsight_stream_set_remote_codecs
                                                (FarsightStream *self,
                                                 const GList *codecs);

Set the selection of codecs that the remote end claims to understand

`self` : | a FarsightStream
`codecs` : | GList of FarsightCodec

### farsight_stream_get_active_codec ()

    gint        farsight_stream_get_active_codec
                                                (FarsightStream *self);

Get the codec to use for this stream.

`self` : | a FarsightStream
Returns : | the id of the codec currently in use, -1 if unset

### farsight_stream_set_active_codec ()

    void        farsight_stream_set_active_codec
                                                (FarsightStream *self,
                                                 gint id);

Set the codec to use for this stream. There should now be enough information to build the pipeline.

`self` : | a FarsightStream
`id` : | id of codec to use

### farsight_stream_set_codec_preference_list ()

    void        farsight_stream_set_codec_preference_list
                                                (FarsightStream *self,
                                                 FarsightCodecPreference codec_pref[]);

Set a list of prefered codecs (optional)

`self` : | a FarsightStream
`codec_pref` : | an array of FarsightCodecPreference

### farsight_stream_get_local_codecs ()

    const GList* farsight_stream_get_local_codecs
                                                (FarsightStream *self);

Get the selection of local codec ids to restrict this stream to using

`self` : | a FarsightStream
Returns : | : a GList of codec ids

### farsight_stream_get_codec_intersection ()

    GList*      farsight_stream_get_codec_intersection
                                                (FarsightStream *self);

Get the intersection of local and remote codecs.

`self` : | a FarsightStream
Returns : | a GList of FarsightCodec. The caller is responsible for freeing the list and individual items when it's done with it.

### farsight_stream_set_sink ()

    gboolean    farsight_stream_set_sink        (FarsightStream *self,
                                                 GstElement *sink);

Set the GStreamer sink for this stream. If sink is NULL it will block the incoming stream and remove the old sink. If called with a new sink it will replace the old one. If there is a user specified pipeline, the sink won't be added into the Farsight bin.

`self` : | a FarsightStream
`sink` : | a GstElement to use as the sink
Returns : | TRUE if sucessful

### farsight_stream_get_sink ()

    GstElement* farsight_stream_get_sink        (FarsightStream *self);

Get the GStreamer sink for this stream

`self` : | a FarsightStream
Returns : | A GstElement for the current stream sink

### farsight_stream_set_sink_filter ()

    gboolean    farsight_stream_set_sink_filter (FarsightStream *self,
                                                 GstCaps *filter);

Set the GStreamer sink link filter for this stream

`self` : | a FarsightStream
`filter` : | a GstCaps to use as a filter
Returns : | TRUE if sucessful

### farsight_stream_set_source ()

    gboolean    farsight_stream_set_source      (FarsightStream *self,
                                                 GstElement *source);

Set the GStreamer source for this stream. If the element does not have a parent, it will be added into the Farsight stream bin. So if you need to set a parent for the source, do it before calling this function.

`self` : | a FarsightStream
`source` : | a GstElement to use as the source
Returns : | TRUE if sucessful

### farsight_stream_get_source ()

    GstElement* farsight_stream_get_source      (FarsightStream *self);

Get the GStreamer source for this stream

`self` : | a FarsightStream
Returns : | A GstElement for the current stream source

### farsight_stream_set_source_filter ()

    gboolean    farsight_stream_set_source_filter
                                                (FarsightStream *self,
                                                 GstCaps *filter);

Set the GStreamer source link filter for this stream

`self` : | a FarsightStream
`filter` : | a GstCaps to use as a filter
Returns : | TRUE if sucessful

### farsight_stream_get_pipeline ()

    GstElement* farsight_stream_get_pipeline    (FarsightStream *self);

Get the FarsightStream working pipeline. This will return the pipeline set by the user or the pipeline created by Farsight if not set by the user.

`self` : | a FarsightStream
Returns : | GstElement or NULL if pipeline not available yet

### farsight_stream_set_pipeline ()

    gboolean    farsight_stream_set_pipeline    (FarsightStream *self,
                                                 GstElement *pipeline);

This function is used if the user wants to create the GstPipeline himself. This means Farsight will use this pipeline instead of creating it's own. It will create a GstBin and insert it into the given pipeline. This is usefull when the user wants all the different Farsight streams to be part of the same global pipeline (i.e. Tee the same source to various streams) If the pipeline is set by the user, the sources will not be added into the Farsight bin.

NOTE: This has to be called before `farsight_stream_prepare_transports()` in order to be used.

`self` : | a FarsightStream
`pipeline` : | a GstElement that is a pipeline
Returns : | TRUE if successful

### farsight_stream_get_media_type ()

    FarsightMediaType farsight_stream_get_media_type
                                                (FarsightStream *self);

Get the FarsightStream direction

`self` : | a FarsightStream
Returns : | FarsightMediaType media type

### farsight_stream_start ()

    gboolean    farsight_stream_start           (FarsightStream *self);

Start the FarsightStream streaming to the network

`self` : | a FarsightStream
Returns : | TRUE if sucessful

### farsight_stream_stop ()

    void        farsight_stream_stop            (FarsightStream *self);

Stop the FarsightStream streaming to the network

`self` : | a FarsightStream

### farsight_stream_get_direction ()

    FarsightStreamDirection farsight_stream_get_direction
                                                (FarsightStream *self);

Get the FarsightStream direction

`self` : | a FarsightStream
Returns : | FarsightStreamState direction

### farsight_stream_get_state ()

    FarsightStreamState farsight_stream_get_state
                                                (FarsightStream *self);

Get the current FarsightStream state

`self` : | a FarsightStream
Returns : | FarsightStreamState state

### farsight_stream_signal_error ()

    void        farsight_stream_signal_error    (FarsightStream *self,
                                                 FarsightStreamError err,
                                                 const gchar *mesg);

Used by subclasses of FarsightStream to emit an error signal

`self` : | a FarsightStream
`err` : | FarsightStreamError value
`mesg` : | a string

### farsight_stream_signal_native_candidates_prepared ()

    void        farsight_stream_signal_native_candidates_prepared
                                                (FarsightStream *self);

Used by subclasses of FarsightStream to emit an native-candidates-prepared signal

`self` : | a FarsightStream

### farsight_stream_signal_new_active_candidate_pair ()

    void        farsight_stream_signal_new_active_candidate_pair
                                                (FarsightStream *self,
                                                 const gchar *native_candidate_id,
                                                 const gchar *remote_candidate_id);

Used by subclasses of FarsightStream to emit an new-active-candidate-pair signal

`self` : | a FarsightStream
`native_candidate_id` : | string identifier of native candidate that is now active
`remote_candidate_id` : | string identifier of remote candidate that is now active

### farsight_stream_signal_new_native_candidate ()

    void        farsight_stream_signal_new_native_candidate
                                                (FarsightStream *self,
                                                 const gchar *candidate_id);

Used by subclasses of FarsightStream to emit an new-native-candidate signal

`self` : | a FarsightStream
`candidate_id` : | Identifier of newly discovered native candidate

### farsight_stream_signal_codec_changed ()

    void        farsight_stream_signal_codec_changed
                                                (FarsightStream *self,
                                                 int codec_id);

Used by subclasses of FarsightStream to emit an codec-changed signal

`self` : | a FarsightStream
`codec_id` : | id of new codec in use

### farsight_stream_signal_state_changed ()

    void        farsight_stream_signal_state_changed
                                                (FarsightStream *self,
                                                 FarsightStreamState state,
                                                 FarsightStreamDirection direction);

Used by subclasses of FarsightStream to emit an state-changed signal

`self` : | a FarsightStream
`state` : | FarsightStreamState of new state
`direction` : | FarsightStreamDirection for directions in

### farsight_stream_start_telephony_event ()

    gboolean    farsight_stream_start_telephony_event
                                                (FarsightStream *self,
                                                 guint8 ev,
                                                 guint8 volume);

This function will start sending a telephony event (such as a DTMF tone) on the FarsightStream, you have to call the function `farsight_stream_stop_telephony_event()` to stop it.

`self` : | a FarsightStream
`ev` : | A FarsightStreamDTMFEvent or another number defined at http://www.iana.org/assignments/audio-telephone-event-registry
`volume` : | The volume in dBm0 without the negative sign. Should be between 0 and 36. Higher values mean lower volume
Returns : | TRUE if sucessful, it can return FALSE if the FarsightStream does not support this telephony event.

### farsight_stream_stop_telephony_event ()

    gboolean    farsight_stream_stop_telephony_event
                                                (FarsightStream *self);

This function will stop sending a telephony event started by `farsight_stream_start_telephony_event()`. If the event was being sent for less than 50ms, it will be sent for 50ms minimum. If the duration was a positive and the event is not over, it will cut it short.

`self` : | a FarsightStream
Returns : | TRUE if sucessful, it can return FALSE if the FarsightStream does not support telephony events or if no telephony event is being sent

## Property Details

### The "`direction`" property

      "direction"            guint                 : Read / Write / Construct Only

The direction of this stream. This should only be set at stream creation time.

Allowed values: <= 4

Default value: 3

### The "`media-type`" property

      "media-type"           guint                 : Read / Write / Construct Only

The media type to be used by this stream specifed by FarsightMediaType.

Allowed values: <= 1

Default value: 0

## Signal Details

### The "codec-changed" signal

    void        user_function                  (FarsightStream *self,
                                                gint            codec_id,
                                                gpointer        user_data)      : Run last

emitted if we automatically choose a new codec for some reason (e.g. high packet loss)

`self` : | FarsightStream that emitted the signal
`codec_id` : | id of codec to be used
`user_data` : | user data set when the signal handler was connected.

### The "error" signal

    void        user_function                  (FarsightStream *self,
                                                gint            type,
                                                gchar          *message,
                                                gpointer        user_data)      : Run last

This signal is emitted in any error condition

`self` : | FarsightStream that emmitted the signal
`type` : | FarsightStreamError type of error
`message` : | Error message
`user_data` : | user data set when the signal handler was connected.

### The "native-candidates-prepared" signal

    void        user_function                  (FarsightStream *self,
                                                gpointer        user_data)      : Run last

This signal is emitted when the native candidates have been prepared. This usually means all of the local ports have been opened, local interfaces have been found, and/or external ports have been found, and/or relay server has been setup, or anything else the protocol needs. After emission of this signal, farsight_stream_get_native_candidate_list should return meaningful data

`self` : | FarsightStream that emmitted the signal
`user_data` : | user data set when the signal handler was connected.

### The "new-active-candidate-pair" signal

    void        user_function                  (FarsightStream *self,
                                                gchar          *native_candidate_id,
                                                gchar          *remote_candidate_id,
                                                gpointer        user_data)                : Run last

Emitted when this FarsightStream has chosen a new active candidate pair to use to connect to the remote client.

`self` : | FarsightStream that emmitted the signal
`native_candidate_id` : | string identifier for native side of the candidate pair
`remote_candidate_id` : | string identifier for remote side of the candidate pair
`user_data` : | user data set when the signal handler was connected.

### The "new-native-candidate" signal

    void        user_function                  (FarsightStream *self,
                                                gchar          *candidate_id,
                                                gpointer        user_data)         : Run last

This signal is emitted when the a new native candidate is found. After emission of this signal, farsight_stream_get_native_candidates should return meaningful data. This does not mean that the candidate has been prepared.

`self` : | FarsightStream that emmitted the signal
`candidate_id` : | id of the found candidate
`user_data` : | user data set when the signal handler was connected.

### The "sink-pad-ready" signal

    void        user_function                  (FarsightStream *self,
                                                gpointer        pad,
                                                gpointer        user_data)      : Run last

This signal is emitted when a sink pad has been created on the Farsight stream bin.

Note : This signal is only valid when a user-defined pipeline has been provided by the user to farsight using farsight_stream_set_pipeline.

`self` : | FarsightStream that emmitted the signal
`pad` : | A GstPad that represents the sink
`user_data` : | user data set when the signal handler was connected.

### The "state-changed" signal

    void        user_function                  (FarsightStream *self,
                                                gint            state,
                                                gint            direction,
                                                gpointer        user_data)      : Run last

This signal is emitted when we change FarsightStreamState.

`self` : | FarsightStream that emmitted the signal
`state` : | FarsightStreamState of new state
`direction` : | FarsightStreamDirection for directions in which the stream is streaming
`user_data` : | user data set when the signal handler was connected.