Farstream.Session

g Farstream.Session Farstream.Session GObject.Object GObject.Object GObject.Object->Farstream.Session

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

codecs_need_resend (old_codecs, new_codecs)

destroy ()

emit_error (error_no, error_msg)

get_stream_transmitter_type (transmitter)

list_transmitters ()

new_stream (participant, direction)

parse_codecs_changed (message)

parse_send_codec_changed (message)

parse_telephony_event_started (message)

parse_telephony_event_stopped (message)

set_allowed_caps (sink_caps, src_caps)

set_codec_preferences (codec_preferences)

set_encryption_parameters (parameters)

set_send_codec (send_codec)

start_telephony_event (event, volume)

stop_telephony_event ()

Virtual Methods

Inherited:

GObject.Object (7)

do_codecs_need_resend (old_codecs, new_codecs)

do_get_stream_transmitter_type (transmitter)

do_list_transmitters ()

do_new_stream (participant, direction)

do_set_allowed_caps (sink_caps, src_caps)

do_set_codec_preferences (codec_preferences)

do_set_encryption_parameters (parameters)

do_set_send_codec (send_codec)

do_start_telephony_event (event, volume)

do_stop_telephony_event ()

Properties

Name

Type

Flags

Short Description

allowed-sink-caps

Gst.Caps

r

Gst.Caps that can be fed into the session

allowed-src-caps

Gst.Caps

r

Gst.Caps that the session can produce

codec-preferences

r

A GLib.List of FsCodecs that allows user to set his codec options and priorities

codecs

r

A GLib.List of FsCodecs indicating the codecs for this session

codecs-without-config

r

A GLib.List of FsCodecs indicating the codecs for this session without any configuration data

conference

Farstream.Conference

r/w/co

The Conference this stream refers to

current-send-codec

Farstream.Codec

r

An Farstream.Codec indicating the currently active send codec

encryption-parameters

Gst.Structure

r

Parameters used to encrypt the stream

id

int

r/w/co

This ID is used on pad related to this session

media-type

Farstream.MediaType

r/w/co

An enum that specifies the media type of the session

sink-pad

Gst.Pad

r

A pad used for sending data on this session

tos

int

r/w

The IP Type of Service to set on sent packets

Signals

Inherited:

GObject.Object (1)

Name

Short Description

error

This signal is emitted in any error condition, it can be emitted on any thread.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent

GObject.Object

r

Class Details

class Farstream.Session(**kwargs)
Bases:

GObject.Object

Abstract:

Yes

Structure:

Farstream.SessionClass

All members are private, access them using methods and properties

codecs_need_resend(old_codecs, new_codecs)
Parameters:
Returns:

A new GLib.List of Farstream.Codec that need to be resent or None if there are none. This list must be freed with fs_codec_list_destroy().

Return type:

[Farstream.Codec]

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.

destroy()

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

emit_error(error_no, error_msg)
Parameters:

This function emit the “error” signal on a Farstream.Session, it should only be called by subclasses.

get_stream_transmitter_type(transmitter)
Parameters:

transmitter (str) – The name of the transmitter

Returns:

The GObject.GType of the stream transmitter

Return type:

GObject.GType

Returns the GObject.GType of the stream transmitter, bindings can use it to validate/convert the parameters passed to Farstream.Session.new_stream().

list_transmitters()
Returns:

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

Return type:

[str]

Get the list of all available transmitters for this session.

new_stream(participant, direction)
Parameters:
Raises:

GLib.Error

Returns:

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

Return type:

Farstream.Stream

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

parse_codecs_changed(message)
Parameters:

message (Gst.Message) – a Gst.Message to parse

Returns:

True if the message matches the session and is valid.

Return type:

bool

Parses a “farstream-codecs-changed” message and checks if it matches the self parameters.

parse_send_codec_changed(message)
Parameters:

message (Gst.Message) – a Gst.Message to parse

Returns:

True if the message matches the session and is valid.

codec:

Returns the Farstream.Codec in the message if not None.

secondary_codecs:

Returns a GLib.List of Farstream.Codec of the message if not None

Return type:

(bool, codec: Farstream.Codec, secondary_codecs: [Farstream.Codec])

Parses a “farstream-send-codec-changed” message and checks if it matches the self parameters.

parse_telephony_event_started(message)
Parameters:

message (Gst.Message) – a Gst.Message to parse

Returns:

True if the message matches the session and is valid.

method:

Returns the Farstream.DTMFMethod in the message if not None.

event:

Returns the Farstream.DTMFEvent in the message if not None.

volume:

Returns the volume in the message if not None.

Return type:

(bool, method: Farstream.DTMFMethod, event: Farstream.DTMFEvent, volume: int)

Parses a “farstream-telephony-event-started” message and checks if it matches the self parameters.

parse_telephony_event_stopped(message)
Parameters:

message (Gst.Message) – a Gst.Message to parse

Returns:

True if the message matches the session and is valid.

method:

Returns the Farstream.DTMFMethod in the message if not None.

Return type:

(bool, method: Farstream.DTMFMethod)

Parses a “farstream-telephony-event-stopped” message and checks if it matches the self parameters.

set_allowed_caps(sink_caps, src_caps)
Parameters:
Raises:

GLib.Error

Returns:

True if the new filter caps were acceptable.

Return type:

bool

Sets the allowed caps for the sink and source pads for this Farstream.Session. 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 Farstream.Session :codecs property and so only those will be negotiated.

If None 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 Farstream.Session :allowed-src-caps and Farstream.Session :allowed-sink-caps properties.

set_codec_preferences(codec_preferences)
Parameters:

codec_preferences ([Farstream.Codec] or None) – a GLib.List of Farstream.Codec with the desired configuration

Raises:

GLib.Error

Returns:

True on success, False on error.

Return type:

bool

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 GLib.List of Farstream.Codec. 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), Farstream.CODEC_ID_DISABLE or Farstream.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.

set_encryption_parameters(parameters)
Parameters:

parameters (Gst.Structure or None) – a Gst.Structure containing the encryption parameters or None to disable encryption

Raises:

GLib.Error

Returns:

True if the encryption parameters could be set, False otherwise

Return type:

bool

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

set_send_codec(send_codec)
Parameters:

send_codec (Farstream.Codec) – a Farstream.Codec representing the codec to send

Raises:

GLib.Error

Returns:

False if the send codec couldn’t be set.

Return type:

bool

This function will set the currently being sent codec for all streams in this session. The given Farstream.Codec 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.

start_telephony_event(event, volume)
Parameters:

  • event (int) – A #FsStreamDTMFEvent or another number defined at http://www.iana.org/assignments/audio-telephone-event-registry

  • volume (int) – 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 Farstream.Stream does not support this telephony event.

Return type:

bool

This function will start sending a telephony event (such as a DTMF tone) on the Farstream.Session. You have to call the function Farstream.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.

stop_telephony_event()
Returns:

True if sucessful, it can return False if the Farstream.Session does not support telephony events or if no telephony event is being sent

Return type:

bool

This function will stop sending a telephony event started by Farstream.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.

do_codecs_need_resend(old_codecs, new_codecs) virtual
Parameters:
Returns:

A new GLib.List of Farstream.Codec that need to be resent or None if there are none. This list must be freed with fs_codec_list_destroy().

Return type:

[Farstream.Codec]

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.

do_get_stream_transmitter_type(transmitter) virtual
Parameters:

transmitter (str) – The name of the transmitter

Returns:

The GObject.GType of the stream transmitter

Return type:

GObject.GType

Returns the GObject.GType of the stream transmitter, bindings can use it to validate/convert the parameters passed to Farstream.Session.new_stream().

do_list_transmitters() virtual
Returns:

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

Return type:

[str]

Get the list of all available transmitters for this session.

do_new_stream(participant, direction) virtual
Parameters:
Returns:

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

Return type:

Farstream.Stream

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

do_set_allowed_caps(sink_caps, src_caps) virtual
Parameters:
Returns:

True if the new filter caps were acceptable.

Return type:

bool

Sets the allowed caps for the sink and source pads for this Farstream.Session. 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 Farstream.Session :codecs property and so only those will be negotiated.

If None 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 Farstream.Session :allowed-src-caps and Farstream.Session :allowed-sink-caps properties.

do_set_codec_preferences(codec_preferences) virtual
Parameters:

codec_preferences ([Farstream.Codec] or None) – a GLib.List of Farstream.Codec with the desired configuration

Returns:

True on success, False on error.

Return type:

bool

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 GLib.List of Farstream.Codec. 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), Farstream.CODEC_ID_DISABLE or Farstream.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.

do_set_encryption_parameters(parameters) virtual
Parameters:

parameters (Gst.Structure or None) – a Gst.Structure containing the encryption parameters or None to disable encryption

Returns:

True if the encryption parameters could be set, False otherwise

Return type:

bool

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

do_set_send_codec(send_codec) virtual
Parameters:

send_codec (Farstream.Codec) – a Farstream.Codec representing the codec to send

Returns:

False if the send codec couldn’t be set.

Return type:

bool

This function will set the currently being sent codec for all streams in this session. The given Farstream.Codec 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.

do_start_telephony_event(event, volume) virtual
Parameters:

  • event (int) – A #FsStreamDTMFEvent or another number defined at http://www.iana.org/assignments/audio-telephone-event-registry

  • volume (int) – 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 Farstream.Stream does not support this telephony event.

Return type:

bool

This function will start sending a telephony event (such as a DTMF tone) on the Farstream.Session. You have to call the function Farstream.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.

do_stop_telephony_event() virtual
Returns:

True if sucessful, it can return False if the Farstream.Session does not support telephony events or if no telephony event is being sent

Return type:

bool

This function will stop sending a telephony event started by Farstream.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.

Signal Details

Farstream.Session.signals.error(session, object, error_no, error_msg)
Signal Name:

error

Flags:

RUN_LAST

Parameters:

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

Property Details

Farstream.Session.props.allowed_sink_caps
Name:

allowed-sink-caps

Type:

Gst.Caps

Default Value:

None

Flags:

READABLE

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

Farstream.Session.props.allowed_src_caps
Name:

allowed-src-caps

Type:

Gst.Caps

Default Value:

None

Flags:

READABLE

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

Farstream.Session.props.codec_preferences
Name:

codec-preferences

Type:

Default Value:

None

Flags:

READABLE

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 Farstream.Session.set_codec_preferences() at any time during a session. It is a GLib.List of Farstream.Codec. 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), Farstream.CODEC_ID_DISABLE or Farstream.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.

Farstream.Session.props.codecs
Name:

codecs

Type:

Default Value:

None

Flags:

READABLE

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 Farstream.Stream in this session, when a Farstream.Stream is destroyed or asynchronously when new config data is discovered.

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

It is a GLib.List of Farstream.Codec. User must free this codec list using fs_codec_list_destroy() when done.

Farstream.Session.props.codecs_without_config
Name:

codecs-without-config

Type:

Default Value:

None

Flags:

READABLE

This is the same list of codecs as Farstream.Session :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 Farstream.Stream in this session, when a Farstream.Stream 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 GLib.List of Farstream.Codec. User must free this codec list using fs_codec_list_destroy() when done.

Farstream.Session.props.conference
Name:

conference

Type:

Farstream.Conference

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

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

Farstream.Session.props.current_send_codec
Name:

current-send-codec

Type:

Farstream.Codec

Default Value:

None

Flags:

READABLE

Indicates the currently active send codec. A user can change the active send codec by calling Farstream.Session.set_send_codec(). The send codec could also be automatically changed by Farstream. This property is an Farstream.Codec. 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.

Farstream.Session.props.encryption_parameters
Name:

encryption-parameters

Type:

Gst.Structure

Default Value:

None

Flags:

READABLE

Retrieves previously set encryption parameters

Farstream.Session.props.id
Name:

id

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

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

Farstream.Session.props.media_type
Name:

media-type

Type:

Farstream.MediaType

Default Value:

Farstream.MediaType.AUDIO

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

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

Farstream.Session.props.sink_pad
Name:

sink-pad

Type:

Gst.Pad

Default Value:

None

Flags:

READABLE

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

Farstream.Session.props.tos
Name:

tos

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE

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