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