FsCodec

## 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