Farstream Reference Manual: FsStreamTransmitter

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