FsStreamTransmitter: Farstream Reference Manual

FsStreamTransmitter

FsStreamTransmitter — A stream transmitter object used to convey per-stream information to a transmitter.

Functions

gboolean	fs_stream_transmitter_add_remote_candidates ()
gboolean	fs_stream_transmitter_gather_local_candidates ()
gboolean	fs_stream_transmitter_force_remote_candidates ()
void	fs_stream_transmitter_stop ()
void	fs_stream_transmitter_emit_error ()
gboolean	fs_stream_parse_component_state_changed ()
gboolean	fs_stream_parse_local_candidates_prepared ()
gboolean	fs_stream_parse_new_active_candidate_pair ()
gboolean	fs_stream_parse_new_local_candidate ()
gboolean	fs_stream_parse_recv_codecs_changed ()

Properties

gboolean	associate-on-source	Read / Write / Construct Only
FsCandidateList *	preferred-local-candidates	Read / Write / Construct Only
gboolean	sending	Read / Write

Signals

void	error	Run Last
void	known-source-packet-received	Run Last
void	local-candidates-prepared	Run Last
void	new-active-candidate-pair	Run Last
void	new-local-candidate	Run Last
void	state-changed	Run Last

Types and Values

struct	FsStreamTransmitter
struct	FsStreamTransmitterClass

Object Hierarchy

    GObject
    ╰── FsStreamTransmitter

Includes

#include <farstream/fs-transmitter.h>

Description

This object is the base implementation of a Farstream Stream Transmitter. It needs to be derived and implement by a Farstream transmitter. A Farstream Stream transmitter is used to convery per-stream information to a transmitter, this is mostly local and remote candidates

Functions

fs_stream_transmitter_add_remote_candidates ()

gboolean
fs_stream_transmitter_add_remote_candidates
                               (FsStreamTransmitter *streamtransmitter,
                                GList *candidates,
                                GError **error);

This function is used to add remote candidates to the transmitter

Parameters

streamtransmitter	a FsStreamTranmitter
candidates	a GList of the remote candidates.	[element-type FsCandidate]
error	location of a GError, or NULL if no error occured

Returns

TRUE of the candidate could be added, FALSE if it couldnt (and the GError will be set)

fs_stream_transmitter_gather_local_candidates ()

gboolean
fs_stream_transmitter_gather_local_candidates
                               (FsStreamTransmitter *streamtransmitter,
                                GError **error);

This function tells the transmitter to start gathering local candidates, signals for new candidates and newly active candidates can be emitted during the call to this function.

Parameters

streamtransmitter	a FsStreamTransmitter
error	location of a GErrorh, or NULL if no error occured

Returns

TRUE if it succeeds (or is not implemented), FALSE otherwise

fs_stream_transmitter_force_remote_candidates ()

gboolean
fs_stream_transmitter_force_remote_candidates
                               (FsStreamTransmitter *streamtransmitter,
                                GList *remote_candidates,
                                GError **error);

This function forces data to be sent immediately to the selected remote candidate, by-passing any connectivity checks. There should be at most one candidate per component.

Parameters

streamtransmitter	a FsStreamTransmitter
remote_candidates	a GList of FsCandidate to force.	[element-type FsCandidate]
error	location of a GError, or NULL if no error occured

Returns

TRUE if the candidates could be forced, FALSE otherwise

fs_stream_transmitter_stop ()

void
fs_stream_transmitter_stop (FsStreamTransmitter *streamtransmitter);

This functions stops the FsStreamTransmitter, it must be called before the last reference is dropped.

Parameters

streamtransmitter

a FsStreamTransmitter

fs_stream_transmitter_emit_error ()

void
fs_stream_transmitter_emit_error (FsStreamTransmitter *streamtransmitter,
                                  gint error_no,
                                  const gchar *error_msg);

This function emit the "error" signal on a FsStreamTransmitter, it should only be called by subclasses.

Parameters

streamtransmitter	FsStreamTransmitter on which to emit the error signal
error_no	The number of the error
error_msg	Error message (for the programmer)

fs_stream_parse_component_state_changed ()

gboolean
fs_stream_parse_component_state_changed
                               (FsStream *stream,
                                GstMessage *message,
                                guint *component,
                                FsStreamState *state);

Parses a "farstream-component-state-changed" message and checks if it matches the stream parameters.

Parameters

stream	a FsStream to match against the message
message	a GstMessage to parse
component	Returns the component from the GstMessage if not `NULL`.	[out]
state	Returns the FsStreamState from the GstMessage if not `NULL`.	[out]

Returns

TRUE if the message matches the stream and is valid.

fs_stream_parse_local_candidates_prepared ()

gboolean
fs_stream_parse_local_candidates_prepared
                               (FsStream *stream,
                                GstMessage *message);

Parses a "farstream-local-candidates-prepared" message and checks if it matches the stream parameters.

Parameters

stream	a FsStream to match against the message
message	a GstMessage to parse

Returns

TRUE if the message matches the stream and is valid.

fs_stream_parse_new_active_candidate_pair ()

gboolean
fs_stream_parse_new_active_candidate_pair
                               (FsStream *stream,
                                GstMessage *message,
                                FsCandidate **local_candidate,
                                FsCandidate **remote_candidate);

Parses a "farstream-new-active-candidate-pair" message and checks if it matches the stream parameters.

Parameters

stream	a FsStream to match against the message
message	a GstMessage to parse
local_candidate	Returns the local FsCandidate in the message if not `NULL`.	[out][transfer none]
remote_candidate	Returns the remote FsCandidate in the message if not `NULL`.	[out][transfer none]

Returns

TRUE if the message matches the stream and is valid.

fs_stream_parse_new_local_candidate ()

gboolean
fs_stream_parse_new_local_candidate (FsStream *stream,
                                     GstMessage *message,
                                     FsCandidate **candidate);

Parses a "farstream-new-local-candidate" message and checks if it matches the stream parameters.

Parameters

stream	a FsStream to match against the message
message	a GstMessage to parse
candidate	Returns the FsCandidate in the message if not `NULL`.	[out][transfer none]

Returns

TRUE if the message matches the stream and is valid.

fs_stream_parse_recv_codecs_changed ()

gboolean
fs_stream_parse_recv_codecs_changed (FsStream *stream,
                                     GstMessage *message,
                                     GList **codecs);

Parses a "farstream-recv-codecs-changed" message and checks if it matches the stream parameters.

Parameters

stream	a FsStream to match against the message
message	a GstMessage to parse
codecs	Returns a GList of FsCodec of the message if not `NULL`.	[out][transfer none][element-type FsCodec]

Returns

TRUE if the message matches the stream and is valid.

Types and Values

struct FsStreamTransmitter

struct FsStreamTransmitter;

All members are private, access them using methods and properties

struct FsStreamTransmitterClass

struct FsStreamTransmitterClass {
  GObjectClass parent_class;

  /*virtual functions */
  gboolean (*add_remote_candidates) (FsStreamTransmitter *streamtransmitter,
                                     GList *candidates, GError **error);

  gboolean (*force_remote_candidates) (FsStreamTransmitter *streamtransmitter,
      GList *remote_candidates,
      GError **error);
  gboolean (*gather_local_candidates) (FsStreamTransmitter *streamtransmitter,
                                       GError **error);
  void (*stop) (FsStreamTransmitter *streamtransmitter);
};

You must override the add_remote_candidate in a subclass

Members

GObjectClass `parent_class`;	Our parent
`add_remote_candidates` ()	Sets the remote candidates
`force_remote_candidates` ()	Forces certain remote candidates
`gather_local_candidates` ()	Starts the gathering of local candidates
`stop` ()	Stop the stream transmitter synchronously (does any Gst stopping that needs to be done)

Property Details

The `“associate-on-source”` property

  “associate-on-source”      gboolean

This tells the stream transmitter to associate incoming data with this based on the source without looking at the content if possible.

Flags: Read / Write / Construct Only

Default value: TRUE

The `“preferred-local-candidates”` property

  “preferred-local-candidates” FsCandidateList *

A GList of FsCandidates.

Flags: Read / Write / Construct Only

The `“sending”` property

  “sending”                  gboolean

A network source GstElement to be used by the FsSession

Flags: Read / Write

Default value: TRUE

Signal Details

The `“error”` signal

void
user_function (FsStreamTransmitter *self,
               FsError              errorno,
               gchar               *error_msg,
               gpointer             user_data)

This signal is emitted in any error condition

Parameters

self	FsStreamTransmitter that emitted the signal
errorno	The number of the error
error_msg	Error message (for the programmer)
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“known-source-packet-received”` signal

void
user_function (FsStreamTransmitter *self,
               guint                component,
               gpointer             buffer,
               gpointer             user_data)

This signal is emitted when a buffer coming from a confirmed known source is received.

Parameters

self	FsStreamTransmitter that emitted the signal
component	The Component on which this buffer was received
buffer	the GstBuffer coming from the known source
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“local-candidates-prepared”` signal

void
user_function (FsStreamTransmitter *self,
               gpointer             user_data)

This signal is emitted when all local candidates have been prepared, an ICE implementation would send its SDP offer or answer.

Parameters

self	FsStreamTransmitter that emitted the signal
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“new-active-candidate-pair”` signal

void
user_function (FsStreamTransmitter *self,
               FsCandidate         *local_candidate,
               FsCandidate         *remote_candidate,
               gpointer             user_data)

This signal is emitted when there is a new active chandidate pair that has been established. This is specially useful for ICE where the active candidate pair can change automatically due to network conditions. The user must not modify the candidates and must copy them if he wants to use them outside the callback scope.

Parameters

self	FsStreamTransmitter that emitted the signal
local_candidate	FsCandidate of the local candidate being used
remote_candidate	FsCandidate of the remote candidate being used
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“new-local-candidate”` signal

void
user_function (FsStreamTransmitter *self,
               FsCandidate         *local_candidate,
               gpointer             user_data)

This signal is emitted when a new local candidate is discovered.

Parameters

self	FsStream that emitted the signal
local_candidate	FsCandidate of the local candidate
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“state-changed”` signal

void
user_function (FsStreamTransmitter *self,
               guint                component,
               FsStreamState        state,
               gpointer             user_data)

This signal is emitted when the ICE state (or equivalent) of the component changes

Parameters

self	FsStreamTransmitter that emitted the signal
component	the id of the component which state has changed
state	the new state of the component
user_data	user data set when the signal handler was connected.

Flags: Run Last