## FsStreamTransmitter

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

## Synopsis

    #include <gst/farsight/fs-transmitter.h>

                        FsStreamTransmitter;
    struct              FsStreamTransmitterClass;
    gboolean            fs_stream_transmitter_set_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,
                                                             const gchar *debug_msg);

## Object Hierarchy

      GObject
       +----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 Farsight Stream Transmitter. It needs to be derived and implement by a Farsight transmitter. A Farsight 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 {
      GObjectClass parent_class;

      /*virtual functions */
      gboolean (*set_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

GObjectClass `parent_class`; | Our parent
`set_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_set_remote_candidates ()

    gboolean            fs_stream_transmitter_set_remote_candidates
                                                            (FsStreamTransmitter *streamtransmitter,
                                                             GList *candidates,
                                                             GError **error);

This function is used to set the remote candidates to the transmitter

`streamtransmitter` : | a FsStreamTranmitter
`candidates` : | a GList of the remote candidates
`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
`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,
                                                             const gchar *debug_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 to be displayed to user
`debug_msg` : | Debugging error message

## 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,
                                                            gchar               *debug_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 to be displayed to user
`debug_msg` : | Debugging error message
`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.