From 15039098245793a32f16be7ea2c0dba12a35eccf Mon Sep 17 00:00:00 2001 From: Tsuda Kageyu Date: Thu, 4 Jul 2013 18:11:33 +0900 Subject: [PATCH 1/2] Added the methods to check which kind of tags the file actually has. --- taglib/ape/apefile.cpp | 12 +++++++++++- taglib/ape/apefile.h | 10 ++++++++++ taglib/flac/flacfile.cpp | 14 ++++++++++++++ taglib/flac/flacfile.h | 15 +++++++++++++++ taglib/mpc/mpcfile.cpp | 11 ++++++++++- taglib/mpc/mpcfile.h | 10 ++++++++++ taglib/mpeg/mpegfile.h | 6 +++--- taglib/ogg/flac/oggflacfile.cpp | 5 +++++ taglib/ogg/flac/oggflacfile.h | 5 +++++ taglib/riff/aiff/aifffile.cpp | 1 + taglib/riff/aiff/aifffile.h | 5 +++++ taglib/riff/wav/wavfile.cpp | 28 +++++++++++++++++++++++++--- taglib/riff/wav/wavfile.h | 10 ++++++++++ taglib/trueaudio/trueaudiofile.cpp | 10 ++++++++++ taglib/trueaudio/trueaudiofile.h | 10 ++++++++++ taglib/wavpack/wavpackfile.cpp | 10 ++++++++++ taglib/wavpack/wavpackfile.h | 10 ++++++++++ 17 files changed, 164 insertions(+), 8 deletions(-) diff --git a/taglib/ape/apefile.cpp b/taglib/ape/apefile.cpp index 415eb17e..3cb9d9a7 100644 --- a/taglib/ape/apefile.cpp +++ b/taglib/ape/apefile.cpp @@ -47,7 +47,7 @@ using namespace TagLib; namespace { - enum { ApeAPEIndex, ApeID3v1Index }; + enum { ApeAPEIndex = 0, ApeID3v1Index = 1 }; } class APE::File::FilePrivate @@ -235,6 +235,16 @@ void APE::File::strip(int tags) } } +bool APE::File::hasAPETag() const +{ + return d->hasAPE; +} + +bool APE::File::hasID3v1Tag() const +{ + return d->hasID3v1; +} + //////////////////////////////////////////////////////////////////////////////// // private members //////////////////////////////////////////////////////////////////////////////// diff --git a/taglib/ape/apefile.h b/taglib/ape/apefile.h index 5ccef72f..5530edf3 100644 --- a/taglib/ape/apefile.h +++ b/taglib/ape/apefile.h @@ -186,6 +186,16 @@ namespace TagLib { */ void strip(int tags = AllTags); + /*! + * Returns whether or not the file on disk contains an APE tag. + */ + bool hasAPETag() const; + + /*! + * Returns whether or not the file on disk contains an ID3v1 tag. + */ + bool hasID3v1Tag() const; + private: File(const File &); File &operator=(const File &); diff --git a/taglib/flac/flacfile.cpp b/taglib/flac/flacfile.cpp index 9f6251cf..823170aa 100644 --- a/taglib/flac/flacfile.cpp +++ b/taglib/flac/flacfile.cpp @@ -552,3 +552,17 @@ void FLAC::File::removePictures() d->blocks = newBlocks; } +bool FLAC::File::hasXiphComment() const +{ + return d->hasXiphComment; +} + +bool FLAC::File::hasID3v1Tag() const +{ + return d->hasID3v1; +} + +bool FLAC::File::hasID3v2Tag() const +{ + return d->hasID3v2; +} diff --git a/taglib/flac/flacfile.h b/taglib/flac/flacfile.h index 95b52142..e159c505 100644 --- a/taglib/flac/flacfile.h +++ b/taglib/flac/flacfile.h @@ -246,6 +246,21 @@ namespace TagLib { */ void addPicture(Picture *picture); + /*! + * Returns whether or not the file on disk contains a Xiph comment. + */ + bool hasXiphComment() const; + + /*! + * Returns whether or not the file on disk contains an ID3v1 tag. + */ + bool hasID3v1Tag() const; + + /*! + * Returns whether or not the file on disk contains an ID3v2 tag. + */ + bool hasID3v2Tag() const; + private: File(const File &); File &operator=(const File &); diff --git a/taglib/mpc/mpcfile.cpp b/taglib/mpc/mpcfile.cpp index ee992ebc..979c035e 100644 --- a/taglib/mpc/mpcfile.cpp +++ b/taglib/mpc/mpcfile.cpp @@ -39,7 +39,7 @@ using namespace TagLib; namespace { - enum { MPCAPEIndex, MPCID3v1Index }; + enum { MPCAPEIndex = 0, MPCID3v1Index = 1 }; } class MPC::File::FilePrivate @@ -256,6 +256,15 @@ void MPC::File::remove(int tags) strip(tags); } +bool MPC::File::hasID3v1Tag() const +{ + return d->hasID3v1; +} + +bool MPC::File::hasAPETag() const +{ + return d->hasAPE; +} //////////////////////////////////////////////////////////////////////////////// // private members diff --git a/taglib/mpc/mpcfile.h b/taglib/mpc/mpcfile.h index ea66a5f9..4db906b5 100644 --- a/taglib/mpc/mpcfile.h +++ b/taglib/mpc/mpcfile.h @@ -187,6 +187,16 @@ namespace TagLib { */ void remove(int tags = AllTags); + /*! + * Returns whether or not the file on disk contains an ID3v1 tag. + */ + bool hasID3v1Tag() const; + + /*! + * Returns whether or not the file on disk contains an APE tag. + */ + bool hasAPETag() const; + private: File(const File &); File &operator=(const File &); diff --git a/taglib/mpeg/mpegfile.h b/taglib/mpeg/mpegfile.h index ef3a2b8f..be94be7f 100644 --- a/taglib/mpeg/mpegfile.h +++ b/taglib/mpeg/mpegfile.h @@ -327,17 +327,17 @@ namespace TagLib { long lastFrameOffset(); /*! - * Returns whether or not the file on disk contains ID3v1 tag. + * Returns whether or not the file on disk contains an ID3v1 tag. */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains ID3v2 tag. + * Returns whether or not the file on disk contains an ID3v2 tag. */ bool hasID3v2Tag() const; /*! - * Returns whether or not the file on disk contains APE tag. + * Returns whether or not the file on disk contains an APE tag. */ bool hasAPETag() const; diff --git a/taglib/ogg/flac/oggflacfile.cpp b/taglib/ogg/flac/oggflacfile.cpp index 18506b2e..d440a0c6 100644 --- a/taglib/ogg/flac/oggflacfile.cpp +++ b/taglib/ogg/flac/oggflacfile.cpp @@ -287,3 +287,8 @@ void Ogg::FLAC::File::scan() d->scanned = true; } + +bool Ogg::FLAC::File::hasXiphComment() const +{ + return d->hasXiphComment; +} diff --git a/taglib/ogg/flac/oggflacfile.h b/taglib/ogg/flac/oggflacfile.h index 4b83df1f..77280eff 100644 --- a/taglib/ogg/flac/oggflacfile.h +++ b/taglib/ogg/flac/oggflacfile.h @@ -128,6 +128,11 @@ namespace TagLib { */ long streamLength(); + /*! + * Returns whether or not the file on disk contains a Xiph comment. + */ + bool hasXiphComment() const; + private: File(const File &); File &operator=(const File &); diff --git a/taglib/riff/aiff/aifffile.cpp b/taglib/riff/aiff/aifffile.cpp index 19b80c8a..d20c148b 100644 --- a/taglib/riff/aiff/aifffile.cpp +++ b/taglib/riff/aiff/aifffile.cpp @@ -123,6 +123,7 @@ bool RIFF::AIFF::File::save() return true; } + //////////////////////////////////////////////////////////////////////////////// // private members //////////////////////////////////////////////////////////////////////////////// diff --git a/taglib/riff/aiff/aifffile.h b/taglib/riff/aiff/aifffile.h index 4ddd43e8..ef72dcd7 100644 --- a/taglib/riff/aiff/aifffile.h +++ b/taglib/riff/aiff/aifffile.h @@ -113,6 +113,11 @@ namespace TagLib { */ virtual bool save(); + /*! + * Returns whether or not the file on disk contains an ID3v2 tag. + */ + bool hasID3v2Tag() const; + private: File(const File &); File &operator=(const File &); diff --git a/taglib/riff/wav/wavfile.cpp b/taglib/riff/wav/wavfile.cpp index 43f2d812..abecea35 100644 --- a/taglib/riff/wav/wavfile.cpp +++ b/taglib/riff/wav/wavfile.cpp @@ -45,7 +45,9 @@ class RIFF::WAV::File::FilePrivate public: FilePrivate() : properties(0), - tagChunkID("ID3 ") + tagChunkID("ID3 "), + hasID3v2(false), + hasInfo(false) { } @@ -59,6 +61,9 @@ public: ByteVector tagChunkID; TagUnion tag; + + bool hasID3v2; + bool hasInfo; }; //////////////////////////////////////////////////////////////////////////////// @@ -143,8 +148,10 @@ bool RIFF::WAV::File::save(TagTypes tags, bool stripOthers, int id3v2Version) ID3v2::Tag *id3v2tag = d->tag.access(ID3v2Index, false); if(!id3v2tag->isEmpty()) { - if(tags & ID3v2) + if(tags & ID3v2) { setChunkData(d->tagChunkID, id3v2tag->render(id3v2Version)); + d->hasID3v2 = true; + } } Info::Tag *infotag = d->tag.access(InfoIndex, false); @@ -155,12 +162,24 @@ bool RIFF::WAV::File::save(TagTypes tags, bool stripOthers, int id3v2Version) setChunkData(chunkId, infotag->render()); else setChunkData("LIST", infotag->render(), true); + + d->hasInfo = true; } } return true; } +bool RIFF::WAV::File::hasID3v2Tag() const +{ + return d->hasID3v2; +} + +bool RIFF::WAV::File::hasInfoTag() const +{ + return d->hasInfo; +} + //////////////////////////////////////////////////////////////////////////////// // private members //////////////////////////////////////////////////////////////////////////////// @@ -174,6 +193,7 @@ void RIFF::WAV::File::read(bool readProperties, Properties::ReadStyle properties if(name == "ID3 " || name == "id3 ") { d->tagChunkID = chunkName(i); d->tag.set(ID3v2Index, new ID3v2::Tag(this, chunkOffset(i))); + d->hasID3v2 = true; } else if(name == "fmt " && readProperties) formatData = chunkData(i); @@ -183,8 +203,10 @@ void RIFF::WAV::File::read(bool readProperties, Properties::ReadStyle properties ByteVector data = chunkData(i); ByteVector type = data.mid(0, 4); - if(type == "INFO") + if(type == "INFO") { d->tag.set(InfoIndex, new RIFF::Info::Tag(data)); + d->hasInfo = true; + } } } diff --git a/taglib/riff/wav/wavfile.h b/taglib/riff/wav/wavfile.h index e8dfb8f8..be5e5d15 100644 --- a/taglib/riff/wav/wavfile.h +++ b/taglib/riff/wav/wavfile.h @@ -139,6 +139,16 @@ namespace TagLib { virtual bool save(); bool save(TagTypes tags, bool stripOthers = true, int id3v2Version = 4); + + /*! + * Returns whether or not the file on disk contains an ID3v2 tag. + */ + bool hasID3v2Tag() const; + + /*! + * Returns whether or not the file on disk contains an RIFF INFO tag. + */ + bool hasInfoTag() const; private: File(const File &); diff --git a/taglib/trueaudio/trueaudiofile.cpp b/taglib/trueaudio/trueaudiofile.cpp index 9bac29f0..f98d6add 100644 --- a/taglib/trueaudio/trueaudiofile.cpp +++ b/taglib/trueaudio/trueaudiofile.cpp @@ -236,6 +236,16 @@ void TrueAudio::File::strip(int tags) } } +bool TrueAudio::File::hasID3v1Tag() const +{ + return d->hasID3v1; +} + +bool TrueAudio::File::hasID3v2Tag() const +{ + return d->hasID3v2; +} + //////////////////////////////////////////////////////////////////////////////// // private members diff --git a/taglib/trueaudio/trueaudiofile.h b/taglib/trueaudio/trueaudiofile.h index d805c8c5..94c6102b 100644 --- a/taglib/trueaudio/trueaudiofile.h +++ b/taglib/trueaudio/trueaudiofile.h @@ -209,7 +209,17 @@ namespace TagLib { * \note In order to make the removal permanent save() still needs to be called */ void strip(int tags = AllTags); + + /*! + * Returns whether or not the file on disk contains an ID3v1 tag. + */ + bool hasID3v1Tag() const; + /*! + * Returns whether or not the file on disk contains an ID3v2 tag. + */ + bool hasID3v2Tag() const; + private: File(const File &); File &operator=(const File &); diff --git a/taglib/wavpack/wavpackfile.cpp b/taglib/wavpack/wavpackfile.cpp index 3754ea86..13b8c570 100644 --- a/taglib/wavpack/wavpackfile.cpp +++ b/taglib/wavpack/wavpackfile.cpp @@ -231,6 +231,16 @@ void WavPack::File::strip(int tags) } } +bool WavPack::File::hasID3v1Tag() const +{ + return d->hasID3v1; +} + +bool WavPack::File::hasAPETag() const +{ + return d->hasAPE; +} + //////////////////////////////////////////////////////////////////////////////// // private members //////////////////////////////////////////////////////////////////////////////// diff --git a/taglib/wavpack/wavpackfile.h b/taglib/wavpack/wavpackfile.h index c507977e..f84d5d78 100644 --- a/taglib/wavpack/wavpackfile.h +++ b/taglib/wavpack/wavpackfile.h @@ -173,7 +173,17 @@ namespace TagLib { * \note In order to make the removal permanent save() still needs to be called */ void strip(int tags = AllTags); + + /*! + * Returns whether or not the file on disk contains an ID3v1 tag. + */ + bool hasID3v1Tag() const; + /*! + * Returns whether or not the file on disk contains an APE tag. + */ + bool hasAPETag() const; + private: File(const File &); File &operator=(const File &); From 30f62ba887ee6b7d2d294ad8d73b006825f626c6 Mon Sep 17 00:00:00 2001 From: Tsuda Kageyu Date: Thu, 4 Jul 2013 21:44:28 +0900 Subject: [PATCH 2/2] Updated the relevant comments --- taglib/ape/apefile.h | 33 ++++++++++++++++------ taglib/asf/asffile.h | 1 - taglib/flac/flacfile.h | 48 ++++++++++++++++++++++++-------- taglib/mpc/mpcfile.h | 37 ++++++++++++++++-------- taglib/mpeg/mpegfile.h | 46 ++++++++++++++++++++++-------- taglib/ogg/flac/oggflacfile.cpp | 10 +++---- taglib/ogg/flac/oggflacfile.h | 16 +++++++++-- taglib/riff/aiff/aifffile.h | 10 ++++++- taglib/riff/wav/wavfile.h | 20 +++++++++++-- taglib/trueaudio/trueaudiofile.h | 42 ++++++++++++++++++---------- taglib/wavpack/wavpackfile.h | 33 ++++++++++++++++------ 11 files changed, 218 insertions(+), 78 deletions(-) diff --git a/taglib/ape/apefile.h b/taglib/ape/apefile.h index 5530edf3..f7b509f4 100644 --- a/taglib/ape/apefile.h +++ b/taglib/ape/apefile.h @@ -152,27 +152,38 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this may return a null pointer * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * an ID3v1 tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the APE::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file + * on disk actually has an ID3v1 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this may return a null pointer * if there is no valid APE tag. If \a create is true it will create - * a APE tag if one does not exist. + * an APE tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the APE::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an APE tag. Use hasAPETag() to check if the file + * on disk actually has an APE tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -187,12 +198,16 @@ namespace TagLib { void strip(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; diff --git a/taglib/asf/asffile.h b/taglib/asf/asffile.h index 4e850d6d..3ce3837a 100644 --- a/taglib/asf/asffile.h +++ b/taglib/asf/asffile.h @@ -114,7 +114,6 @@ namespace TagLib { virtual bool save(); private: - int readBYTE(bool *ok = 0); int readWORD(bool *ok = 0); unsigned int readDWORD(bool *ok = 0); diff --git a/taglib/flac/flacfile.h b/taglib/flac/flacfile.h index e159c505..0963f4af 100644 --- a/taglib/flac/flacfile.h +++ b/taglib/flac/flacfile.h @@ -161,39 +161,57 @@ namespace TagLib { /*! * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this returns a null pointer * if there is no valid ID3v2 tag. If \a create is true it will create - * an ID3v2 tag if one does not exist. + * an ID3v2 tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the FLAC::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file + * on disk actually has an ID3v2 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag(bool create = false); /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. + * If \a create is false (the default) this returns a null pointer + * if there is no valid APE tag. If \a create is true it will create + * an APE tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the FLAC::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file + * on disk actually has an ID3v1 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the XiphComment for the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this returns a null pointer * if there is no valid XiphComment. If \a create is true it will create - * a XiphComment if one does not exist. + * a XiphComment if one does not exist and returns a valid pointer. * + * \note This may return a valid pointer regardless of whether or not the + * file on disk has a XiphComment. Use hasXiphComment() to check if the + * file on disk actually has a XiphComment. + * * \note The Tag is still owned by the FLAC::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasXiphComment() */ Ogg::XiphComment *xiphComment(bool create = false); @@ -247,17 +265,23 @@ namespace TagLib { void addPicture(Picture *picture); /*! - * Returns whether or not the file on disk contains a Xiph comment. + * Returns whether or not the file on disk actually has a XiphComment. + * + * \see xiphComment() */ bool hasXiphComment() const; /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; diff --git a/taglib/mpc/mpcfile.h b/taglib/mpc/mpcfile.h index 4db906b5..1eef8103 100644 --- a/taglib/mpc/mpcfile.h +++ b/taglib/mpc/mpcfile.h @@ -145,28 +145,39 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * If \a create is false (the default) this returns a null pointer + * if there is no valid APE tag. If \a create is true it will create + * an APE tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the APE::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file + * on disk actually has an ID3v1 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this may return a null pointer * if there is no valid APE tag. If \a create is true it will create - * a APE tag if one does not exist. If there is already an ID3v1 tag, thes - * new APE tag will be placed before it. + * an APE tag if one does not exist and returns a valid pointer. If + * there already be an ID3v1 tag, the new APE tag will be placed before it. * - * \note The Tag is still owned by the APE::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an APE tag. Use hasAPETag() to check if the file + * on disk actually has an APE tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -188,12 +199,16 @@ namespace TagLib { void remove(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; diff --git a/taglib/mpeg/mpegfile.h b/taglib/mpeg/mpegfile.h index be94be7f..3fc01e68 100644 --- a/taglib/mpeg/mpegfile.h +++ b/taglib/mpeg/mpegfile.h @@ -238,39 +238,57 @@ namespace TagLib { /*! * Returns a pointer to the ID3v2 tag of the file. * - * A tag will always be returned, regardless of whether there is a - * tag in the file or not. Use ID3v2::Tag::isEmpty() to check if - * the tag contains no data. + * If \a create is false (the default) this may return a null pointer + * if there is no valid ID3v2 tag. If \a create is true it will create + * an ID3v2 tag if one does not exist and returns a valid pointer. + * + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file + * on disk actually has an ID3v2 tag. * * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag(bool create = false); /*! * Returns a pointer to the ID3v1 tag of the file. * - * A tag will always be returned, regardless of whether there is a - * tag in the file or not. Use Tag::isEmpty() to check if - * the tag contains no data. + * If \a create is false (the default) this may return a null pointer + * if there is no valid ID3v1 tag. If \a create is true it will create + * an ID3v1 tag if one does not exist and returns a valid pointer. + * + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file + * on disk actually has an ID3v1 tag. * * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this may return a null pointer * if there is no valid APE tag. If \a create is true it will create - * an APE tag if one does not exist. + * an APE tag if one does not exist and returns a valid pointer. + * + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an APE tag. Use hasAPETag() to check if the file + * on disk actually has an APE tag. * * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -327,17 +345,23 @@ namespace TagLib { long lastFrameOffset(); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const; diff --git a/taglib/ogg/flac/oggflacfile.cpp b/taglib/ogg/flac/oggflacfile.cpp index d440a0c6..bdf82459 100644 --- a/taglib/ogg/flac/oggflacfile.cpp +++ b/taglib/ogg/flac/oggflacfile.cpp @@ -137,6 +137,11 @@ bool Ogg::FLAC::File::save() return Ogg::File::save(); } +bool Ogg::FLAC::File::hasXiphComment() const +{ + return d->hasXiphComment; +} + //////////////////////////////////////////////////////////////////////////////// // private members //////////////////////////////////////////////////////////////////////////////// @@ -287,8 +292,3 @@ void Ogg::FLAC::File::scan() d->scanned = true; } - -bool Ogg::FLAC::File::hasXiphComment() const -{ - return d->hasXiphComment; -} diff --git a/taglib/ogg/flac/oggflacfile.h b/taglib/ogg/flac/oggflacfile.h index 77280eff..8d87e486 100644 --- a/taglib/ogg/flac/oggflacfile.h +++ b/taglib/ogg/flac/oggflacfile.h @@ -91,11 +91,19 @@ namespace TagLib { /*! * Returns the Tag for this file. This will always be a XiphComment. + * + * \note This always returns a valid pointer regardless of whether or not + * the file on disk has a XiphComment. Use hasXiphComment() to check if + * the file on disk actually has a XiphComment. + * + * \note The Tag is still owned by the FLAC::File and should not be + * deleted by the user. It will be deleted when the file (object) is + * destroyed. + * + * \see hasXiphComment() */ virtual XiphComment *tag() const; - - /*! * Returns the FLAC::Properties for this file. If no audio properties * were read then this will return a null pointer. @@ -129,7 +137,9 @@ namespace TagLib { long streamLength(); /*! - * Returns whether or not the file on disk contains a Xiph comment. + * Returns whether or not the file on disk actually has a XiphComment. + * + * \see tag() */ bool hasXiphComment() const; diff --git a/taglib/riff/aiff/aifffile.h b/taglib/riff/aiff/aifffile.h index ef72dcd7..c75b94b4 100644 --- a/taglib/riff/aiff/aifffile.h +++ b/taglib/riff/aiff/aifffile.h @@ -85,6 +85,12 @@ namespace TagLib { /*! * Returns the Tag for this file. + * + * \note This always returns a valid pointer regardless of whether or not + * the file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file + * on disk actually has an ID3v2 tag. + * + * \see hasID3v2Tag() */ virtual ID3v2::Tag *tag() const; @@ -114,7 +120,9 @@ namespace TagLib { virtual bool save(); /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; diff --git a/taglib/riff/wav/wavfile.h b/taglib/riff/wav/wavfile.h index be5e5d15..2f83332a 100644 --- a/taglib/riff/wav/wavfile.h +++ b/taglib/riff/wav/wavfile.h @@ -105,11 +105,23 @@ namespace TagLib { /*! * Returns the ID3v2 Tag for this file. + * + * \note This always returns a valid pointer regardless of whether or not + * the file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the + * file on disk actually has an ID3v2 tag. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag() const; /*! * Returns the RIFF INFO Tag for this file. + * + * \note This always returns a valid pointer regardless of whether or not + * the file on disk has a RIFF INFO tag. Use hasInfoTag() to check if the + * file on disk actually has a RIFF INFO tag. + * + * \see hasInfoTag() */ Info::Tag *InfoTag() const; @@ -141,12 +153,16 @@ namespace TagLib { bool save(TagTypes tags, bool stripOthers = true, int id3v2Version = 4); /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; /*! - * Returns whether or not the file on disk contains an RIFF INFO tag. + * Returns whether or not the file on disk actually has a RIFF INFO tag. + * + * \see InfoTag() */ bool hasInfoTag() const; diff --git a/taglib/trueaudio/trueaudiofile.h b/taglib/trueaudio/trueaudiofile.h index 94c6102b..dbaafcdb 100644 --- a/taglib/trueaudio/trueaudiofile.h +++ b/taglib/trueaudio/trueaudiofile.h @@ -173,30 +173,40 @@ namespace TagLib { virtual bool save(); /*! - * Returns a pointer to the ID3v2 tag of the file. + * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v2 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * If \a create is false (the default) this may return a null pointer + * if there is no valid ID3v1 tag. If \a create is true it will create + * an ID3v1 tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the TrueAudio::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file + * on disk actually has an ID3v1 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! - * Returns a pointer to the ID3v1 tag of the file. + * Returns a pointer to the ID3v2 tag of the file. * - * If \a create is false (the default) this will return a null pointer - * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * If \a create is false (the default) this may return a null pointer + * if there is no valid ID3v2 tag. If \a create is true it will create + * an ID3v2 tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the TrueAudio::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file + * on disk actually has an ID3v2 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v2Tag() */ ID3v2::Tag *ID3v2Tag(bool create = false); @@ -211,12 +221,16 @@ namespace TagLib { void strip(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an ID3v2 tag. + * Returns whether or not the file on disk actually has an ID3v2 tag. + * + * \see ID3v2Tag() */ bool hasID3v2Tag() const; diff --git a/taglib/wavpack/wavpackfile.h b/taglib/wavpack/wavpackfile.h index f84d5d78..198e9619 100644 --- a/taglib/wavpack/wavpackfile.h +++ b/taglib/wavpack/wavpackfile.h @@ -140,27 +140,38 @@ namespace TagLib { /*! * Returns a pointer to the ID3v1 tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this may return a null pointer * if there is no valid ID3v1 tag. If \a create is true it will create - * an ID3v1 tag if one does not exist. If there is already an APE tag, the - * new ID3v1 tag will be placed after it. + * an ID3v1 tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the APE::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file + * on disk actually has an ID3v1 tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasID3v1Tag() */ ID3v1::Tag *ID3v1Tag(bool create = false); /*! * Returns a pointer to the APE tag of the file. * - * If \a create is false (the default) this will return a null pointer + * If \a create is false (the default) this may return a null pointer * if there is no valid APE tag. If \a create is true it will create - * a APE tag if one does not exist. + * an APE tag if one does not exist and returns a valid pointer. * - * \note The Tag is still owned by the APE::File and should not be + * \note This may return a valid pointer regardless of whether or not the + * file on disk has an APE tag. Use hasAPETag() to check if the file + * on disk actually has an APE tag. + * + * \note The Tag is still owned by the MPEG::File and should not be * deleted by the user. It will be deleted when the file (object) is * destroyed. + * + * \see hasAPETag() */ APE::Tag *APETag(bool create = false); @@ -175,12 +186,16 @@ namespace TagLib { void strip(int tags = AllTags); /*! - * Returns whether or not the file on disk contains an ID3v1 tag. + * Returns whether or not the file on disk actually has an ID3v1 tag. + * + * \see ID3v1Tag() */ bool hasID3v1Tag() const; /*! - * Returns whether or not the file on disk contains an APE tag. + * Returns whether or not the file on disk actually has an APE tag. + * + * \see APETag() */ bool hasAPETag() const;