FsSession: Farstream Reference Manual

## FsSession FsSession — A session in a conference |

## Functions

FsStream * | fs_session_new_stream ()
gboolean | fs_session_set_codec_preferences ()
void | fs_session_destroy ()
gboolean | fs_session_start_telephony_event ()
gboolean | fs_session_stop_telephony_event ()
gboolean | fs_session_set_send_codec ()
gchar ** | fs_session_list_transmitters ()
GType | fs_session_get_stream_transmitter_type ()
GList * | fs_session_codecs_need_resend ()
gboolean | fs_session_set_allowed_caps ()
gboolean | fs_session_set_encryption_parameters ()
void | fs_session_emit_error ()
gboolean | fs_session_parse_codecs_changed ()
gboolean | fs_session_parse_send_codec_changed ()
gboolean | fs_session_parse_telephony_event_started ()
gboolean | fs_session_parse_telephony_event_stopped ()

## Properties

GstCaps * | allowed-sink-caps | Read
GstCaps * | allowed-src-caps | Read
FsCodecGList * | codec-preferences | Read
FsCodecGList * | codecs | Read
FsCodecGList * | codecs-without-config | Read
FsConference * | conference | Read / Write / Construct Only
FsCodec * | current-send-codec | Read
GstStructure * | encryption-parameters | Read
guint | id | Read / Write / Construct Only
FsMediaType | media-type | Read / Write / Construct Only
GstPad * | sink-pad | Read
guint | tos | Read / Write

## Signals

void | error | Run Last

## Types and Values

struct | FsSession
struct | FsSessionClass
enum | FsDTMFEvent
enum | FsDTMFMethod

## Object Hierarchy

        GObject
        ╰── FsSession

## Includes

    #include <farstream/fs-conference.h>

## Description

This object is the base implementation of a Farstream Session. It needs to be derived and implemented by a farstream conference gstreamer element. A Farstream session is defined in the same way as an RTP session. It can contain one or more participants but represents only one media stream (i.e. One session for video and one session for audio in an AV conference). Sessions contained in the same conference will be synchronised together during playback.

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

### The "`farstream-send-codec-changed`" message

`"session"` | FsSession | The session that emits the message
`"codec"` | FsCodec | The new send codec
`"secondary-codecs"` | GList | A GList of FsCodec (to be freed with `fs_codec_list_destroy()`)

This message is sent on the bus when the value of the “current-send-codec” property changes.

### The "`farstream-codecs-changed`" message

`"session"` | FsSession | The session that emits the message

This message is sent on the bus when the value of the “codecs” or “codecs-without-config” properties change. If one is using codecs that have configuration data that needs to be transmitted reliably, one should fetch “codecs”, otherwise, “codecs-without-config” should be enough.

### The "`farstream-telephony-event-started`" message

`"session"` | FsSession | The session that emits the message
`"method"` | FsDTMFMethod | The method used to send the DTMF
`"event"` | FSDTMFEvent | The event number
`"volume"` | guchar | The volume of the event

This message is emitted after a succesful call to `fs_session_start_telephony_event()` to inform the application that the telephony event has started.

### The "`farstream-telephony-event-stopped`" message

`"session"` | FsSession | The session that emits the message
`"method"` | FsDTMFMethod | The method used to send the DTMF

This message is emitted after a succesful call to `fs_session_stop_telephony_event()` to inform the application that the telephony event has stopped.

## Functions

### fs_session_new_stream ()

    FsStream *
    fs_session_new_stream (FsSession *session,
                           FsParticipant *participant,
                           FsStreamDirection direction,
                           GError **error);

This function creates a stream for the given participant into the active session.

#### Parameters

session | a FsSession |
participant | FsParticipant of a participant for the new stream |
direction | FsStreamDirection describing the direction of the new stream that will be created for this participant |
error | location of a GError, or `NULL` if no error occured |

#### Returns

the new FsStream that has been created. User must unref the FsStream when the stream is ended. If an error occured, returns NULL.

[transfer full]

### fs_session_set_codec_preferences ()

    gboolean
    fs_session_set_codec_preferences (FsSession *session,
                                      GList *codec_preferences,
                                      GError **error);

Set the list of desired codec preferences. The user may change this value during an ongoing session. Note that doing this can cause the codecs to change. Therefore this requires the user to fetch the new codecs and renegotiate them with the peers. It is a GList of FsCodec. The changes are immediately effective. The function does not take ownership of the list.

The payload type may be a valid dynamic PT (96-127), `FS_CODEC_ID_DISABLE` or `FS_CODEC_ID_ANY`. If the encoding name is "reserve-pt", then the payload type of the codec will be "reserved" and not be used by any dynamically assigned payload type.

If the list of specifications would invalidate all codecs, an error will be returned.

#### Parameters

session | a FsSession |
codec_preferences | a GList of FsCodec with the desired configuration. | [element-type FsCodec][allow-none]
error | location of a GError, or `NULL` if no error occured |

#### Returns

`TRUE` on success, `FALSE` on error.

### fs_session_destroy ()

    void
    fs_session_destroy (FsSession *session);

This will cause the session to remove all links to other objects and to remove itself from the FsConference, it will also destroy all FsStream inside this FsSession Once a FsSession 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 session.

#### Parameters

session | a FsSession |

### fs_session_start_telephony_event ()

    gboolean
    fs_session_start_telephony_event (FsSession *session,
                                      guint8 event,
                                      guint8 volume);

This function will start sending a telephony event (such as a DTMF tone) on the FsSession. You have to call the function `fs_session_stop_telephony_event()` to stop it.

If this function returns `TRUE`, a "farstream-telephony-event-started" will always be emitted when the event is actually played out.

#### Parameters

session | a FsSession |
event | A FsStreamDTMFEvent or another number defined at http://www.iana.org/assignments/audio-telephone-event-registry |
volume | The volume in dBm0 without the negative sign. Should be between 0 and 36. Higher values mean lower volume |

#### Returns

`TRUE` if sucessful, it can return `FALSE` if the FsStream does not support this telephony event.

### fs_session_stop_telephony_event ()

    gboolean
    fs_session_stop_telephony_event (FsSession *session);

This function will stop sending a telephony event started by `fs_session_start_telephony_event()`. If the event was being sent for less than 50ms, it will be sent for 50ms minimum. If the duration was a positive and the event is not over, it will cut it short.

If this function returns `TRUE`, a "farstream-telephony-event-stopped" will always be emitted when the event is actually stopped.

#### Parameters

session | an FsSession |

#### Returns

`TRUE` if sucessful, it can return `FALSE` if the FsSession does not support telephony events or if no telephony event is being sent

### fs_session_set_send_codec ()

    gboolean
    fs_session_set_send_codec (FsSession *session,
                               FsCodec *send_codec,
                               GError **error);

This function will set the currently being sent codec for all streams in this session. The given FsCodec must be taken directly from the codecs property of the session. If the given codec is not in the codecs list, `error` will be set and `FALSE` will be returned. The `send_codec` will be copied so it must be free'd using `fs_codec_destroy()` when done.

#### Parameters

session | a FsSession |
send_codec | a FsCodec representing the codec to send |
error | location of a GError, or `NULL` if no error occured |

#### Returns

`FALSE` if the send codec couldn't be set.

### fs_session_list_transmitters ()

    gchar **
    fs_session_list_transmitters (FsSession *session);

Get the list of all available transmitters for this session.

#### Parameters

session | A FsSession |

#### Returns

a newly-allocagted `NULL` terminated array of named of transmitters or `NULL` if no transmitter is needed for this type of session. It should be freed with `g_strfreev()`.

[transfer full]

### fs_session_get_stream_transmitter_type ()

    GType
    fs_session_get_stream_transmitter_type
                                   (FsSession *session,
                                    const gchar *transmitter);

Returns the GType of the stream transmitter, bindings can use it to validate/convert the parameters passed to `fs_session_new_stream()`.

#### Parameters

session | A FsSession |
transmitter | The name of the transmitter |

#### Returns

The GType of the stream transmitter

### fs_session_codecs_need_resend ()

    GList *
    fs_session_codecs_need_resend (FsSession *session,
                                   GList *old_codecs,
                                   GList *new_codecs);

Some codec updates need to be reliably transmitted to the other side because they contain important parameters required to decode the media. Other codec updates, caused by user action, don't.

#### Parameters

session | a FsSession |
old_codecs | Codecs previously retrieved from the “codecs” property. | [element-type FsCodec][transfer none][allow-none]
new_codecs | Codecs recently retrieved from the “codecs” property. | [element-type FsCodec][transfer none][allow-none]

#### Returns

A new GList of FsCodec that need to be resent or `NULL` if there are none. This list must be freed with `fs_codec_list_destroy()`.

[element-type FsCodec][transfer full]

### fs_session_set_allowed_caps ()

    gboolean
    fs_session_set_allowed_caps (FsSession *session,
                                 GstCaps *sink_caps,
                                 GstCaps *src_caps,
                                 GError **error);

Sets the allowed caps for the sink and source pads for this FsSession. Only codecs that can take the input specified by the `sink_caps` and can produce output as specified by the `src_caps` will be produced in the “codecs” property and so only those will be negotiated.

If `NULL` is passed to either `src_caps` or `sink_caps` , it is not changed.

The default is "video/x-raw" for a video stream, "audio/x-raw" for an audio stream and "ANY" for an application stream.

The values can be retrived using the “allowed-src-caps” and “allowed-sink-caps” properties.

#### Parameters

session | a FsSession |
sink_caps | Caps for the sink pad or `NULL`. | [allow-none]
src_caps | Caps for the src pad or `NULL`. | [allow-none]
error | the location where a GError can be stored or `NULL` |

#### Returns

`TRUE` if the new filter caps were acceptable.

Since: UNRELEASED

### fs_session_set_encryption_parameters ()

    gboolean
    fs_session_set_encryption_parameters (FsSession *session,
                                          GstStructure *parameters,
                                          GError **error);

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

#### Parameters

session | a FsSession |
parameters | a GstStructure containing the encryption parameters or `NULL` to disable encryption. | [transfer none][allow-none]
error | the location where to store a GError or `NULL` |

#### Returns

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

Since: UNRELEASED

### fs_session_emit_error ()

    void
    fs_session_emit_error (FsSession *session,
                           gint error_no,
                           const gchar *error_msg);

This function emit the "error" signal on a FsSession, it should only be called by subclasses.

#### Parameters

session | FsSession on which to emit the error signal |
error_no | The number of the error of type FsError |
error_msg | Error message |

### fs_session_parse_codecs_changed ()

    gboolean
    fs_session_parse_codecs_changed (FsSession *session,
                                     GstMessage *message);

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

#### Parameters

session | a FsSession to match against the message |
message | a GstMessage to parse |

#### Returns

`TRUE` if the message matches the session and is valid.

### fs_session_parse_send_codec_changed ()

    gboolean
    fs_session_parse_send_codec_changed (FsSession *session,
                                         GstMessage *message,
                                         FsCodec **codec,
                                         GList **secondary_codecs);

Parses a "farstream-send-codec-changed" message and checks if it matches the `session` parameters.

#### Parameters

session | a FsSession to match against the message |
message | a GstMessage to parse |
codec | Returns the FsCodec in the message if not `NULL`. | [out][transfer none]
secondary_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 session and is valid.

### fs_session_parse_telephony_event_started ()

    gboolean
    fs_session_parse_telephony_event_started
                                   (FsSession *session,
                                    GstMessage *message,
                                    FsDTMFMethod *method,
                                    FsDTMFEvent *event,
                                    guint8 *volume);

Parses a "farstream-telephony-event-started" message and checks if it matches the `session` parameters.

#### Parameters

session | a FsSession to match against the message |
message | a GstMessage to parse |
method | Returns the FsDTMFMethod in the message if not `NULL`. | [out]
event | Returns the FsDTMFEvent in the message if not `NULL`. | [out]
volume | Returns the volume in the message if not `NULL`. | [out]

#### Returns

`TRUE` if the message matches the session and is valid.

### fs_session_parse_telephony_event_stopped ()

    gboolean
    fs_session_parse_telephony_event_stopped
                                   (FsSession *session,
                                    GstMessage *message,
                                    FsDTMFMethod *method);

Parses a "farstream-telephony-event-stopped" message and checks if it matches the `session` parameters.

#### Parameters

session | a FsSession to match against the message |
message | a GstMessage to parse |
method | Returns the FsDTMFMethod in the message if not `NULL`. | [out]

#### Returns

`TRUE` if the message matches the session and is valid.

## Types and Values

### struct FsSession

    struct FsSession;

All members are private, access them using methods and properties

### struct FsSessionClass

    struct FsSessionClass {
      GObjectClass parent_class;

      /*virtual functions */
      FsStream *(* new_stream) (FsSession *session,
                                FsParticipant *participant,
                                FsStreamDirection direction,
                                GError **error);

      gboolean (* start_telephony_event) (FsSession *session, guint8 event,
                                          guint8 volume);
      gboolean (* stop_telephony_event) (FsSession *session);

      gboolean (* set_send_codec) (FsSession *session, FsCodec *send_codec,
                                   GError **error);
      gboolean (* set_codec_preferences) (FsSession *session,
          GList *codec_preferences,
          GError **error);

      gchar** (* list_transmitters) (FsSession *session);

      GType (* get_stream_transmitter_type) (FsSession *session,
                                             const gchar *transmitter);

      GList* (* codecs_need_resend) (FsSession *session, GList *old_codecs,
          GList *new_codecs);

      gboolean (* set_allowed_caps) (FsSession *session, GstCaps *sink_caps,
          GstCaps *src_caps, GError **error);

      gboolean (* set_encryption_parameters) (FsSession *session,
          GstStructure *parameters, GError **error);
    };

You must override at least new_stream in a subclass.

#### Members

`new_stream` () | Create a new FsStream |
`start_telephony_event` () | Starts a telephony event |
`stop_telephony_event` () | Stops a telephony event |
`set_send_codec` () | Forces sending with a specific codec |
`set_codec_preferences` () | Specifies the codec preferences |
`list_transmitters` () | Returns a list of the available transmitters |
`get_stream_transmitter_type` () | Returns the GType of the stream transmitter |
`codecs_need_resend` () | Returns the list of codecs that need resending |
`set_allowed_caps` () | Set the possible allowed src and sink caps |
`set_encryption_parameters` () | Set encryption parameters |

### enum FsDTMFEvent

An enum that represents the different DTMF event that can be sent to a FsSession. The values corresponds those those defined in RFC 4733 The rest of the possibles values are in the IANA registry at: http://www.iana.org/assignments/audio-telephone-event-registry

#### Members

### enum FsDTMFMethod

An enum that represents the different ways a DTMF event can be sent

#### Members

FS_DTMF_METHOD_RTP_RFC4733 | Send as a special payload type defined by RFC 4733 (which obsoletes RFC 2833) |
FS_DTMF_METHOD_SOUND | Send as tones as in-band audio sound |

## Property Details

### The `“allowed-sink-caps”` property

      “allowed-sink-caps”        GstCaps *

These are the GstCaps that can be fed into the session, they are used to filter the codecs to only those that can accepted those caps as input.

Flags: Read

### The `“allowed-src-caps”` property

      “allowed-src-caps”         GstCaps *

These are the GstCaps that the session can produce, they are used to filter the codecs to only those that can accepted those caps as output.

Flags: Read

### The `“codec-preferences”` property

      “codec-preferences”        FsCodecGList *

This is the current preferences list for the local codecs. It is set by the user to specify the codec options and priorities. The user may change its value with `fs_session_set_codec_preferences()` at any time during a session. It is a GList of FsCodec. The user must free this codec list using `fs_codec_list_destroy()` when done.

The payload type may be a valid dynamic PT (96-127), `FS_CODEC_ID_DISABLE` or `FS_CODEC_ID_ANY`. If the encoding name is "reserve-pt", then the payload type of the codec will be "reserved" and not be used by any dynamically assigned payload type.

[transfer full]

Flags: Read

### The `“codecs”` property

      “codecs”                   FsCodecGList *

This is the list of codecs used for this session. It will include the codecs and payload type used to receive media on this session. It will also include any configuration parameter that must be transmitted reliably for the other end to decode the content.

It may change when the codec preferences are set, when codecs are set on a FsStream in this session, when a FsStream is destroyed or asynchronously when new config data is discovered.

If any configuration parameter needs to be discovered, this property will be `NULL` until they have been discovered. One can always get the codecs from “codecs-without-config”. The "farstream-codecs-changed" message will be emitted whenever the value of this property changes.

It is a GList of FsCodec. User must free this codec list using `fs_codec_list_destroy()` when done.

[transfer full]

Flags: Read

### The `“codecs-without-config”` property

      “codecs-without-config”    FsCodecGList *

This is the same list of codecs as “codecs” without the configuration information that describes the data sent. It is suitable for configurations where a list of codecs is shared by many senders. If one is using codecs such as Theora, Vorbis or H.264 that require such information to be transmitted, the configuration data should be included in the stream and retransmitted regularly.

It may change when the codec preferences are set, when codecs are set on a FsStream in this session, when a FsStream is destroyed or asynchronously when new config data is discovered.

The "farstream-codecs-changed" message will be emitted whenever the value of this property changes.

It is a GList of FsCodec. User must free this codec list using `fs_codec_list_destroy()` when done.

[transfer full]

Flags: Read

### The `“conference”` property

      “conference”               FsConference *

The FsConference parent of this session. This property is a construct param and is read-only.

Flags: Read / Write / Construct Only

### The `“current-send-codec”` property

      “current-send-codec”       FsCodec *

Indicates the currently active send codec. A user can change the active send codec by calling `fs_session_set_send_codec()`. The send codec could also be automatically changed by Farstream. This property is an FsCodec. User must free the codec using `fs_codec_destroy()` when done. The "farstream-send-codec-changed" message is emitted on the bus when the value of this property changes.

Flags: Read

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

      “encryption-parameters”    GstStructure *

Retrieves previously set encryption parameters

Flags: Read

### The `“id”` property

      “id”                       guint

The ID of the session, the first number of the pads linked to this session will be this id

Flags: Read / Write / Construct Only

Default value: 0

### The `“media-type”` property

      “media-type”               FsMediaType

The media-type of the session. This is either Audio, Video or both. This is a constructor parameter that cannot be changed.

Flags: Read / Write / Construct Only

Default value: FS_MEDIA_TYPE_AUDIO

### The `“sink-pad”` property

      “sink-pad”                 GstPad *

The Gstreamer sink pad that must be used to send media data on this session. User must unref this GstPad when done with it.

Flags: Read

### The `“tos”` property

      “tos”                      guint

Sets the IP ToS field (and if possible the IPv6 TCLASS field

Flags: Read / Write

Allowed values: <= 255

Default value: 0

## Signal Details

### The `“error”` signal

    void
    user_function (FsSession *self,
                   GObject   *object,
                   FsError    error_no,
                   gchar     *error_msg,
                   gpointer   user_data)

This signal is emitted in any error condition, it can be emitted on any thread. Applications should listen to the GstBus for errors.

#### Parameters

self | FsSession that emitted the signal |
object | The Gobject that emitted the signal |
error_no | The number of the error |
error_msg | Error message |
user_data | user data set when the signal handler was connected. |

Flags: Run Last