FsStream

FsStream — A stream in a session in a conference

Synopsis

#include <gst/farsight/fs-conference-iface.h>

                    FsStream;
struct              FsStreamClass;
enum                FsStreamDirection;
enum                FsStreamState;
gboolean            fs_stream_set_remote_candidates     (FsStream *stream,
                                                         GList *candidates,
                                                         GError **error);
gboolean            fs_stream_set_remote_codecs         (FsStream *stream,
                                                         GList *remote_codecs,
                                                         GError **error);
gboolean            fs_stream_force_remote_candidates   (FsStream *stream,
                                                         GList *remote_candidates,
                                                         GError **error);
void                fs_stream_add_id                    (FsStream *stream,
                                                         guint id);
GstIterator *       fs_stream_get_src_pads_iterator     (FsStream *stream);
void                fs_stream_emit_error                (FsStream *stream,
                                                         gint error_no,
                                                         const gchar *error_msg,
                                                         const 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
  "negotiated-codecs"        FsCodecGList*         : Read
  "participant"              FsParticipant*        : Read / Write / Construct Only
  "remote-codecs"            FsCodecGList*         : Read
  "session"                  FsSession*            : Read / Write / Construct Only

Signals

  "error"                                          : 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 FsParticipant inside a FsSession. In fact, a FsStream instance is obtained by adding a participant into a session using fs_session_new_stream().

This will communicate asynchronous events to the user through GstMessage of type GST_MESSAGE_ELEMENT sent over the GstBus.

The "farsight-new-local-candidate" message

1
2
"stream"           <a class="link" href="FsStream.html" title="FsStream">FsStream</a>          The stream that emits the message
"candidate"        <a class="link" href="farsight2-libs-FsCandidate.html#FsCandidate" title="struct FsCandidate">FsCandidate</a>       The new candidate

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


The "farsight-local-candidates-prepared" message

1
"stream"           <a class="link" href="FsStream.html" title="FsStream">FsStream</a>          The stream that emits the message

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


The "farsight-new-active-candidate-pair" message

1
2
3
"stream"           <a class="link" href="FsStream.html" title="FsStream">FsStream</a>          The stream that emits the message
"local-candidate"  <a class="link" href="farsight2-libs-FsCandidate.html#FsCandidate" title="struct FsCandidate">FsCandidate</a>       Local candidate being used
"remote-candidate" <a class="link" href="farsight2-libs-FsCandidate.html#FsCandidate" title="struct FsCandidate">FsCandidate</a>       Remote candidate being used

This message is emitted when there is a new active candidate 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. This message is emitted once per component.


The "farsight-recv-codecs-changed" message

1
2
"stream"           <a class="link" href="FsStream.html" title="FsStream">FsStream</a>          The stream that emits the message
"codecs"           <GTKDOCLINK HREF="FsCodecGList">FsCodecGList</GTKDOCLINK>      A <GTKDOCLINK HREF="GList">GList</GTKDOCLINK> of <a class="link" href="farsight2-libs-FsCodec.html#FsCodec" title="struct FsCodec">FsCodec</a>

This message is emitted when the content of the "current-recv-codecs" property changes. It is normally emitted right after the "src-pad-added" signal 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. The list of new recv-codecs is included in the message


The "farsight-component-state-changed" message

1
2
3
"stream"           <a class="link" href="FsStream.html" title="FsStream">FsStream</a>          The stream that emits the message
"component"        <GTKDOCLINK HREF="guint">guint</GTKDOCLINK>             The component whose state changed
"state"            <a class="link" href="FsStream.html#FsStreamState" title="enum FsStreamState">FsStreamState</a>     The new state of the component

This message is emitted the state of a component of a stream changes.

Details

FsStream

typedef struct _FsStream FsStream;

All members are private, access them using methods and properties


struct FsStreamClass

struct FsStreamClass {
  GObjectClass parent_class;

  /*virtual functions */
  gboolean (*set_remote_candidates) (FsStream *stream,
                                     GList *candidates,
                                     GError **error);

  gboolean (*force_remote_candidates) (FsStream *stream,
      GList *remote_candidates,
      GError **error);

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

  void (*add_id) (FsStream *stream,
                  guint id);
};

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

set_remote_candidates ()

Set sthe remote candidates

force_remote_candidates ()

Forces certain remote candidates

set_remote_codecs ()

Sets the list of remote codecs

add_id ()

Add a known id to be associated with this stream

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

enum FsStreamState

typedef enum
{
  FS_STREAM_STATE_FAILED,
  FS_STREAM_STATE_DISCONNECTED,
  FS_STREAM_STATE_GATHERING,
  FS_STREAM_STATE_CONNECTING,
  FS_STREAM_STATE_CONNECTED,
  FS_STREAM_STATE_READY
} FsStreamState;

These are the possible states of a stream, a simple multicast stream could only be in "disconnected" or "ready" state. An stream using an ICE transmitter would use all of these.

FS_STREAM_STATE_FAILED

connectivity checks have been completed, but connectivity was not established

FS_STREAM_STATE_DISCONNECTED

no activity scheduled

FS_STREAM_STATE_GATHERING

gathering local candidates

FS_STREAM_STATE_CONNECTING

establishing connectivity

FS_STREAM_STATE_CONNECTED

at least one working candidate pair

FS_STREAM_STATE_READY

ICE concluded, candidate pair selection is now final

fs_stream_set_remote_candidates ()

gboolean            fs_stream_set_remote_candidates     (FsStream *stream,
                                                         GList *candidates,
                                                         GError **error);

This function sets the list of remote candidates. Any new candidates are added to the list. The candidates will be used to establish 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

candidates :

an GList of FsCandidate representing the remote candidates

error :

location of a GError, or NULL if no error occured

Returns :

TRUE if the candidate was valid, 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 :

a 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_force_remote_candidates ()

gboolean            fs_stream_force_remote_candidates   (FsStream *stream,
                                                         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.

stream :

a FsStream

remote_candidates :

a GList of FsCandidate to force

error :

location of a GError, or NULL if no error occured

Returns :

TRUE if the candidates could be forced, FALSE otherwise

fs_stream_add_id ()

void                fs_stream_add_id                    (FsStream *stream,
                                                         guint id);

This function is used to add data identifiers that allow the plugin to recognize packets that are meant for id. For example, in RTP, one would set the SSRCs that are expected.

Depending on the protocol, one may be able to add more than one ID to a stream (in RTP you can have multiple SSRCs in a stream). If a protocol supports only one id, adding a new one will overwrite it. If an ID was already set on a stream, adding it to another stream will override the previdous decision.

For most protocols, calling this function is optional as the incoming data can be matched with a stream by its source IP address. This is mostly useful if one is using multicast or is behind a muxer server.

stream :

a FsStream

id :

The id to add to the stream

fs_stream_get_src_pads_iterator ()

GstIterator *       fs_stream_get_src_pads_iterator     (FsStream *stream);

Creates a GstIterator that can be used to iterate the src pads of this stream. These are the pads that were announced by "src-pad-added" and are still valid.

stream :

a FsStream

Returns :

The GstIterator

fs_stream_emit_error ()

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

This function emits the "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);

Emits the "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

This is the list of codecs that have been received by this stream. The user must free the list if fs_codec_list_destroy(). The "farsight-recv-codecs-changed" message is send on the GstBus when the value of this property changes. It 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.


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 "negotiated-codecs" property

  "negotiated-codecs"        FsCodecGList*         : Read

This is the list of negotiatied codecs, it is the same list as the list of FsCodec from the parent FsSession, except that the codec config data has been replaced with the data from the remote codecs for this stream. This is the list of FsCodec used to receive data from this stream. It is a GList of FsCodec.


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.

Signal Details

The "error" signal

void                user_function                      (FsStream *self,
                                                        FsError   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 "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.