Farstream Reference Manual: FsCodec

## FsCodec FsCodec — Structure representing a media codec |

## Functions

#define | FS_CODEC_ID_ANY
#define | FS_CODEC_ID_DISABLE
FsCodec * | fs_codec_new ()
void | fs_codec_destroy ()
FsCodec * | fs_codec_copy ()
gboolean | fs_codec_are_equal ()
GList * | fs_codec_list_from_keyfile ()
void | fs_codec_list_destroy ()
GList * | fs_codec_list_copy ()
gboolean | fs_codec_list_are_equal ()
gchar * | fs_codec_to_string ()
void | fs_codec_add_optional_parameter ()
void | fs_codec_remove_optional_parameter ()
FsCodecParameter * | fs_codec_get_optional_parameter ()
FsCodecParameter * | fs_codec_parameter_copy ()
void | fs_codec_parameter_free ()
void | fs_codec_add_feedback_parameter ()
FsFeedbackParameter * | fs_codec_get_feedback_parameter ()
void | fs_codec_remove_feedback_parameter ()
FsFeedbackParameter * | fs_feedback_parameter_copy ()
void | fs_feedback_parameter_free ()
#define | FS_CODEC_ARGS()
const gchar * | fs_media_type_to_string ()

## Types and Values

struct | FsCodec
enum | FsMediaType
struct | FsCodecParameter
struct | FsFeedbackParameter
#define | FS_CODEC_FORMAT

## Includes

    #include <farstream/fs-conference.h>

## Description

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

## Functions

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

#### Parameters

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

#### Parameters

codec | FsCodec structure to free |

### fs_codec_copy ()

    FsCodec *
    fs_codec_copy (const FsCodec *codec);

Copies a FsCodec structure.

#### Parameters

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.

#### Parameters

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=

#### Parameters

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.

[element-type FsCodec][transfer full]

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

#### Parameters

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.

#### Parameters

codec_list | a GList of FsCodec to copy. | [transfer none][element-type FsCodec]

#### Returns

The new list.

[element-type FsCodec][transfer full]

### fs_codec_list_are_equal ()

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

Verifies if two glist of fscodecs are identical

#### Parameters

list1 | a GList of FsCodec. | [element-type FsCodec][allow-none]
list2 | a GList of FsCodec. | [element-type FsCodec][allow-none]

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

#### Parameters

codec | A farstream 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

#### Parameters

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.

#### Parameters

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

#### Parameters

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. | [allow-none]

#### Returns

the FsCodecParameter from the FsCodec or `NULL`.

[transfer none]

### fs_codec_parameter_copy ()

    FsCodecParameter *
    fs_codec_parameter_copy (const FsCodecParameter *param);

Makes a copy of a FsCodecParameter

#### Parameters

param | a FsCodecParameter |

#### Returns

a newly allocated FsCodecParameter

### fs_codec_parameter_free ()

    void
    fs_codec_parameter_free (FsCodecParameter *param);

Frees a FsCodecParameter

#### Parameters

param | a FsCodecParameter to free |

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

#### Parameters

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;

#### Parameters

codec | a FsCodec |
type | The subtype of the parameter to search for or `NULL` for any type. | [allow-none]
subtype | The subtype of the parameter to search for or `NULL` for any subtype. | [allow-none]
extra_params | The extra_params of the parameter to search for or `NULL` for any extra_params. | [allow-none]

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

#### Parameters

codec | a FsCodec |
item | a pointer to the GList element to remove that contains a FsFeedbackParameter. | [transfer none][element-type FsFeedbackParameter]

### fs_feedback_parameter_copy ()

    FsFeedbackParameter *
    fs_feedback_parameter_copy (const FsFeedbackParameter *param);

Makes a copy of a FsFeedbackParameter

#### Parameters

param | a FsFeedbackParameter |

#### Returns

a newly allocated FsFeedbackParameter

### fs_feedback_parameter_free ()

    void
    fs_feedback_parameter_free (FsFeedbackParameter *param);

Frees a FsFeedbackParameter

#### Parameters

param | a FsFeedbackParameter to free |

### FS_CODEC_ARGS()

    #define             FS_CODEC_ARGS(codec)

Formats the codec in args for FS_CODEC_FORMAT

#### Parameters

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

#### Parameters

media_type | A media type |

#### Returns

a static string representing the media type

## Types and Values

### struct FsCodec

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

This structure reprensents one codec that can be offered or received

#### Members

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 |
guint `minimum_reporting_interval`; | The minimum interval between two RTCP reports, If it is not specified (G_MAXUINT), it is up to the protocol to decide (it is 5 seconds for RTP). |
GList *`optional_params`; | key pairs of param name to param data. | [element-type FsCodecParameter]
GList *`feedback_params`; | key triplets of feedbck param type, subtype and extra string that is supported for this codec. | [element-type FsFeedbackParameter]

### enum FsMediaType

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

#### Members

FS_MEDIA_TYPE_AUDIO | A media type that encodes audio. |
FS_MEDIA_TYPE_VIDEO | A media type that encodes video. |
FS_MEDIA_TYPE_APPLICATION | A media type for application data. |
FS_MEDIA_TYPE_LAST | Largest valid FsMediaType |

### struct FsCodecParameter

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

Used to store arbitary parameters for a codec

#### Members

gchar *`name`; | paramter name. |
gchar *`value`; | parameter value. |

### struct FsFeedbackParameter

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

Use to store feedback parameters

#### Members

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