FsStreamTransmitter

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

## Synopsis

    #include <farstream/fs-transmitter.h>

                        FsStreamTransmitter;
    struct              FsStreamTransmitterClass;
    gboolean            fs_stream_transmitter_add_remote_candidates
                                                            (FsStreamTransmitter *streamtransmitter,
                                                             GList *candidates,
                                                             GError **error);
    gboolean            fs_stream_transmitter_gather_local_candidates
                                                            (FsStreamTransmitter *streamtransmitter,
                                                             GError **error);
    gboolean            fs_stream_transmitter_force_remote_candidates
                                                            (FsStreamTransmitter *streamtransmitter,
                                                             GList *remote_candidates,
                                                             GError **error);
    void                fs_stream_transmitter_stop          (FsStreamTransmitter *streamtransmitter);
    void                fs_stream_transmitter_emit_error    (FsStreamTransmitter *streamtransmitter,
                                                             gint error_no,
                                                             const gchar *error_msg);
    gboolean            fs_stream_parse_component_state_changed
                                                            (FsStream *stream,
                                                             GstMessage *message,
                                                             guint *component,
                                                             FsStreamState *state);
    gboolean            fs_stream_parse_local_candidates_prepared
                                                            (FsStream *stream,
                                                             GstMessage *message);
    gboolean            fs_stream_parse_new_active_candidate_pair
                                                            (FsStream *stream,
                                                             GstMessage *message,
                                                             FsCandidate **local_candidate,
                                                             FsCandidate **remote_candidate);
    gboolean            fs_stream_parse_new_local_candidate (FsStream *stream,
                                                             GstMessage *message,
                                                             FsCandidate **candidate);
    gboolean            fs_stream_parse_recv_codecs_changed (FsStream *stream,
                                                             GstMessage *message,
                                                             GList **codecs);

## Object Hierarchy

      GObject
       +----GstObject
             +----FsStreamTransmitter

## Properties

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

## Signals

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

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

## Details

### FsStreamTransmitter

    typedef struct _FsStreamTransmitter FsStreamTransmitter;

All members are private, access them using methods and properties

### struct FsStreamTransmitterClass

    struct FsStreamTransmitterClass {
      GstObjectClass 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

GstObjectClass `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)

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

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

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

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

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

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

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

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

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

`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);

Returns a GList of FsCodec of the message if not `NULL`

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

`stream` : | a FsStream to match against the message
`message` : | a GstMessage to parse
`codecs` : | . [out][transfer none][element-type FsCodec]
Returns : | `TRUE` if the message matches the stream and is valid.

## Property Details

### The `"associate-on-source"` property

      "associate-on-source"      gboolean              : Read / Write / Construct Only

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

Default value: TRUE

### The `"preferred-local-candidates"` property

      "preferred-local-candidates" FsCandidateList*      : Read / Write / Construct Only

A GList of FsCandidates.

### The `"sending"` property

      "sending"                  gboolean              : Read / Write

A network source GstElement to be used by the FsSession

Default value: TRUE

## Signal Details

### The `"error"` signal

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

This signal is emitted in any error condition

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

### The `"known-source-packet-received"` signal

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

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

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

### The `"local-candidates-prepared"` signal

    void                user_function                      (FsStreamTransmitter *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` : | FsStreamTransmitter that emitted the signal
`user_data` : | user data set when the signal handler was connected.

### The `"new-active-candidate-pair"` signal

    void                user_function                      (FsStreamTransmitter *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` : | 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.

### The `"new-local-candidate"` signal

    void                user_function                      (FsStreamTransmitter *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 `"state-changed"` signal

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

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

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