Top | ![]() |
![]() |
![]() |
![]() |
FarsightStreamFarsightStream — A object that represents and manages a single real-time audio/video stream. |
guint | direction | Read / Write / Construct Only |
guint | media-type | Read / Write / Construct Only |
void | codec-changed | Run Last |
void | error | Run Last |
void | native-candidates-prepared | Run Last |
void | new-active-candidate-pair | Run Last |
void | new-native-candidate | Run Last |
void | sink-pad-ready | Run Last |
void | state-changed | Run Last |
struct | FarsightStream |
enum | FarsightCandidateType |
enum | FarsightNetworkProtocol |
struct | FarsightTransportInfo |
enum | FarsightStreamDirection |
enum | FarsightStreamState |
enum | FarsightStreamError |
enum | FarsightStreamDTMFEvent |
enum | FarsightStreamDTMFMethod |
struct | FarsightStreamClass |
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.
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
GList * farsight_stream_get_native_candidate (FarsightStream *self
,const gchar *candidate_id
);
Returns a specific native candidate
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
void farsight_stream_remove_remote_candidate (FarsightStream *self
,const gchar *remote_candidate_id
);
Removes the given remote candidate from the remote candidate list
void farsight_stream_set_remote_candidate_list (FarsightStream *self
,const GList *remote_candidates
);
Sets a list of remote candidates
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.
gboolean farsight_stream_set_remote_codecs (FarsightStream *self
,const GList *codecs
);
Set the selection of codecs that the remote end claims to understand
gint
farsight_stream_get_active_codec (FarsightStream *self
);
Get the codec to use for this stream.
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.
void farsight_stream_set_codec_preference_list (FarsightStream *self
,const GArray *codec_pref
);
Set a list of prefered codecs (optional). Setting it to NULL will unset the list. A 0-length list is invalid.
const GList *
farsight_stream_get_local_codecs (FarsightStream *self
);
Get the selection of local codec ids to restrict this stream to using
Returns : a GList of codec ids
GList *
farsight_stream_get_codec_intersection
(FarsightStream *self
);
Get the intersection of local and remote codecs.
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. 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. This function will eat one reference to the element, if you want to keep a reference, make sure you have a second one. Any sink set with this function must be be in main pipeline if one has been set.
GstElement *
farsight_stream_get_sink (FarsightStream *self
);
Get the GStreamer sink for this stream This function will eat one reference to the element, if you want to keep a reference, make sure you have a second one.
gboolean farsight_stream_set_sink_filter (FarsightStream *self
,GstCaps *filter
);
Set the GStreamer sink link filter for this stream
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. This function will eat one reference to the element, if you want to keep a reference, make sure you have a second one. Any source set with this function must be be in main pipeline if one has been set.
GstElement *
farsight_stream_get_source (FarsightStream *self
);
Get the GStreamer source for this stream
gboolean farsight_stream_set_source_filter (FarsightStream *self
,GstCaps *filter
);
Set the GStreamer source link filter for this stream
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.
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. It must also be called before any call to
farsight_stream_set_source()
and farsight_stream_set_sink()
.
FarsightMediaType
farsight_stream_get_media_type (FarsightStream *self
);
Get the FarsightStream media type
gboolean
farsight_stream_start (FarsightStream *self
);
Start the FarsightStream streaming to the network
void
farsight_stream_stop (FarsightStream *self
);
Stop the FarsightStream streaming to the network
FarsightStreamDirection
farsight_stream_get_direction (FarsightStream *self
);
Get the FarsightStream requested direction
FarsightStreamDirection
farsight_stream_get_current_direction (FarsightStream *self
);
Get the FarsightStream current direction
FarsightStreamState
farsight_stream_get_state (FarsightStream *self
);
Get the current FarsightStream state
void farsight_stream_signal_error (FarsightStream *self
,FarsightStreamError err
,const gchar *mesg
);
Used by subclasses of FarsightStream to emit an
error signalvoid
farsight_stream_signal_native_candidates_prepared
(FarsightStream *self
);
Used by subclasses of FarsightStream to emit an
native-candidates-prepared signalvoid 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 signalvoid farsight_stream_signal_new_native_candidate (FarsightStream *self
,const gchar *candidate_id
);
Used by subclasses of FarsightStream to emit an
new-native-candidate signalvoid farsight_stream_signal_codec_changed (FarsightStream *self
,int codec_id
);
Used by subclasses of FarsightStream to emit an
codec-changed signalvoid farsight_stream_signal_state_changed (FarsightStream *self
,FarsightStreamState state
,FarsightStreamDirection direction
);
Used by subclasses of FarsightStream to emit an
state-changed signalself |
||
state |
FarsightStreamState of new state |
|
direction |
FarsightStreamDirection for directions in |
gboolean farsight_stream_set_sending (FarsightStream *self
,gboolean sending
);
This function will tell Farsight to stop sending. This will block the source pad that is given to Farsight.
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.
This function will use any available method, if you want to use a specific
method only, use farsight_stream_start_telephony_event_full()
self |
||
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 |
TRUE
if sucessful, it can return FALSE
if the FarsightStream
does not support this 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.
TRUE
if sucessful, it can return FALSE
if the FarsightStream
does not support telephony events or if no telephony event is being sent
gboolean farsight_stream_start_telephony_event_full (FarsightStream *self
,guint8 ev
,guint8 volume
,FarsightStreamDTMFMethod method
);
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_full()
to stop it.
self |
||
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 |
|
method |
The method used to send the event |
TRUE
if sucessful, it can return FALSE
if the FarsightStream
does not support this telephony event.
gboolean farsight_stream_stop_telephony_event_full (FarsightStream *self
,FarsightStreamDTMFMethod method
);
This function will stop sending a telephony event started by
farsight_stream_start_telephony_event_full()
. 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. The type parameters has to be the same type that was passed to
self |
||
method |
The method used to send the event, this MUST match the parameter
passed to |
TRUE
if sucessful, it can return FALSE
if the FarsightStream
does not support telephony events or if no telephony event is being sent
gboolean farsight_stream_preload_receive_pipeline (FarsightStream *self
,gint payload_type
);
This function will preload a codec instead of loading it when the first
codec arrives. It is particularly useful with DSP and other slow to load
and initialise codecs. It must be called after
farsight_stream_set_remote_codecs()
.
TRUE if sucessful, it can return FALSE if the FarsightStream is already receiving packets or if the codec can not be preloaded.
struct FarsightStream;
A object that represents and manages a single real-time audio/video stream.
struct FarsightTransportInfo { 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; };
Struct to hold information about a possible stream network transport.
string identifier of the candidate of which this transport is a part. |
||
number indicating which component of the candidate is formed by this transport |
||
IP in dotted format |
||
Port to use |
||
FarsightNetworkProtocol |
FarsightNetworkProtocol for ip protocol to use as transport |
|
a string specifying subtype of this protocol type if needed |
||
a string specifying a profile type for this protocol, if applicable |
||
Value between |
||
FarsightCandidateType |
Type of candidate |
|
Username to use to connect to client if necessary, NULL otherwise |
||
Username to use to connect to client if necessary, NULL otherwise |
Enum for the direction of a FarsightStream
An enum used to signal errors that occur on a FarsightStream
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
struct FarsightStreamClass { GObjectClass parent_class; /*virtual methods */ void (* prepare_transports) (FarsightStream *self); GstElement * (* get_pipeline) (FarsightStream *self); gboolean (* set_pipeline) (FarsightStream *self, GstElement *pipeline); G_CONST_RETURN GList * (* get_native_candidate_list) (FarsightStream *self); GList * (* get_native_candidate) (FarsightStream *self, const gchar* candidate_id); void (* set_remote_candidate_list) (FarsightStream *self, const GList *remote_candidates); void (* add_remote_candidate) (FarsightStream *self, const GList *remote_candidate); void (* remove_remote_candidate) (FarsightStream *self, const gchar *remote_candidate_id); gboolean (* set_active_candidate_pair) (FarsightStream *self, const gchar *native_candidate_id, const gchar *remote_candidiate_id); /* void (*set_local_codec_selection) (FarsightStream *self, const GList *ids); */ G_CONST_RETURN GList * (* get_local_codecs) (FarsightStream *self); gboolean (* set_remote_codecs) (FarsightStream *self, const GList *codecs); GList *(* get_codec_intersection) (FarsightStream *self); void (* set_codec_preference_list) (FarsightStream *self, const GArray *codec_pref); void (* set_active_codec) (FarsightStream *self, gint id); gint (* get_active_codec) (FarsightStream *self); gboolean (* set_sink) (FarsightStream *self, GstElement *sink); gboolean (* set_sink_filter) (FarsightStream *self, GstCaps *filter); GstElement * (* get_sink) (FarsightStream *self); gboolean (* set_source) (FarsightStream *self, GstElement *source); gboolean (* set_source_filter) (FarsightStream *self, GstCaps *filter); GstElement * (* get_source) (FarsightStream *self); gboolean (* start) (FarsightStream *self); void (* stop) (FarsightStream *self); gboolean (*set_sending) (FarsightStream *self, gboolean sending); gboolean (*hold) (FarsightStream *self); gboolean (*unhold) (FarsightStream *self); gboolean (*is_held) (FarsightStream *self); gboolean (* start_telephony_event) (FarsightStream *self, guint8 ev, guint8 volume, FarsightStreamDTMFMethod method); gboolean (* stop_telephony_event) (FarsightStream *self, FarsightStreamDTMFMethod method); gboolean (*preload_receive_pipeline) (FarsightStream *self, gint payload_type); gboolean (* get_jb_statistics) (FarsightStream *self, guint64 *total_packets, guint64 *late_packets, guint64 *duplicate_packets, guint *fill_level, guint64 *times_overrun, guint64 *times_underrun); };
“direction”
property “direction” guint
The direction of this stream. This should only be set at stream creation time.
Flags: Read / Write / Construct Only
Allowed values: <= 4
Default value: 3
“media-type”
property “media-type” guint
The media type to be used by this stream specifed by FarsightMediaType.
Flags: Read / Write / Construct Only
Allowed values: <= 1
Default value: 0
“codec-changed”
signalvoid user_function (FarsightStream *self, gint codec_id, gpointer user_data)
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. |
Flags: Run Last
“error”
signalvoid user_function (FarsightStream *self, gint type, gchar *message, gpointer user_data)
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. |
Flags: Run Last
“native-candidates-prepared”
signalvoid user_function (FarsightStream *self, gpointer user_data)
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. |
Flags: Run Last
“new-active-candidate-pair”
signalvoid user_function (FarsightStream *self, gchar *native_candidate_id, gchar *remote_candidate_id, gpointer user_data)
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. |
Flags: Run Last
“new-native-candidate”
signalvoid user_function (FarsightStream *self, gchar *candidate_id, gpointer user_data)
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. |
Flags: Run Last
“sink-pad-ready”
signalvoid user_function (FarsightStream *self, gpointer pad, gpointer user_data)
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. |
Flags: Run Last
“state-changed”
signalvoid user_function (FarsightStream *self, gint state, gint direction, gpointer user_data)
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. |
Flags: Run Last