FsSession

FsSession — A session in a conference

Synopsis




enum                FsDTMFEvent;
enum                FsDTMFMethod;
                    FsSession;
                    FsSessionClass;
FsStream*           fs_session_new_stream               (FsSession *session,
                                                         FsParticipant *participant,
                                                         FsStreamDirection direction,
                                                         const gchar *transmitter,
                                                         guint stream_transmitter_n_parameters,
                                                         GParameter *stream_transmitter_parameters,
                                                         GError **error);
gboolean            fs_session_start_telephony_event    (FsSession *session,
                                                         guint8 event,
                                                         guint8 volume,
                                                         FsDTMFMethod method);
gboolean            fs_session_stop_telephony_event     (FsSession *session,
                                                         FsDTMFMethod method);
gboolean            fs_session_set_send_codec           (FsSession *session,
                                                         FsCodec *send_codec,
                                                         GError **error);
void                fs_session_emit_error               (FsSession *session,
                                                         gint error_no,
                                                         gchar *error_msg,
                                                         gchar *debug_msg);

Object Hierarchy


  GObject
   +----FsSession

Properties


  "current-send-codec"       FsCodec               : Read
  "id"                       guint                 : Read / Write / Construct Only
  "local-codecs"             FsCodecGList          : Read
  "local-codecs-config"      FsCodecGList          : Read / Write
  "media-type"               FsMediaType           : Read / Write / Construct Only
  "negotiated-codecs"        FsCodecGList          : Read
  "sink-pad"                 GstPad                : Read

Signals


  "error"                                          : Run Last
  "new-negotiated-codecs"                          : Run Last
  "send-codec-changed"                             : Run Last

Description

This object is the base implementation of a Farsight Session. It needs to be derived and implemented by a farsight conference gstreamer element. A Farsight 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.

Details

enum FsDTMFEvent

typedef enum
{
  FS_DTMF_EVENT_0 = 0,
  FS_DTMF_EVENT_1 = 1,
  FS_DTMF_EVENT_2 = 2,
  FS_DTMF_EVENT_3 = 3,
  FS_DTMF_EVENT_4 = 4,
  FS_DTMF_EVENT_5 = 5,
  FS_DTMF_EVENT_6 = 6,
  FS_DTMF_EVENT_7 = 7,
  FS_DTMF_EVENT_8 = 8,
  FS_DTMF_EVENT_9 = 9,
  FS_DTMF_EVENT_STAR = 10,
  FS_DTMF_EVENT_POUND = 11,
  FS_DTMF_EVENT_A = 12,
  FS_DTMF_EVENT_B = 13,
  FS_DTMF_EVENT_C = 14,
  FS_DTMF_EVENT_D = 15
} 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


enum FsDTMFMethod

typedef enum
{
  FS_DTMF_METHOD_AUTO = 0,
  FS_DTMF_METHOD_RTP_RFC4733,
  FS_DTMF_METHOD_IN_BAND
} FsDTMFMethod;

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

FS_DTMF_METHOD_AUTO

Send in any possible way

FS_DTMF_METHOD_RTP_RFC4733

Send as a special payload type defined by RFC 4733 (which obsoletes RFC 2833)

FS_DTMF_METHOD_IN_BAND

Send as tones as in-band audio sound

FsSession

typedef struct _FsSession FsSession;

All members are private, access them using methods and properties


FsSessionClass

typedef struct {
  GObjectClass parent_class;

  /*virtual functions */
  FsStream *(* new_stream) (FsSession *session,
                            FsParticipant *participant,
                            FsStreamDirection direction,
                            const gchar *transmitter,
                            guint stream_transmitter_n_parameters,
                            GParameter *stream_transmitter_parameters,
                            GError **error);

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

  gboolean (* set_send_codec) (FsSession *session, FsCodec *send_codec,
                               GError **error);
} FsSessionClass;

You must override at least new_stream in a subclass.

GObjectClass parent_class;

Our parent

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

fs_session_new_stream ()

FsStream*           fs_session_new_stream               (FsSession *session,
                                                         FsParticipant *participant,
                                                         FsStreamDirection direction,
                                                         const gchar *transmitter,
                                                         guint stream_transmitter_n_parameters,
                                                         GParameter *stream_transmitter_parameters,
                                                         GError **error);

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

session :

an 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

transmitter :

Name of the type of transmitter to use for this session

stream_transmitter_n_parameters :

Number of parametrs passed to the stream transmitter

stream_transmitter_parameters :

an array of n_parameters GParameter struct that will be passed to the newly-create FsStreamTransmitter

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.

fs_session_start_telephony_event ()

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

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. This function will use any available method, if you want to use a specific method only, use fs_session_start_telephony_event_full()

session :

an 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

method :

The method used to send the event

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,
                                                         FsDTMFMethod method);

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.

session :

an FsSession

method :

The method used to send the event

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 negotiated-codecs property of the session. If the given codec is not in the negotiated 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.

session :

an FsSession

send_codec :

an 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_emit_error ()

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

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

session :

FsSession 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 "current-send-codec" property

  "current-send-codec"       FsCodec               : Read

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 Farsight. In both cases the ::send-codec-changed signal will be emited. This property is an FsCodec. User must free the codec using fs_codec_destroy() when done. The FsSession::send-codec-changed signal is emitted when the content of this property changes.


The "id" property

  "id"                       guint                 : Read / Write / Construct Only

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

Default value: 0


The "local-codecs" property

  "local-codecs"             FsCodecGList          : Read

This is the list of local codecs that have been auto-detected based on installed GStreamer plugins. This list is unchanged during the lifecycle of the session unless local-codecs-config is changed by the user. It is a GList of FsCodec. User must free this codec list using fs_codec_list_destroy() when done.


The "local-codecs-config" property

  "local-codecs-config"      FsCodecGList          : Read / Write

This is the current configuration list for the local codecs. It is usually set by the user to specify the codec options and priorities. The user may change this value during an ongoing session. Note that doing this can cause the local-codecs to be changed. Therefore this requires the user to fetch the new local-codecs and renegotiate them with the peers. It is a GList of FsCodec. User must free this codec list using fs_codec_list_destroy() when done.


The "media-type" property

  "media-type"               FsMediaType           : Read / Write / Construct Only

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

Default value: FS_MEDIA_TYPE_AUDIO


The "negotiated-codecs" property

  "negotiated-codecs"        FsCodecGList          : Read

This list indicated what codecs have been successfully negotiated with the session participants. This list can change based on participants joining/leaving the session. It is a GList of FsCodec. User must free this codec list using fs_codec_list_destroy() when done. The FsSession::new-negotiated-codecs signal is emited when the content of this property changes.


The "sink-pad" property

  "sink-pad"                 GstPad                : Read

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

Signal Details

The "error" signal

void                user_function                      (FsSession *self,
                                                        GObject   *object,
                                                        gint       error_no,
                                                        gchar     *error_msg,
                                                        gchar     *debug_msg,
                                                        gpointer   user_data)      : Run Last

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

self :

FsSession that emitted the signal

object :

The Gobject that emitted the signal

error_no :

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 "new-negotiated-codecs" signal

void                user_function                      (FsSession *self,
                                                        gpointer   user_data)      : Run Last

This signal is emitted when the negotiated codecs list has changed for this session. This can happen when new remote codecs are added to the session (i.e. When a session is being initialized or a new participant joins an existing session). The user should look at the FsSession:negotiated-codecs property to determine what the new negotiated codec list is.

self :

FsSession that emitted the signal

user_data :

user data set when the signal handler was connected.

The "send-codec-changed" signal

void                user_function                      (FsSession *self,
                                                        gpointer   user_data)      : Run Last

This signal is emitted when the active send codec has been changed manually by the user or automatically for QoS purposes. The user should look at the FsSession:current-send-codec property in the session to determine what the new active codec is

self :

FsSession that emitted the signal

user_data :

user data set when the signal handler was connected.