/*************************************************************************** copyright : (C) 2003 by Scott Wheeler email : wheeler@kde.org ***************************************************************************/ /*************************************************************************** * This library is free software; you can redistribute it and/or modify * * it under the terms of the GNU Lesser General Public License version * * 2.1 as published by the Free Software Foundation. * * * * This library is distributed in the hope that it will be useful, but * * WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * * Lesser General Public License for more details. * * * * You should have received a copy of the GNU Lesser General Public * * License along with this library; if not, write to the Free Software * * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * * USA * ***************************************************************************/ #ifndef TAGLIB_TAG_C #define TAGLIB_TAG_C /* Do not include this in the main TagLib documentation. */ #ifndef DO_NOT_DOCUMENT #ifdef __cplusplus extern "C" { #endif #if defined(TAGLIB_STATIC) #define TAGLIB_C_EXPORT #elif defined(_WIN32) || defined(_WIN64) #ifdef MAKE_TAGLIB_C_LIB #define TAGLIB_C_EXPORT __declspec(dllexport) #else #define TAGLIB_C_EXPORT __declspec(dllimport) #endif #elif defined(__GNUC__) && (__GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 1) #define TAGLIB_C_EXPORT __attribute__ ((visibility("default"))) #else #define TAGLIB_C_EXPORT #endif #ifdef _MSC_VER /* minwindef.h contains typedef int BOOL */ #include #elif !defined BOOL #define BOOL int #endif /******************************************************************************* * [ TagLib C Binding ] * * This is an interface to TagLib's "simple" API, meaning that you can read and * modify media files in a generic, but not specialized way. This is a rough * representation of TagLib::File and TagLib::Tag, for which the documentation * is somewhat more complete and worth consulting. *******************************************************************************/ /* * These are used to give the C API some type safety (as opposed to * using void * ), but pointers to them are simply cast to the corresponding C++ * types in the implementation. */ typedef struct { int dummy; } TagLib_File; typedef struct { int dummy; } TagLib_Tag; typedef struct { int dummy; } TagLib_AudioProperties; typedef struct { int dummy; } TagLib_IOStream; /*! * By default all strings coming into or out of TagLib's C API are in UTF8. * However, it may be desirable for TagLib to operate on Latin1 (ISO-8859-1) * strings in which case this should be set to FALSE. */ TAGLIB_C_EXPORT void taglib_set_strings_unicode(BOOL unicode); /*! * TagLib can keep track of strings that are created when outputting tag values * and clear them using taglib_tag_clear_strings(). This is enabled by default. * However if you wish to do more fine grained management of strings, you can do * so by setting \a management to FALSE. */ TAGLIB_C_EXPORT void taglib_set_string_management_enabled(BOOL management); /*! * Explicitly free a string returned from TagLib */ TAGLIB_C_EXPORT void taglib_free(void* pointer); /******************************************************************************* * Stream API ******************************************************************************/ /*! * Creates a byte vector stream from \a size bytes of \a data. * Such a stream can be used with taglib_file_new_iostream() to create a file * from memory. */ TAGLIB_C_EXPORT TagLib_IOStream *taglib_memory_iostream_new(const char *data, unsigned int size); /*! * Frees and closes the stream. */ TAGLIB_C_EXPORT void taglib_iostream_free(TagLib_IOStream *stream); /******************************************************************************* * File API ******************************************************************************/ typedef enum { TagLib_File_MPEG, TagLib_File_OggVorbis, TagLib_File_FLAC, TagLib_File_MPC, TagLib_File_OggFlac, TagLib_File_WavPack, TagLib_File_Speex, TagLib_File_TrueAudio, TagLib_File_MP4, TagLib_File_ASF, TagLib_File_AIFF, TagLib_File_WAV, TagLib_File_APE, TagLib_File_IT, TagLib_File_Mod, TagLib_File_S3M, TagLib_File_XM, TagLib_File_Opus, TagLib_File_DSF, TagLib_File_DSDIFF } TagLib_File_Type; /*! * Creates a TagLib file based on \a filename. TagLib will try to guess the file * type. * * \returns NULL if the file type cannot be determined or the file cannot * be opened. */ TAGLIB_C_EXPORT TagLib_File *taglib_file_new(const char *filename); /*! * Creates a TagLib file based on \a filename. Rather than attempting to guess * the type, it will use the one specified by \a type. */ TAGLIB_C_EXPORT TagLib_File *taglib_file_new_type(const char *filename, TagLib_File_Type type); /*! * Creates a TagLib file from a \a stream. * A byte vector stream can be used to read a file from memory and write to * memory, e.g. when fetching network data. * The stream has to be created using taglib_memory_iostream_new() and shall be * freed using taglib_iostream_free() \e after this file is freed with * taglib_file_free(). */ TAGLIB_C_EXPORT TagLib_File *taglib_file_new_iostream(TagLib_IOStream *stream); /*! * Frees and closes the file. */ TAGLIB_C_EXPORT void taglib_file_free(TagLib_File *file); /*! * Returns \c true if the file is open and readable and valid information for * the Tag and / or AudioProperties was found. */ TAGLIB_C_EXPORT BOOL taglib_file_is_valid(const TagLib_File *file); /*! * Returns a pointer to the tag associated with this file. This will be freed * automatically when the file is freed. */ TAGLIB_C_EXPORT TagLib_Tag *taglib_file_tag(const TagLib_File *file); /*! * Returns a pointer to the audio properties associated with this file. This * will be freed automatically when the file is freed. */ TAGLIB_C_EXPORT const TagLib_AudioProperties *taglib_file_audioproperties(const TagLib_File *file); /*! * Saves the \a file to disk. */ TAGLIB_C_EXPORT BOOL taglib_file_save(TagLib_File *file); /****************************************************************************** * Tag API ******************************************************************************/ /*! * Returns a string with this tag's title. * * \note By default this string should be UTF8 encoded and its memory should be * freed using taglib_tag_free_strings(). */ TAGLIB_C_EXPORT char *taglib_tag_title(const TagLib_Tag *tag); /*! * Returns a string with this tag's artist. * * \note By default this string should be UTF8 encoded and its memory should be * freed using taglib_tag_free_strings(). */ TAGLIB_C_EXPORT char *taglib_tag_artist(const TagLib_Tag *tag); /*! * Returns a string with this tag's album name. * * \note By default this string should be UTF8 encoded and its memory should be * freed using taglib_tag_free_strings(). */ TAGLIB_C_EXPORT char *taglib_tag_album(const TagLib_Tag *tag); /*! * Returns a string with this tag's comment. * * \note By default this string should be UTF8 encoded and its memory should be * freed using taglib_tag_free_strings(). */ TAGLIB_C_EXPORT char *taglib_tag_comment(const TagLib_Tag *tag); /*! * Returns a string with this tag's genre. * * \note By default this string should be UTF8 encoded and its memory should be * freed using taglib_tag_free_strings(). */ TAGLIB_C_EXPORT char *taglib_tag_genre(const TagLib_Tag *tag); /*! * Returns the tag's year or 0 if the year is not set. */ TAGLIB_C_EXPORT unsigned int taglib_tag_year(const TagLib_Tag *tag); /*! * Returns the tag's track number or 0 if the track number is not set. */ TAGLIB_C_EXPORT unsigned int taglib_tag_track(const TagLib_Tag *tag); /*! * Sets the tag's title. * * \note By default this string should be UTF8 encoded. */ TAGLIB_C_EXPORT void taglib_tag_set_title(TagLib_Tag *tag, const char *title); /*! * Sets the tag's artist. * * \note By default this string should be UTF8 encoded. */ TAGLIB_C_EXPORT void taglib_tag_set_artist(TagLib_Tag *tag, const char *artist); /*! * Sets the tag's album. * * \note By default this string should be UTF8 encoded. */ TAGLIB_C_EXPORT void taglib_tag_set_album(TagLib_Tag *tag, const char *album); /*! * Sets the tag's comment. * * \note By default this string should be UTF8 encoded. */ TAGLIB_C_EXPORT void taglib_tag_set_comment(TagLib_Tag *tag, const char *comment); /*! * Sets the tag's genre. * * \note By default this string should be UTF8 encoded. */ TAGLIB_C_EXPORT void taglib_tag_set_genre(TagLib_Tag *tag, const char *genre); /*! * Sets the tag's year. 0 indicates that this field should be cleared. */ TAGLIB_C_EXPORT void taglib_tag_set_year(TagLib_Tag *tag, unsigned int year); /*! * Sets the tag's track number. 0 indicates that this field should be cleared. */ TAGLIB_C_EXPORT void taglib_tag_set_track(TagLib_Tag *tag, unsigned int track); /*! * Frees all of the strings that have been created by the tag. */ TAGLIB_C_EXPORT void taglib_tag_free_strings(void); /****************************************************************************** * Audio Properties API ******************************************************************************/ /*! * Returns the length of the file in seconds. */ TAGLIB_C_EXPORT int taglib_audioproperties_length(const TagLib_AudioProperties *audioProperties); /*! * Returns the bitrate of the file in kb/s. */ TAGLIB_C_EXPORT int taglib_audioproperties_bitrate(const TagLib_AudioProperties *audioProperties); /*! * Returns the sample rate of the file in Hz. */ TAGLIB_C_EXPORT int taglib_audioproperties_samplerate(const TagLib_AudioProperties *audioProperties); /*! * Returns the number of channels in the audio stream. */ TAGLIB_C_EXPORT int taglib_audioproperties_channels(const TagLib_AudioProperties *audioProperties); /******************************************************************************* * Special convenience ID3v2 functions *******************************************************************************/ typedef enum { TagLib_ID3v2_Latin1, TagLib_ID3v2_UTF16, TagLib_ID3v2_UTF16BE, TagLib_ID3v2_UTF8 } TagLib_ID3v2_Encoding; /*! * This sets the default encoding for ID3v2 frames that are written to tags. */ TAGLIB_C_EXPORT void taglib_id3v2_set_default_text_encoding(TagLib_ID3v2_Encoding encoding); /****************************************************************************** * Properties API ******************************************************************************/ /*! * Sets the property \a prop with \a value. Use \a value = NULL to remove * the property, otherwise it will be replaced. */ TAGLIB_C_EXPORT void taglib_property_set(TagLib_File *file, const char *prop, const char *value); /*! * Appends \a value to the property \a prop (sets it if non-existing). * Use \a value = NULL to remove all values associated with the property. */ TAGLIB_C_EXPORT void taglib_property_set_append(TagLib_File *file, const char *prop, const char *value); /*! * Get the keys of the property map. * * \return NULL terminated array of C-strings (char *), only NULL if empty. * It must be freed by the client using taglib_property_free(). */ TAGLIB_C_EXPORT char** taglib_property_keys(const TagLib_File *file); /*! * Get value(s) of property \a prop. * * \return NULL terminated array of C-strings (char *), only NULL if empty. * It must be freed by the client using taglib_property_free(). */ TAGLIB_C_EXPORT char** taglib_property_get(const TagLib_File *file, const char *prop); /*! * Frees the NULL terminated array \a props and the C-strings it contains. */ TAGLIB_C_EXPORT void taglib_property_free(char **props); /****************************************************************************** * Complex Properties API ******************************************************************************/ /*! * Types which can be stored in a TagLib_Variant. * * \related TagLib::Variant::Type * These correspond to TagLib::Variant::Type, but ByteVectorList, VariantList, * VariantMap are not supported and will be returned as their string * representation. */ typedef enum { TagLib_Variant_Void, TagLib_Variant_Bool, TagLib_Variant_Int, TagLib_Variant_UInt, TagLib_Variant_LongLong, TagLib_Variant_ULongLong, TagLib_Variant_Double, TagLib_Variant_String, TagLib_Variant_StringList, TagLib_Variant_ByteVector } TagLib_Variant_Type; /*! * Discriminated union used in complex property attributes. * * \e type must be set according to the \e value union used. * \e size is only required for TagLib_Variant_ByteVector and must contain * the number of bytes. * * \related TagLib::Variant. */ typedef struct { TagLib_Variant_Type type; unsigned int size; union { char *stringValue; char *byteVectorValue; char **stringListValue; BOOL boolValue; int intValue; unsigned int uIntValue; long long longLongValue; unsigned long long uLongLongValue; double doubleValue; } value; } TagLib_Variant; /*! * Attribute of a complex property. * Complex properties consist of a NULL-terminated array of pointers to * this structure with \e key and \e value. */ typedef struct { char *key; TagLib_Variant value; } TagLib_Complex_Property_Attribute; /*! * Picture data extracted from a complex property by the convenience function * taglib_picture_from_complex_property(). */ typedef struct { char *mimeType; char *description; char *pictureType; char *data; unsigned int size; } TagLib_Complex_Property_Picture_Data; /*! * Declare complex property attributes to set a picture. * Can be used to define a variable \a var which can be used with * taglib_complex_property_set() and a "PICTURE" key to set an * embedded picture with the picture data \a dat of size \a siz * and description \a desc, mime type \a mime and picture type * \a typ (size is unsigned int, the other input parameters char *). */ #define TAGLIB_COMPLEX_PROPERTY_PICTURE(var, dat, siz, desc, mime, typ) \ const TagLib_Complex_Property_Attribute \ var##Attrs[] = { \ { \ (char *)"data", \ { \ TagLib_Variant_ByteVector, \ (siz), \ { \ (char *)(dat) \ } \ } \ }, \ { \ (char *)"mimeType", \ { \ TagLib_Variant_String, \ 0U, \ { \ (char *)(mime) \ } \ } \ }, \ { \ (char *)"description", \ { \ TagLib_Variant_String, \ 0U, \ { \ (char *)(desc) \ } \ } \ }, \ { \ (char *)"pictureType", \ { \ TagLib_Variant_String, \ 0U, \ { \ (char *)(typ) \ } \ } \ } \ }; \ const TagLib_Complex_Property_Attribute *var[] = { \ &var##Attrs[0], &var##Attrs[1], &var##Attrs[2], \ &var##Attrs[3], NULL \ } /*! * Sets the complex property \a key with \a value. Use \a value = NULL to * remove the property, otherwise it will be replaced with the NULL * terminated array of attributes in \a value. * * A picture can be set with the TAGLIB_COMPLEX_PROPERTY_PICTURE macro: * * \code {.c} * TagLib_File *file = taglib_file_new("myfile.mp3"); * FILE *fh = fopen("mypicture.jpg", "rb"); * if(fh) { * fseek(fh, 0L, SEEK_END); * long size = ftell(fh); * fseek(fh, 0L, SEEK_SET); * char *data = (char *)malloc(size); * fread(data, size, 1, fh); * TAGLIB_COMPLEX_PROPERTY_PICTURE(props, data, size, "Written by TagLib", * "image/jpeg", "Front Cover"); * taglib_complex_property_set(file, "PICTURE", props); * taglib_file_save(file); * free(data); * fclose(fh); * } * \endcode */ TAGLIB_C_EXPORT BOOL taglib_complex_property_set( TagLib_File *file, const char *key, const TagLib_Complex_Property_Attribute **value); /*! * Appends \a value to the complex property \a key (sets it if non-existing). * Use \a value = NULL to remove all values associated with the \a key. */ TAGLIB_C_EXPORT BOOL taglib_complex_property_set_append( TagLib_File *file, const char *key, const TagLib_Complex_Property_Attribute **value); /*! * Get the keys of the complex properties. * * \return NULL terminated array of C-strings (char *), only NULL if empty. * It must be freed by the client using taglib_complex_property_free_keys(). */ TAGLIB_C_EXPORT char** taglib_complex_property_keys(const TagLib_File *file); /*! * Get value(s) of complex property \a key. * * \return NULL terminated array of property values, which are themselves an * array of property attributes, only NULL if empty. * It must be freed by the client using taglib_complex_property_free(). */ TAGLIB_C_EXPORT TagLib_Complex_Property_Attribute*** taglib_complex_property_get( const TagLib_File *file, const char *key); /*! * Extract the complex property values of a picture. * * This function can be used to get the data from a "PICTURE" complex property * without having to traverse the whole variant map. A picture can be * retrieved like this: * * \code {.c} * TagLib_File *file = taglib_file_new("myfile.mp3"); * TagLib_Complex_Property_Attribute*** properties = * taglib_complex_property_get(file, "PICTURE"); * TagLib_Complex_Property_Picture_Data picture; * taglib_picture_from_complex_property(properties, &picture); * // Do something with picture.mimeType, picture.description, * // picture.pictureType, picture.data, picture.size, e.g. extract it. * FILE *fh = fopen("mypicture.jpg", "wb"); * if(fh) { * fwrite(picture.data, picture.size, 1, fh); * fclose(fh); * } * taglib_complex_property_free(properties); * \endcode * * Note that the data in \a picture contains pointers to data in \a properties, * i.e. it only lives as long as the properties, until they are freed with * taglib_complex_property_free(). * If you want to access multiple pictures or additional properties of FLAC * pictures ("width", "height", "numColors", "colorDepth" int values), you * have to traverse the \a properties yourself. */ TAGLIB_C_EXPORT void taglib_picture_from_complex_property( TagLib_Complex_Property_Attribute*** properties, TagLib_Complex_Property_Picture_Data *picture); /*! * Frees the NULL terminated array \a keys (as returned by * taglib_complex_property_keys()) and the C-strings it contains. */ TAGLIB_C_EXPORT void taglib_complex_property_free_keys(char **keys); /*! * Frees the NULL terminated array \a props of property attribute arrays * (as returned by taglib_complex_property_get()) and the data such as * C-strings and byte vectors contained in these attributes. */ TAGLIB_C_EXPORT void taglib_complex_property_free( TagLib_Complex_Property_Attribute ***props); #ifdef __cplusplus } #endif #endif /* DO_NOT_DOCUMENT */ #endif