libs/taglib/bindings/c/tag_c.h

   1 /***************************************************************************
   2     copyright            : (C) 2003 by Scott Wheeler
   3     email                : wheeler@kde.org
   4  ***************************************************************************/
   5
   6 /***************************************************************************
   7  *   This library is free software; you can redistribute it and/or modify  *
   8  *   it  under the terms of the GNU Lesser General Public License version  *
   9  *   2.1 as published by the Free Software Foundation.                     *
  10  *                                                                         *
  11  *   This library is distributed in the hope that it will be useful, but   *
  12  *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
  14  *   Lesser General Public License for more details.                       *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU Lesser General Public      *
  17  *   License along with this library; if not, write to the Free Software   *
  18  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
  19  *   USA                                                                   *
  20  ***************************************************************************/
  21
  22 #ifndef TAGLIB_TAG_C
  23 #define TAGLIB_TAG_C
  24
  25 /* Do not include this in the main TagLib documentation. */
  26 #ifndef DO_NOT_DOCUMENT
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #if defined(_WIN32) || defined(_WIN64)
  33 #ifdef MAKE_TAGLIB_C_LIB
  34 #define TAGLIB_C_EXPORT __declspec(dllexport)
  35 #else
  36 #define TAGLIB_C_EXPORT __declspec(dllimport)
  37 #endif
  38 #else
  39 #define TAGLIB_C_EXPORT
  40 #endif
  41
  42 #ifndef BOOL
  43 #define BOOL int
  44 #endif
  45
  46 /*******************************************************************************
  47  * [ TagLib C Binding ]
  48  *
  49  * This is an interface to TagLib's "simple" API, meaning that you can read and
  50  * modify media files in a generic, but not specialized way.  This is a rough
  51  * representation of TagLib::File and TagLib::Tag, for which the documentation
  52  * is somewhat more complete and worth consulting.
  53  *******************************************************************************/
  54
  55 /*
  56  * These are used for type provide some type safety to the C API (as opposed to
  57  * using void *, but pointers to them are simply cast to the corresponding C++
  58  * types in the implementation.
  59  */
  60
  61 typedef struct { int dummy; } TagLib_File;
  62 typedef struct { int dummy; } TagLib_Tag;
  63 typedef struct { int dummy; } TagLib_AudioProperties;
  64
  65 /*!
  66  * By default all strings coming into or out of TagLib's C API are in UTF8.
  67  * However, it may be desirable for TagLib to operate on Latin1 (ISO-8859-1)
  68  * strings in which case this should be set to FALSE.
  69  */
  70 TAGLIB_C_EXPORT void taglib_set_strings_unicode(BOOL unicode);
  71
  72 /*!
  73  * TagLib can keep track of strings that are created when outputting tag values
  74  * and clear them using taglib_tag_clear_strings().  This is enabled by default.
  75  * However if you wish to do more fine grained management of strings, you can do
  76  * so by setting \a management to FALSE.
  77  */
  78 TAGLIB_C_EXPORT void taglib_set_string_management_enabled(BOOL management);
  79
  80 /*******************************************************************************
  81  * File API
  82  ******************************************************************************/
  83
  84 typedef enum {
  85   TagLib_File_MPEG,
  86   TagLib_File_OggVorbis,
  87   TagLib_File_FLAC,
  88   TagLib_File_MPC,
  89   TagLib_File_OggFlac,
  90   TagLib_File_WavPack,
  91   TagLib_File_Speex,
  92   TagLib_File_TrueAudio
  93 } TagLib_File_Type;
  94
  95 /*!
  96  * Creates a TagLib file based on \a filename.  TagLib will try to guess the file
  97  * type.
  98  *
  99  * \returns NULL if the file type cannot be determined or the file cannot
 100  * be opened.
 101  */
 102 TAGLIB_C_EXPORT TagLib_File *taglib_file_new(const char *filename);
 103
 104 /*!
 105  * Creates a TagLib file based on \a filename.  Rather than attempting to guess
 106  * the type, it will use the one specified by \a type.
 107  */
 108 TAGLIB_C_EXPORT TagLib_File *taglib_file_new_type(const char *filename, TagLib_File_Type type);
 109
 110 /*!
 111  * Frees and closes the file.
 112  */
 113 TAGLIB_C_EXPORT void taglib_file_free(TagLib_File *file);
 114
 115 /*!
 116  * Returns true if the file is open and readble and valid information for
 117  * the Tag and / or AudioProperties was found.
 118  */
 119
 120 TAGLIB_C_EXPORT BOOL taglib_file_is_valid(const TagLib_File *file);
 121
 122 /*!
 123  * Returns a pointer to the tag associated with this file.  This will be freed
 124  * automatically when the file is freed.
 125  */
 126 TAGLIB_C_EXPORT TagLib_Tag *taglib_file_tag(const TagLib_File *file);
 127
 128 /*!
 129  * Returns a pointer to the the audio properties associated with this file.  This
 130  * will be freed automatically when the file is freed.
 131  */
 132 TAGLIB_C_EXPORT const TagLib_AudioProperties *taglib_file_audioproperties(const TagLib_File *file);
 133
 134 /*!
 135  * Saves the \a file to disk.
 136  */
 137 TAGLIB_C_EXPORT BOOL taglib_file_save(TagLib_File *file);
 138
 139 /******************************************************************************
 140  * Tag API
 141  ******************************************************************************/
 142
 143 /*!
 144  * Returns a string with this tag's title.
 145  *
 146  * \note By default this string should be UTF8 encoded and its memory should be
 147  * freed using taglib_tag_free_strings().
 148  */
 149 TAGLIB_C_EXPORT char *taglib_tag_title(const TagLib_Tag *tag);
 150
 151 /*!
 152  * Returns a string with this tag's artist.
 153  *
 154  * \note By default this string should be UTF8 encoded and its memory should be
 155  * freed using taglib_tag_free_strings().
 156  */
 157 TAGLIB_C_EXPORT char *taglib_tag_artist(const TagLib_Tag *tag);
 158
 159 /*!
 160  * Returns a string with this tag's album name.
 161  *
 162  * \note By default this string should be UTF8 encoded and its memory should be
 163  * freed using taglib_tag_free_strings().
 164  */
 165 TAGLIB_C_EXPORT char *taglib_tag_album(const TagLib_Tag *tag);
 166
 167 /*!
 168  * Returns a string with this tag's comment.
 169  *
 170  * \note By default this string should be UTF8 encoded and its memory should be
 171  * freed using taglib_tag_free_strings().
 172  */
 173 TAGLIB_C_EXPORT char *taglib_tag_comment(const TagLib_Tag *tag);
 174
 175 /*!
 176  * Returns a string with this tag's genre.
 177  *
 178  * \note By default this string should be UTF8 encoded and its memory should be
 179  * freed using taglib_tag_free_strings().
 180  */
 181 TAGLIB_C_EXPORT char *taglib_tag_genre(const TagLib_Tag *tag);
 182
 183 /*!
 184  * Returns the tag's year or 0 if year is not set.
 185  */
 186 TAGLIB_C_EXPORT unsigned int taglib_tag_year(const TagLib_Tag *tag);
 187
 188 /*!
 189  * Returns the tag's track number or 0 if track number is not set.
 190  */
 191 TAGLIB_C_EXPORT unsigned int taglib_tag_track(const TagLib_Tag *tag);
 192
 193 /*!
 194  * Sets the tag's title.
 195  *
 196  * \note By default this string should be UTF8 encoded.
 197  */
 198 TAGLIB_C_EXPORT void taglib_tag_set_title(TagLib_Tag *tag, const char *title);
 199
 200 /*!
 201  * Sets the tag's artist.
 202  *
 203  * \note By default this string should be UTF8 encoded.
 204  */
 205 TAGLIB_C_EXPORT void taglib_tag_set_artist(TagLib_Tag *tag, const char *artist);
 206
 207 /*!
 208  * Sets the tag's album.
 209  *
 210  * \note By default this string should be UTF8 encoded.
 211  */
 212 TAGLIB_C_EXPORT void taglib_tag_set_album(TagLib_Tag *tag, const char *album);
 213
 214 /*!
 215  * Sets the tag's comment.
 216  *
 217  * \note By default this string should be UTF8 encoded.
 218  */
 219 TAGLIB_C_EXPORT void taglib_tag_set_comment(TagLib_Tag *tag, const char *comment);
 220
 221 /*!
 222  * Sets the tag's genre.
 223  *
 224  * \note By default this string should be UTF8 encoded.
 225  */
 226 TAGLIB_C_EXPORT void taglib_tag_set_genre(TagLib_Tag *tag, const char *genre);
 227
 228 /*!
 229  * Sets the tag's year.  0 indicates that this field should be cleared.
 230  */
 231 TAGLIB_C_EXPORT void taglib_tag_set_year(TagLib_Tag *tag, unsigned int year);
 232
 233 /*!
 234  * Sets the tag's track number.  0 indicates that this field should be cleared.
 235  */
 236 TAGLIB_C_EXPORT void taglib_tag_set_track(TagLib_Tag *tag, unsigned int track);
 237
 238 /*!
 239  * Frees all of the strings that have been created by the tag.
 240  */
 241 TAGLIB_C_EXPORT void taglib_tag_free_strings(void);
 242
 243 /******************************************************************************
 244  * Audio Properties API
 245  ******************************************************************************/
 246
 247 /*!
 248  * Returns the length of the file in seconds.
 249  */
 250 TAGLIB_C_EXPORT int taglib_audioproperties_length(const TagLib_AudioProperties *audioProperties);
 251
 252 /*!
 253  * Returns the bitrate of the file in kb/s.
 254  */
 255 TAGLIB_C_EXPORT int taglib_audioproperties_bitrate(const TagLib_AudioProperties *audioProperties);
 256
 257 /*!
 258  * Returns the sample rate of the file in Hz.
 259  */
 260 TAGLIB_C_EXPORT int taglib_audioproperties_samplerate(const TagLib_AudioProperties *audioProperties);
 261
 262 /*!
 263  * Returns the number of channels in the audio stream.
 264  */
 265 TAGLIB_C_EXPORT int taglib_audioproperties_channels(const TagLib_AudioProperties *audioProperties);
 266
 267 /*******************************************************************************
 268  * Special convenience ID3v2 functions
 269  *******************************************************************************/
 270
 271 typedef enum {
 272   TagLib_ID3v2_Latin1,
 273   TagLib_ID3v2_UTF16,
 274   TagLib_ID3v2_UTF16BE,
 275   TagLib_ID3v2_UTF8
 276 } TagLib_ID3v2_Encoding;
 277
 278 /*!
 279  * This sets the default encoding for ID3v2 frames that are written to tags.
 280  */
 281
 282 TAGLIB_C_EXPORT void taglib_id3v2_set_default_text_encoding(TagLib_ID3v2_Encoding encoding);
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287 #endif /* DO_NOT_DOCUMENT */
 288 #endif