FsStream

FsStream — A stream in a session in a conference

Synopsis




                    FsStream;
                    FsStreamClass;
enum                FsStreamDirection;
gboolean            fs_stream_add_remote_candidate      (FsStream *stream,
                                                         FsCandidate *candidate,
                                                         GError **error);
void                fs_stream_remote_candidates_added   (FsStream *stream);
gboolean            fs_stream_select_candidate_pair     (FsStream *stream,
                                                         gchar *lfoundation,
                                                         gchar *rfoundation,
                                                         GError **error);
gboolean            fs_stream_set_remote_codecs         (FsStream *stream,
                                                         GList *remote_codecs,
                                                         GError **error);
void                fs_stream_emit_error                (FsStream *stream,
                                                         gint error_no,
                                                         gchar *error_msg,
                                                         gchar *debug_msg);
void                fs_stream_emit_src_pad_added        (FsStream *stream,
                                                         GstPad *pad,
                                                         FsCodec *codec);

Object Hierarchy


  GObject
   +----FsStream

Properties


  "current-recv-codecs"      FsCodecGList          : Read
  "direction"                FsStreamDirection     : Read / Write / Construct
  "participant"              FsParticipant         : Read / Write / Construct Only
  "remote-codecs"            FsCodecGList          : Read
  "session"                  FsSession             : Read / Write / Construct Only
  "stream-transmitter"       FsStreamTransmitter   : Read / Write / Construct Only

Signals


  "error"                                          : Run Last
  "local-candidates-prepared"                      : Run Last
  "new-active-candidate-pair"                      : Run Last
  "new-local-candidate"                            : Run Last
  "recv-codecs-changed"                            : Run Last
  "src-pad-added"                                  : Run Last

Description

This object is the base implementation of a Farsight Stream. It needs to be derived and implemented by a farsight conference gstreamer element. A Farsight Stream is a media stream originating from a participant inside a session. In fact, a FarsightStream instance is obtained by adding a participant into a session using fs_session_add_participant.

Details

FsStream

typedef struct _FsStream FsStream;

All members are private, access them using methods and properties


FsStreamClass

typedef struct {
  GObjectClass parent_class;

  /*virtual functions */
  gboolean (*add_remote_candidate) (FsStream *stream,
                                    FsCandidate *candidate,
                                    GError **error);

  void (*remote_candidates_added) (FsStream *stream);

  gboolean (*select_candidate_pair) (FsStream *stream, gchar *lfoundation,
                                     gchar *rfoundation, GError **error);

  gboolean (*set_remote_codecs) (FsStream *stream,
                                 GList *remote_codecs, GError **error);
} FsStreamClass;

You must override add_remote_candidate in a subclass. If you have to negotiate codecs, then you must override set_remote_codecs too

GObjectClass parent_class;

Our parent

add_remote_candidate ()

Adds a remote candidate

remote_candidates_added ()

Tell the stream to start the connectivity checks

select_candidate_pair ()

Select the candidate pair

set_remote_codecs ()

Sets the list of remote codecs

enum FsStreamDirection

typedef enum
{
  FS_DIRECTION_NONE = 0,
  FS_DIRECTION_SEND = 1<<0,
  FS_DIRECTION_RECV = 1<<1,
  FS_DIRECTION_BOTH = FS_DIRECTION_SEND | FS_DIRECTION_RECV
} FsStreamDirection;

An enum for specifying the direction of a stream

FS_DIRECTION_NONE

No direction specified

FS_DIRECTION_SEND

Send only

FS_DIRECTION_RECV

Receive only

FS_DIRECTION_BOTH

Send and receive

fs_stream_add_remote_candidate ()

gboolean            fs_stream_add_remote_candidate      (FsStream *stream,
                                                         FsCandidate *candidate,
                                                         GError **error);

This function adds the given candidate into the remote candiate list of the stream. It will be used for establishing a connection with the peer. A copy will be made so the user must free the passed candidate using fs_candidate_destroy() when done.

stream :

an FsStream

candidate :

an FsCandidate struct representing a remote candidate

error :

location of a GError, or NULL if no error occured

Returns :

TRUE if the candidate was valid, FALSE otherwise

fs_stream_remote_candidates_added ()

void                fs_stream_remote_candidates_added   (FsStream *stream);

Call this function when the remotes candidates have been set and the checks can start. More candidates can be added afterwards

stream :

a FsStream

fs_stream_select_candidate_pair ()

gboolean            fs_stream_select_candidate_pair     (FsStream *stream,
                                                         gchar *lfoundation,
                                                         gchar *rfoundation,
                                                         GError **error);

This function selects one pair of candidates to be selected to start sending media on.

stream :

a FsStream

lfoundation :

The foundation of the local candidate to be selected

rfoundation :

The foundation of the remote candidate to be selected

error :

location of a GError, or NULL if no error occured

Returns :

TRUE if the candidate pair could be selected, FALSE otherwise

fs_stream_set_remote_codecs ()

gboolean            fs_stream_set_remote_codecs         (FsStream *stream,
                                                         GList *remote_codecs,
                                                         GError **error);

This function will set the list of remote codecs for this stream. If the given remote codecs couldn't be negotiated with the list of local codecs or already negotiated codecs for the corresponding FsSession, error will be set and FALSE will be returned. The remote_codecs list will be copied so it must be free'd using fs_codec_list_destroy() when done.

stream :

an FsStream

remote_codecs :

a GList of FsCodec representing the remote codecs

error :

location of a GError, or NULL if no error occured

Returns :

FALSE if the remote codecs couldn't be set.

fs_stream_emit_error ()

void                fs_stream_emit_error                (FsStream *stream,
                                                         gint error_no,
                                                         gchar *error_msg,
                                                         gchar *debug_msg);

This function emits the FsStream::error" signal, it should only be called by subclasses.

stream :

FsStream on which to emit the error signal

error_no :

The number of the error

error_msg :

Error message to be displayed to user

debug_msg :

Debugging error message

fs_stream_emit_src_pad_added ()

void                fs_stream_emit_src_pad_added        (FsStream *stream,
                                                         GstPad *pad,
                                                         FsCodec *codec);

This functin emits the FsStream::src-pad-added" signal, it should only be called by subclasses.

stream :

FsStream on which to emit the src-pad-added signal

pad :

the GstPad that this FsStream has created

codec :

The FsCodec for this pad

Property Details

The "current-recv-codecs" property

  "current-recv-codecs"      FsCodecGList          : Read

A GList of FsCodec representing the codecs that have been received.


The "direction" property

  "direction"                FsStreamDirection     : Read / Write / Construct

The direction of the stream. This property is set initially as a parameter to the fs_session_new_stream() function. It can be changed later if required by setting this property.


The "participant" property

  "participant"              FsParticipant         : Read / Write / Construct Only

The FsParticipant for this stream. This property is a construct param and is read-only construction.


The "remote-codecs" property

  "remote-codecs"            FsCodecGList          : Read

This is the list of remote codecs for this stream. They must be set by the user as soon as they are known using fs_stream_set_remote_codecs() (generally through external signaling). It is a GList of FsCodec.


The "session" property

  "session"                  FsSession             : Read / Write / Construct Only

The FsSession for this stream. This property is a construct param and is read-only construction.


The "stream-transmitter" property

  "stream-transmitter"       FsStreamTransmitter   : Read / Write / Construct Only

The FsStreamTransmitter for this stream.

Signal Details

The "error" signal

void                user_function                      (FsStream *self,
                                                        gint      errorno,
                                                        gchar    *error_msg,
                                                        gchar    *debug_msg,
                                                        gpointer  user_data)      : Run Last

This signal is emitted in any error condition

self :

FsStream that emitted the signal

errorno :

The number of the error

error_msg :

Error message to be displayed to user

debug_msg :

Debugging error message

user_data :

user data set when the signal handler was connected.

The "local-candidates-prepared" signal

void                user_function                      (FsStream *self,
                                                        gpointer  user_data)      : Run Last

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

self :

FsStream that emitted the signal

user_data :

user data set when the signal handler was connected.

The "new-active-candidate-pair" signal

void                user_function                      (FsStream    *self,
                                                        FsCandidate *local_candidate,
                                                        FsCandidate *remote_candidate,
                                                        gpointer     user_data)             : Run Last

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.

self :

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

The "new-local-candidate" signal

void                user_function                      (FsStream    *self,
                                                        FsCandidate *local_candidate,
                                                        gpointer     user_data)            : Run Last

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

self :

FsStream that emitted the signal

local_candidate :

FsCandidate of the local candidate

user_data :

user data set when the signal handler was connected.

The "recv-codecs-changed" signal

void                user_function                      (FsStream *self,
                                                        gpointer  user_data)      : Run Last

This signal is emitted when the list of currently received codecs has changed. They can be fetched from the FsStream:current-recv-codecs property. This is useful for displaying the current active reception codecs. This signal is normally emitted right after src-pad-added only if that codec was not previously received in this stream, but it can also be emitted if the pad already exists, but the source material that will come to it is different.

self :

FsStream that emitted the signal

user_data :

user data set when the signal handler was connected.

The "src-pad-added" signal

void                user_function                      (FsStream *self,
                                                        GstPad   *pad,
                                                        FsCodec  *codec,
                                                        gpointer  user_data)      : Run Last

This signal is emitted when a new gst source pad has been created for a specific codec being received. There will be a different source pad for each codec that is received. The user must ref the GstPad if he wants to keep it. The user should not modify the FsCodec and must copy it if he wants to use it outside the callback scope.

This signal is not emitted on the main thread, but on GStreamer's streaming thread!

self :

FsStream that emitted the signal

pad :

GstPad of the new source pad

codec :

FsCodec of the codec being received on the new source pad

user_data :

user data set when the signal handler was connected.