libpurple/media/codec.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef _PURPLE_MEDIA_CODEC_H_
  23 #define _PURPLE_MEDIA_CODEC_H_
  24 /**
  25  * SECTION:codec
  26  * @section_id: libpurple-codec
  27  * @short_description: <filename>media/codec.h</filename>
  28  * @title: Codec for Media API
  29  */
  30
  31 #include "enum-types.h"
  32
  33 /**
  34  * PurpleMediaCodec:
  35  *
  36  * An opaque structure representing an audio or video codec.
  37  */
  38 typedef struct _PurpleMediaCodec PurpleMediaCodec;
  39
  40 #include "../util.h"
  41
  42 #include <glib-object.h>
  43
  44 G_BEGIN_DECLS
  45
  46 #define PURPLE_TYPE_MEDIA_CODEC            (purple_media_codec_get_type())
  47 #define PURPLE_IS_MEDIA_CODEC(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_CODEC))
  48 #define PURPLE_IS_MEDIA_CODEC_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA_CODEC))
  49 #define PURPLE_MEDIA_CODEC(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_CODEC, PurpleMediaCodec))
  50 #define PURPLE_MEDIA_CODEC_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA_CODEC, PurpleMediaCodec))
  51 #define PURPLE_MEDIA_CODEC_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA_CODEC, PurpleMediaCodec))
  52
  53
  54 /**
  55  * purple_media_codec_get_type:
  56  *
  57  * Gets the type of the media codec structure.
  58  *
  59  * Returns: The media codec's GType
  60  */
  61 GType purple_media_codec_get_type(void);
  62
  63 /**
  64  * purple_media_codec_new:
  65  * @id: Codec identifier.
  66  * @encoding_name: Name of the media type this encodes.
  67  * @media_type: PurpleMediaSessionType of this codec.
  68  * @clock_rate: The clock rate this codec encodes at, if applicable.
  69  *
  70  * Creates a new PurpleMediaCodec instance.
  71  *
  72  * Returns: The newly created PurpleMediaCodec.
  73  */
  74 PurpleMediaCodec *purple_media_codec_new(int id, const char *encoding_name,
  75                 PurpleMediaSessionType media_type, guint clock_rate);
  76
  77 /**
  78  * purple_media_codec_get_id:
  79  * @codec: The codec to get the id from.
  80  *
  81  * Gets the codec id.
  82  *
  83  * Returns: The codec id.
  84  */
  85 guint purple_media_codec_get_id(PurpleMediaCodec *codec);
  86
  87 /**
  88  * purple_media_codec_get_encoding_name:
  89  * @codec: The codec to get the encoding name from.
  90  *
  91  * Gets the encoding name.
  92  *
  93  * Returns: The encoding name.
  94  */
  95 gchar *purple_media_codec_get_encoding_name(PurpleMediaCodec *codec);
  96
  97 /**
  98  * purple_media_codec_get_clock_rate:
  99  * @codec: The codec to get the clock rate from.
 100  *
 101  * Gets the clock rate.
 102  *
 103  * Returns: The clock rate.
 104  */
 105 guint purple_media_codec_get_clock_rate(PurpleMediaCodec *codec);
 106
 107 /**
 108  * purple_media_codec_get_channels:
 109  * @codec: The codec to get the number of channels from.
 110  *
 111  * Gets the number of channels.
 112  *
 113  * Returns: The number of channels.
 114  */
 115 guint purple_media_codec_get_channels(PurpleMediaCodec *codec);
 116
 117 /**
 118  * purple_media_codec_get_optional_parameters:
 119  * @codec: The codec to get the optional parameters from.
 120  *
 121  * Gets a list of the optional parameters.
 122  *
 123  * The list consists of PurpleKeyValuePair's.
 124  *
 125  * Returns: The list of optional parameters. The list is owned by the codec and
 126  *         should not be freed.
 127  */
 128 GList *purple_media_codec_get_optional_parameters(PurpleMediaCodec *codec);
 129
 130 /**
 131  * purple_media_codec_add_optional_parameter:
 132  * @codec: The codec to add the parameter to.
 133  * @name: The name of the parameter to add.
 134  * @value: The value of the parameter to add.
 135  *
 136  * Adds an optional parameter to the codec.
 137  */
 138 void purple_media_codec_add_optional_parameter(PurpleMediaCodec *codec,
 139                 const gchar *name, const gchar *value);
 140
 141 /**
 142  * purple_media_codec_remove_optional_parameter:
 143  * @codec: The codec to remove the parameter from.
 144  * @param: A pointer to the parameter to remove.
 145  *
 146  * Removes an optional parameter from the codec.
 147  */
 148 void purple_media_codec_remove_optional_parameter(PurpleMediaCodec *codec,
 149                 PurpleKeyValuePair *param);
 150
 151 /**
 152  * purple_media_codec_get_optional_parameter:
 153  * @codec: The codec to find the parameter in.
 154  * @name: The name of the parameter to search for.
 155  * @value: The value to search for or NULL.
 156  *
 157  * Gets an optional parameter based on the values given.
 158  *
 159  * Returns: The value found or NULL.
 160  */
 161 PurpleKeyValuePair *purple_media_codec_get_optional_parameter(
 162                 PurpleMediaCodec *codec, const gchar *name,
 163                 const gchar *value);
 164
 165 /**
 166  * purple_media_codec_copy:
 167  * @codec: The codec to copy.
 168  *
 169  * Copies a PurpleMediaCodec object.
 170  *
 171  * Returns: The copy of the codec.
 172  */
 173 PurpleMediaCodec *purple_media_codec_copy(PurpleMediaCodec *codec);
 174
 175 /**
 176  * purple_media_codec_list_copy:
 177  * @codecs: The list of codecs to be copied.
 178  *
 179  * Copies a GList of PurpleMediaCodec and its contents.
 180  *
 181  * Returns: The copy of the GList.
 182  */
 183 GList *purple_media_codec_list_copy(GList *codecs);
 184
 185 /**
 186  * purple_media_codec_list_free:
 187  * @codecs: The list of codecs to be freed.
 188  *
 189  * Frees a GList of PurpleMediaCodec and its contents.
 190  */
 191 void purple_media_codec_list_free(GList *codecs);
 192
 193 /**
 194  * purple_media_codec_to_string:
 195  * @codec: The codec to create the string of.
 196  *
 197  * Creates a string representation of the codec.
 198  *
 199  * Returns: The new string representation.
 200  */
 201 gchar *purple_media_codec_to_string(const PurpleMediaCodec *codec);
 202
 203 G_END_DECLS
 204
 205 #endif  /* _PURPLE_MEDIA_CODEC_H_ */
 206