![]() |
![]() |
![]() |
Farsight Reference Manual | ![]() |
---|---|---|---|---|
FarsightStreamFarsightStream — A object that represents and manages a single real-time audio/video stream. |
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);
"direction" guint : Read / Write / Construct Only "media-type" guint : Read / Write / Construct Only
"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
typedef struct _FarsightStream FarsightStream;
A object that represents and manages a single real-time audio/video stream.
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
typedef enum { FARSIGHT_NETWORK_PROTOCOL_UDP, FARSIGHT_NETWORK_PROTOCOL_TCP } FarsightNetworkProtocol;
An enum for the base IP protocol used for a FarsightStream
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 |
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
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
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
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 |
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 |
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. |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
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 |
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 |
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 |
gboolean farsight_stream_start (FarsightStream *self);
Start the FarsightStream streaming to the network
self : |
a FarsightStream |
Returns : | TRUE if sucessful |
void farsight_stream_stop (FarsightStream *self);
Stop the FarsightStream streaming to the network
self : |
a FarsightStream |
FarsightStreamDirection farsight_stream_get_direction (FarsightStream *self);
Get the FarsightStream direction
self : |
a FarsightStream |
Returns : | FarsightStreamState direction |
FarsightStreamState farsight_stream_get_state (FarsightStream *self);
Get the current FarsightStream state
self : |
a FarsightStream |
Returns : | FarsightStreamState state |
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 |
void farsight_stream_signal_native_candidates_prepared (FarsightStream *self);
Used by subclasses of FarsightStream to emit an native-candidates-prepared signal
self : |
a FarsightStream |
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 |
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 |
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 |
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 |
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
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
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. |
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. |
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. |
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. |
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. |
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. |