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;
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_source      (FarsightStream *self,
                                             GstElement *source);
GstElement* farsight_stream_get_source      (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);

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
"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_STOPPED,
  FARSIGHT_STREAM_STATE_PLAYING,
  FARSIGHT_STREAM_STATE_CONNECTING,
  FARSIGHT_STREAM_STATE_CONNECTED
} FarsightStreamState;

An enum used to signal the state of a FarsightStream

FARSIGHT_STREAM_STATE_STOPPED The stream is stopped
FARSIGHT_STREAM_STATE_PLAYING The stream is playing
FARSIGHT_STREAM_STATE_CONNECTING The stream is in the process of being set up
FARSIGHT_STREAM_STATE_CONNECTED The stream is set up and ready to start playing

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_ERROR_EOS The stream was erronously ended
FARSIGHT_STREAM_UNKNOWN_ERROR An unknown error occured.
FARSIGHT_STREAM_LAST_ERROR

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

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_source ()

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

Set the GStreamer source for this stream

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_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

Property Details

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

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 "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.