FsCodec

FsCodec — Structure representing a media codec

Synopsis

#include <gst/farsight/fs-conference-iface.h>

struct              FsCodec;
enum                FsMediaType;
struct              FsCodecParameter;
struct              FsFeedbackParameter;
#define             FS_CODEC_ID_ANY
#define             FS_CODEC_ID_DISABLE
FsCodec *           fs_codec_new                        (int id,
                                                         const char *encoding_name,
                                                         FsMediaType media_type,
                                                         guint clock_rate);
void                fs_codec_destroy                    (FsCodec *codec);
FsCodec *           fs_codec_copy                       (const FsCodec *codec);
gboolean            fs_codec_are_equal                  (const FsCodec *codec1,
                                                         const FsCodec *codec2);
GList *             fs_codec_list_from_keyfile          (const gchar *filename,
                                                         GError **error);
void                fs_codec_list_destroy               (GList *codec_list);
GList *             fs_codec_list_copy                  (const GList *codec_list);
gboolean            fs_codec_list_are_equal             (GList *list1,
                                                         GList *list2);
gchar *             fs_codec_to_string                  (const FsCodec *codec);
void                fs_codec_add_optional_parameter     (FsCodec *codec,
                                                         const gchar *name,
                                                         const gchar *value);
void                fs_codec_remove_optional_parameter  (FsCodec *codec,
                                                         FsCodecParameter *param);
FsCodecParameter *  fs_codec_get_optional_parameter     (FsCodec *codec,
                                                         const gchar *name,
                                                         const gchar *value);
void                fs_codec_add_feedback_parameter     (FsCodec *codec,
                                                         const gchar *type,
                                                         const gchar *subtype,
                                                         const gchar *extra_params);
FsFeedbackParameter * fs_codec_get_feedback_parameter   (FsCodec *codec,
                                                         const gchar *type,
                                                         const gchar *subtype,
                                                         const gchar *extra_params);
void                fs_codec_remove_feedback_parameter  (FsCodec *codec,
                                                         GList *item);
#define             FS_CODEC_FORMAT
#define             FS_CODEC_ARGS                       (codec)
const gchar *       fs_media_type_to_string             (FsMediaType media_type);

Description

An FsCodec is a way to exchange codec information between the client and Farsight. The information specified in this structure is usually representative of the codec information exchanged in the signaling.

Details

struct FsCodec

struct FsCodec {
  gint id;
  char *encoding_name;
  FsMediaType media_type;
  guint clock_rate;
  guint channels;
  GList *optional_params;
};

This structure reprensents one codec that can be offered or received

gint id;

numeric identifier for encoding, eg. PT for SDP

char *encoding_name;

the name of the codec

FsMediaType media_type;

type of media this codec is for

guint clock_rate;

clock rate of this stream

guint channels;

Number of channels codec should decode

GList *optional_params;

key pairs of param name to param data

enum FsMediaType

typedef enum
{
  FS_MEDIA_TYPE_AUDIO,
  FS_MEDIA_TYPE_VIDEO,
  FS_MEDIA_TYPE_LAST = FS_MEDIA_TYPE_VIDEO
} FsMediaType;

Enum used to signify the media type of a codec or stream.

FS_MEDIA_TYPE_AUDIO

A media type that encodes audio.

FS_MEDIA_TYPE_VIDEO

A media type that encodes video.

FS_MEDIA_TYPE_LAST

Largest valid FsMediaType

struct FsCodecParameter

struct FsCodecParameter {
    gchar *name;
    gchar *value;
};

Used to store arbitary parameters for a codec

gchar *name;

paramter name.

gchar *value;

parameter value.

struct FsFeedbackParameter

struct FsFeedbackParameter {
  gchar *type;
  gchar *subtype;
  gchar *extra_params;
};

Use to store feedback parameters

gchar *type;

the type of feedback, like "ack", "name", "ccm"

gchar *subtype;

the subtype of feedback (can be an empty string)

gchar *extra_params;

a string containing extra parameters (can be empty)

FS_CODEC_ID_ANY

#define FS_CODEC_ID_ANY            (-1)

If the id of a FsCodec is FS_CODEC_ID_ANY, then it will be replaced with a dynamic payload type at runtime


FS_CODEC_ID_DISABLE

#define FS_CODEC_ID_DISABLE        (-2)

If the id of a FsCodec is FS_CODEC_ID_DISABLE, then this codec will not be used


fs_codec_new ()

FsCodec *           fs_codec_new                        (int id,
                                                         const char *encoding_name,
                                                         FsMediaType media_type,
                                                         guint clock_rate);

Allocates and initializes a FsCodec structure

id :

codec identifier, if RTP this should be based on IETF RTP payload types

encoding_name :

Name of media type this encodes

media_type :

FsMediaType for type of codec

clock_rate :

The clock rate this codec encodes at, if applicable

Returns :

A newly allocated FsCodec

fs_codec_destroy ()

void                fs_codec_destroy                    (FsCodec *codec);

Deletes a FsCodec structure and all its data. Is a no-op on NULL codec

codec :

FsCodec structure to free

fs_codec_copy ()

FsCodec *           fs_codec_copy                       (const FsCodec *codec);

Copies a FsCodec structure.

codec :

codec to copy

Returns :

a copy of the codec

fs_codec_are_equal ()

gboolean            fs_codec_are_equal                  (const FsCodec *codec1,
                                                         const FsCodec *codec2);

Compare two codecs, it will declare two codecs to be identical even if their optional parameters are in a different order. NULL encoding names are ignored.

codec1 :

First codec

codec2 :

Second codec

Returns :

TRUE of the codecs are identical, FALSE otherwise

fs_codec_list_from_keyfile ()

GList *             fs_codec_list_from_keyfile          (const gchar *filename,
                                                         GError **error);

Reads the content of a GKeyFile of the following format into a GList of FsCodec structures.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[audio/codec1]
clock-rate=8000

[audio/codec1:1]
clock-rate=16000

[audio/codec2]
one_param=QCIF
another_param=WOW

[video/codec3]
wierd_param=42
feedback:nack/pli=1
feedback:tfrc=

filename :

Name of the GKeyFile to read the codecs parameters from

error :

location of a GError, or NULL if no error occured

Returns :

The GList of FsCodec or NULL if the keyfile was empty or an error occured.

fs_codec_list_destroy ()

void                fs_codec_list_destroy               (GList *codec_list);

Deletes a list of FsCodec structures and the list itself. Does nothing on NULL lists.

codec_list :

a GList of FsCodec to delete

fs_codec_list_copy ()

GList *             fs_codec_list_copy                  (const GList *codec_list);

Copies a list of FsCodec structures.

codec_list :

a GList of FsCodec to copy

Returns :

The new list.

fs_codec_list_are_equal ()

gboolean            fs_codec_list_are_equal             (GList *list1,
                                                         GList *list2);

Verifies if two glist of fscodecs are identical

list1 :

a GList of FsCodec

list2 :

a GList of FsCodec

Returns :

TRUE if they are identical, FALSE otherwise

fs_codec_to_string ()

gchar *             fs_codec_to_string                  (const FsCodec *codec);

Returns a newly-allocated string representing the codec

codec :

A farsight codec

Returns :

the newly-allocated string

fs_codec_add_optional_parameter ()

void                fs_codec_add_optional_parameter     (FsCodec *codec,
                                                         const gchar *name,
                                                         const gchar *value);

This function adds an new optional parameter to a FsCodec

codec :

The FsCodec to add the parameter to

name :

The name of the optional parameter

value :

The extra_params of the optional parameter

fs_codec_remove_optional_parameter ()

void                fs_codec_remove_optional_parameter  (FsCodec *codec,
                                                         FsCodecParameter *param);

Removes an optional parameter from a codec.

NULL param will do nothing.

codec :

a FsCodec

param :

a pointer to the FsCodecParameter to remove

fs_codec_get_optional_parameter ()

FsCodecParameter *  fs_codec_get_optional_parameter     (FsCodec *codec,
                                                         const gchar *name,
                                                         const gchar *value);

Finds the FsCodecParameter in the FsCodec that has the requested name and, if not NULL, the requested value

codec :

a FsCodec

name :

The name of the parameter to search for

value :

The value of the parameter to search for or NULL for any value

Returns :

the FsCodecParameter from the FsCodec or NULL

fs_codec_add_feedback_parameter ()

void                fs_codec_add_feedback_parameter     (FsCodec *codec,
                                                         const gchar *type,
                                                         const gchar *subtype,
                                                         const gchar *extra_params);

This function adds an new feedback parameter to a FsCodec

codec :

The FsCodec to add the parameter to

type :

The type of the feedback parameter

subtype :

The subtype of the feedback parameter

extra_params :

The extra_params of the feeback parameter

fs_codec_get_feedback_parameter ()

FsFeedbackParameter * fs_codec_get_feedback_parameter   (FsCodec *codec,
                                                         const gchar *type,
                                                         const gchar *subtype,
                                                         const gchar *extra_params);

Finds the FsFeedbackParameter in the FsCodec that has the requested subtype, type and extra_params. One of which must be non-NULL;

codec :

a FsCodec

type :

The subtype of the parameter to search for or NULL for any type

subtype :

The subtype of the parameter to search for or NULL for any subtype

extra_params :

The extra_params of the parameter to search for or NULL for any extra_params

Returns :

the FsFeedbackParameter from the FsCodec or NULL

fs_codec_remove_feedback_parameter ()

void                fs_codec_remove_feedback_parameter  (FsCodec *codec,
                                                         GList *item);

Removes an optional parameter from a codec.

NULL param will do nothing.

codec :

a FsCodec

item :

a pointer to the GList element to remove that contains a FsFeedbackParameter

FS_CODEC_FORMAT

#define FS_CODEC_FORMAT "%d: %s %s clock:%d channels:%d params:%p"

A format that can be used in printf like format strings to format a FsCodec


FS_CODEC_ARGS()

#define             FS_CODEC_ARGS(codec)

Formats the codec in args for FS_CODEC_FORMAT

codec :

a FsCodec

fs_media_type_to_string ()

const gchar *       fs_media_type_to_string             (FsMediaType media_type);

Gives a user-printable string representing the media type

media_type :

A media type

Returns :

a static string representing the media type