The "farsight-send-codec-changed" message

1
2
3
4

"session"          <a class="link" href="farsight2-libs-fs-session.html#FsSession">FsSession</a>          The session that emits the message
"codec"            <a class="link" href="farsight2-libs-FsCodec.html#FsCodec" title="struct FsCodec">FsCodec</a>            The new send codec
"secondary-codecs" <GTKDOCLINK HREF="GList">GList</GTKDOCLINK>              A <GTKDOCLINK HREF="GList">GList</GTKDOCLINK> of <a class="link" href="farsight2-libs-FsCodec.html#FsCodec" title="struct FsCodec">FsCodec</a> (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 "farsight-codecs-changed" message

1

"session"          <a class="link" href="farsight2-libs-fs-session.html#FsSession">FsSession</a>          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, once should check the value of "codecs-ready" property to make sure all of the codecs configuration are ready and have been discovered before using the codecs. If its not TRUE, one should wait for the next "farsight-codecs-changed" message until reading the codecs.

enum FsDTMFEvent

typedef enum
{
  /*< protected >*/
  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

FsSession

typedef struct _FsSession 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,
                            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);
  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);
};

You must override at least new_stream in a subclass.

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.

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

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.

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.

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.

fs_session_list_transmitters ()

gchar **            fs_session_list_transmitters        (FsSession *session);

Get the list of all available transmitters for this session.

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().

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.

fs_session_emit_error ()

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

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

The "codec-preferences" property

  "codec-preferences"        FsCodecGList*         : Read

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.

The "codecs" property

  "codecs"                   FsCodecGList*         : Read

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.

You can only assume that the configuration parameters are valid when the "codecs-ready" property is TRUE. The "farsight-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.

The "codecs-ready" property

  "codecs-ready"             gboolean              : Read

Some codecs that have configuration data that needs to be sent reliably may need to be initialized from actual data before being ready. If your application uses such codecs, wait until this property is TRUE before using the "codecs" property. If the value if not TRUE, the "farsight-codecs-changed" message will be emitted when it becomes TRUE. You should re-check the value of this property when you receive the message.

Default value: TRUE

The "codecs-without-config" property

  "codecs-without-config"    FsCodecGList*         : Read

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 "farsight-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.

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. This property is an FsCodec. User must free the codec using fs_codec_destroy() when done. The "farsight-send-codec-changed" message is emitted on the bus when the value 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 "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 "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.

The "tos" property

  "tos"                      guint                 : Read / Write

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

Allowed values: <= 255

Default value: 0

The "error" signal

void                user_function                      (FsSession *self,
                                                        GObject   *object,
                                                        FsError    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.