FsStream: Farstream Reference Manual

## FsStream FsStream — A stream in a session in a conference |

## Functions

gboolean | fs_stream_set_transmitter ()
gboolean | fs_stream_set_transmitter_ht ()
gboolean | fs_stream_add_remote_candidates ()
gboolean | fs_stream_set_remote_codecs ()
gboolean | fs_stream_force_remote_candidates ()
gboolean | fs_stream_set_decryption_parameters ()
void | fs_stream_destroy ()
GstIterator * | fs_stream_iterate_src_pads ()
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 ()
void | fs_stream_add_id ()
void | fs_stream_emit_error ()
void | fs_stream_emit_src_pad_added ()

## Properties

FsCodecGList * | current-recv-codecs | Read
GstStructure * | decryption-parameters | Read
FsStreamDirection | direction | Read / Write / Construct
FsCodecGList * | negotiated-codecs | Read
FsParticipant * | participant | Read / Write / Construct Only
FsCodecGList * | remote-codecs | Read
gboolean | require-encryption | Read / Write
FsSession * | session | Read / Write / Construct Only

## Signals

void | error | Run Last
void | src-pad-added | Run Last

## Types and Values

struct | FsStream
struct | FsStreamClass
enum | FsStreamDirection
enum | FsStreamState

## Object Hierarchy

        GObject
        ╰── FsStream

## Includes

    #include <farstream/fs-conference.h>

## Description

This object is the base implementation of a Farstream Stream. It needs to be derived and implemented by a Farstream conference GStreamer element. A Farstream 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 "`farstream-new-local-candidate`" message

    1
    2
    "stream"           #FsStream          The stream that emits the message
    "candidate"        #FsCandidate       The new candidate

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

### The "`farstream-local-candidates-prepared`" message

    1
    "stream"           #FsStream          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 "`farstream-new-active-candidate-pair`" message

    1
    2
    3
    "stream"           #FsStream          The stream that emits the message
    "local-candidate"  #FsCandidate       Local candidate being used
    "remote-candidate" #FsCandidate       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 "`farstream-recv-codecs-changed`" message

    1
    2
    "stream"           #FsStream          The stream that emits the message
    "codecs"           #FsCodecGList      A #GList of #FsCodec

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 "`farstream-component-state-changed`" message

    1
    2
    3
    "stream"           #FsStream          The stream that emits the message
    "component"        #guint             The component whose state changed
    "state"            #FsStreamState     The new state of the component

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

## Functions

### fs_stream_set_transmitter ()

    gboolean
    fs_stream_set_transmitter (FsStream *stream,
                               const gchar *transmitter,
                               GParameter *stream_transmitter_parameters,
                               guint stream_transmitter_n_parameters,
                               GError **error);

Set the transmitter to use for this stream. This function will only succeed once.

The parameters correspond to the varios GObject properties of the selected stream transmitter.

#### Parameters

stream | a FsStream |
transmitter | Name of the type of transmitter to use for this stream |
stream_transmitter_n_parameters | Number of parametrs passed to the stream transmitter |
stream_transmitter_parameters | an array of n_parameters GParameter struct that will be passed to the newly-create FsStreamTransmitter. | [array length=stream_transmitter_n_parameters][allow-none]
error | location of a GError, or `NULL` if no error occured |

#### Returns

`TRUE` if the transmitter could be set, `FALSE` otherwise

### fs_stream_set_transmitter_ht ()

    gboolean
    fs_stream_set_transmitter_ht (FsStream *stream,
                                  const gchar *transmitter,
                                  GHashTable *stream_transmitter_parameters,
                                  GError **error);

Set the transmitter to use for this stream. This function will only succeed once.

The parameters correspond to the varios GObject properties of the selected stream transmitter.

This is the same as `fs_stream_set_transmitter()` except that the parameters are passed in a GHashTable to make it more friendly to GObject introspection

#### Parameters

stream | a FsStream |
transmitter | Name of the type of transmitter to use for this stream |
stream_transmitter_parameters | A GHashTable of string->GValue containing the parameters. | [element-type utf8 GValue][allow-none]
error | location of a GError, or `NULL` if no error occured |

#### Returns

`TRUE` if the transmitter could be set, `FALSE` otherwise

### fs_stream_add_remote_candidates ()

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

This function adds 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.

#### Parameters

stream | an FsStream |
candidates | an GList of FsCandidate representing the remote candidates. | [element-type FsCandidate]
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.

#### Parameters

stream | a FsStream |
remote_codecs | a GList of FsCodec representing the remote codecs. | [element-type FsCodec]
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.

#### Parameters

stream | a FsStream |
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_set_decryption_parameters ()

    gboolean
    fs_stream_set_decryption_parameters (FsStream *stream,
                                         GstStructure *parameters,
                                         GError **error);

Sets decryption parameters. The exact parameters depend on the type of plugin being used.

#### Parameters

stream | a FsStream |
parameters | a GstStructure containing the decryption parameters. | [transfer none]
error | the location where to store a GError or `NULL` |

#### Returns

`TRUE` if the decryption parameters could be set, `FALSE` otherwise

Since: UNRELEASED

### fs_stream_destroy ()

    void
    fs_stream_destroy (FsStream *stream);

This will cause the stream to remove all links to other objects and to remove itself from the FsSession. Once a FsStream has been destroyed, it can not be used anymore.

It is strongly recommended to call this function from the main thread because releasing the application's reference to a stream.

#### Parameters

stream | a FsStream |

### fs_stream_iterate_src_pads ()

    GstIterator *
    fs_stream_iterate_src_pads (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.

#### Parameters

stream | a FsStream |

#### Returns

The GstIterator.

[transfer full]

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

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

#### Parameters

stream | a FsStream |
id | The id to add to the stream |

### fs_stream_emit_error ()

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

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

#### Parameters

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 |

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

#### Parameters

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 |

## Types and Values

### struct FsStream

    struct FsStream;

All members are private, access them using methods and properties

### struct FsStreamClass

    struct FsStreamClass {
      GObjectClass parent_class;

      /*virtual functions */
      gboolean (*add_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);

      gboolean (*set_transmitter) (FsStream *stream,
          const gchar *transmitter,
          GParameter *stream_transmitter_parameters,
          guint stream_transmitter_n_parameters,
          GError **error);

      gboolean (* set_decryption_parameters) (FsStream *stream,
          GstStructure *parameters, GError **error);
    };

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

#### Members

`add_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 |
`set_transmitter` () | Set the transmitter to use for this stream |
`set_decryption_parameters` () | Set decryption parameters |

### enum FsStreamDirection

An enum for specifying the direction of a stream

#### Members

FS_DIRECTION_NONE | No direction specified |
FS_DIRECTION_SEND | Send only |
FS_DIRECTION_RECV | Receive only |
FS_DIRECTION_BOTH | Send and receive |

### enum 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.

#### Members

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 |

## Property Details

### The `“current-recv-codecs”` property

      “current-recv-codecs”      FsCodecGList *

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 "farstream-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.

[transfer full]

Flags: Read

### The `“decryption-parameters”` property

      “decryption-parameters”    GstStructure *

Retrieves previously set decryption parameters

Flags: Read

### The `“direction”` property

      “direction”                FsStreamDirection

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.

Flags: Read / Write / Construct

### The `“negotiated-codecs”` property

      “negotiated-codecs”        FsCodecGList *

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.

[transfer full]

Flags: Read

### The `“participant”` property

      “participant”              FsParticipant *

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

Flags: Read / Write / Construct Only

### The `“remote-codecs”` property

      “remote-codecs”            FsCodecGList *

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.

[transfer full]

Flags: Read

### The `“require-encryption”` property

      “require-encryption”       gboolean

If set to TRUE, only encrypted content will be accepted on this stream.

Flags: Read / Write

Default value: FALSE

### The `“session”` property

      “session”                  FsSession *

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

Flags: Read / Write / Construct Only

## Signal Details

### The `“error”` signal

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

This signal is emitted in any error condition

#### Parameters

self | FsStream that emitted the signal |
errorno | The number of the error |
error_msg | Error message to be displayed to user |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“src-pad-added”` signal

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

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!

#### Parameters

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

Flags: Run Last