1
/***************************************************************************
2
copyright : (C) 2002 - 2008 by Scott Wheeler
3
email : wheeler@kde.org
4
***************************************************************************/
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. *
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. *
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 *
21
* Alternatively, this file is available under the Mozilla Public *
22
* License Version 1.1. You may obtain a copy of the License at *
23
* http://www.mozilla.org/MPL/ *
24
***************************************************************************/
29
#include "taglib_export.h"
31
#include "tbytevector.h"
37
class AudioProperties;
41
class TAGLIB_EXPORT FileName
44
FileName(const wchar_t *name) : m_wname(name) {}
45
FileName(const char *name) : m_name(name) {}
46
operator const wchar_t *() const { return m_wname.c_str(); }
47
operator const char *() const { return m_name.c_str(); }
53
typedef const char *FileName;
56
//! A file class with some useful methods for tag manipulation
59
* This class is a basic file class with some methods that are particularly
60
* useful for tag editors. It has methods to take advantage of
61
* ByteVector and a binary search method for finding patterns in a file.
64
class TAGLIB_EXPORT File
68
* Position in the file used for seeking.
71
//! Seek from the beginning of the file.
73
//! Seek from the current position in the file.
75
//! Seek from the end of the file.
80
* Destroys this File instance.
85
* Returns the file name in the local file system encoding.
87
FileName name() const;
90
* Returns a pointer to this file's tag. This should be reimplemented in
91
* the concrete subclasses.
93
virtual Tag *tag() const = 0;
96
* Returns a pointer to this file's audio properties. This should be
97
* reimplemented in the concrete subclasses. If no audio properties were
98
* read then this will return a null pointer.
100
virtual AudioProperties *audioProperties() const = 0;
103
* Save the file and its associated tags. This should be reimplemented in
104
* the concrete subclasses. Returns true if the save succeeds.
106
* \warning On UNIX multiple processes are able to write to the same file at
107
* the same time. This can result in serious file corruption. If you are
108
* developing a program that makes use of TagLib from multiple processes you
109
* must insure that you are only doing writes to a particular file from one
112
virtual bool save() = 0;
115
* Reads a block of size \a length at the current get pointer.
117
ByteVector readBlock(ulong length);
120
* Attempts to write the block \a data at the current get pointer. If the
121
* file is currently only opened read only -- i.e. readOnly() returns true --
122
* this attempts to reopen the file in read/write mode.
124
* \note This should be used instead of using the streaming output operator
125
* for a ByteVector. And even this function is significantly slower than
126
* doing output with a char[].
128
void writeBlock(const ByteVector &data);
131
* Returns the offset in the file that \a pattern occurs at or -1 if it can
132
* not be found. If \a before is set, the search will only continue until the
133
* pattern \a before is found. This is useful for tagging purposes to search
134
* for a tag before the synch frame.
136
* Searching starts at \a fromOffset, which defaults to the beginning of the
139
* \note This has the practial limitation that \a pattern can not be longer
140
* than the buffer size used by readBlock(). Currently this is 1024 bytes.
142
long find(const ByteVector &pattern,
144
const ByteVector &before = ByteVector::null);
147
* Returns the offset in the file that \a pattern occurs at or -1 if it can
148
* not be found. If \a before is set, the search will only continue until the
149
* pattern \a before is found. This is useful for tagging purposes to search
150
* for a tag before the synch frame.
152
* Searching starts at \a fromOffset and proceeds from the that point to the
153
* beginning of the file and defaults to the end of the file.
155
* \note This has the practial limitation that \a pattern can not be longer
156
* than the buffer size used by readBlock(). Currently this is 1024 bytes.
158
long rfind(const ByteVector &pattern,
160
const ByteVector &before = ByteVector::null);
163
* Insert \a data at position \a start in the file overwriting \a replace
164
* bytes of the original content.
166
* \note This method is slow since it requires rewriting all of the file
167
* after the insertion point.
169
void insert(const ByteVector &data, ulong start = 0, ulong replace = 0);
172
* Removes a block of the file starting a \a start and continuing for
175
* \note This method is slow since it involves rewriting all of the file
176
* after the removed portion.
178
void removeBlock(ulong start = 0, ulong length = 0);
181
* Returns true if the file is read only (or if the file can not be opened).
183
bool readOnly() const;
186
* Since the file can currently only be opened as an argument to the
187
* constructor (sort-of by design), this returns if that open succeeded.
192
* Returns true if the file is open and readble and valid information for
193
* the Tag and / or AudioProperties was found.
195
bool isValid() const;
198
* Move the I/O pointer to \a offset in the file from position \a p. This
199
* defaults to seeking from the beginning of the file.
203
void seek(long offset, Position p = Beginning);
206
* Reset the end-of-file and error flags on the file.
211
* Returns the current offset withing the file.
216
* Returns the length of the file.
221
* Returns true if \a file can be opened for reading. If the file does not
222
* exist, this will return false.
226
static bool isReadable(const char *file);
229
* Returns true if \a file can be opened for writing.
233
static bool isWritable(const char *name);
237
* Construct a File object and opens the \a file. \a file should be a
238
* be a C-string in the local file system encoding.
240
* \note Constructor is protected since this class should only be
241
* instantiated through subclasses.
246
* Marks the file as valid or invalid.
250
void setValid(bool valid);
253
* Truncates the file to a \a length.
255
void truncate(long length);
258
* Returns the buffer size that is used for internal buffering.
260
static uint bufferSize();
264
File &operator=(const File &);
added
removed
Frameworks/taglib/taglib/taglib/toolkit/tfile.h
