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

enum FarsightNetworkProtocol

typedef enum
{
  FARSIGHT_NETWORK_PROTOCOL_UDP,
  FARSIGHT_NETWORK_PROTOCOL_TCP
} FarsightNetworkProtocol;

An enum for the base IP protocol used for a FarsightStream

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.

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

enum FarsightStreamState

typedef enum
{
  FARSIGHT_STREAM_STATE_STOPPED,
  FARSIGHT_STREAM_STATE_PLAYING,
  FARSIGHT_STREAM_STATE_CONNECTING,
  FARSIGHT_STREAM_STATE_CONNECTED
} FarsightStreamState;

An enum used to signal the state of a FarsightStream

enum FarsightStreamError

typedef enum
{
  FARSIGHT_STREAM_ERROR_EOS,
  FARSIGHT_STREAM_UNKNOWN_ERROR,
  FARSIGHT_STREAM_LAST_ERROR = FARSIGHT_STREAM_UNKNOWN_ERROR
} FarsightStreamError;

An enum used to signal errors that occur on a FarsightStream

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.

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

farsight_stream_get_native_candidate ()

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

Returns a specific native candidate

farsight_stream_get_native_candidate_list ()

const GList* farsight_stream_get_native_candidate_list
                                            (FarsightStream *self);

Get list of native candidates for this stream

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

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

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.

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

farsight_stream_get_active_codec ()

gint        farsight_stream_get_active_codec
                                            (FarsightStream *self);

Get the codec to use for this stream.

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.

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)

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

farsight_stream_get_codec_intersection ()

GList*      farsight_stream_get_codec_intersection
                                            (FarsightStream *self);

Get the intersection of local and remote codecs.

farsight_stream_set_sink ()

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

Set the GStreamer sink for this stream

farsight_stream_get_sink ()

GstElement* farsight_stream_get_sink        (FarsightStream *self);

Get the GStreamer sink for this stream

farsight_stream_set_source ()

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

Set the GStreamer source for this stream

farsight_stream_get_source ()

GstElement* farsight_stream_get_source      (FarsightStream *self);

Get the GStreamer source for this stream

farsight_stream_start ()

gboolean    farsight_stream_start           (FarsightStream *self);

Start the FarsightStream streaming to the network

farsight_stream_stop ()

void        farsight_stream_stop            (FarsightStream *self);

Stop the FarsightStream streaming to the network

farsight_stream_get_direction ()

FarsightStreamDirection farsight_stream_get_direction
                                            (FarsightStream *self);

Get the FarsightStream direction

farsight_stream_get_state ()

FarsightStreamState farsight_stream_get_state
                                            (FarsightStream *self);

Get the current FarsightStream 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

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

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

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

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

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

The "direction" property

  "direction"            guint                 : Read / Write / Construct Only

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

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

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)

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

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

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.

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.

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.