metadata.h 31.5 KB
Newer Older
Josh Coalson's avatar
Josh Coalson committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/* libFLAC++ - Free Lossless Audio Codec library
 * Copyright (C) 2002  Josh Coalson
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library 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 FLACPP__METADATA_H
#define FLACPP__METADATA_H

23
24
#include "export.h"

Josh Coalson's avatar
Josh Coalson committed
25
26
#include "FLAC/metadata.h"

Josh Coalson's avatar
Josh Coalson committed
27
28
29
30
31
32
33
// ===============================================================
//
//  Full documentation for the metadata interface can be found
//  in the C layer in include/FLAC/metadata.h
//
// ===============================================================

Josh Coalson's avatar
Josh Coalson committed
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
/** \file include/FLAC++/metadata.h
 *
 *  \brief
 *  This module provides classes for creating and manipulating FLAC
 *  metadata blocks in memory, and three progressively more powerful
 *  interfaces for traversing and editing metadata in FLAC files.
 *
 *  See the detailed documentation for each interface in the
 *  \link flacpp_metadata metadata \endlink module.
 */

/** \defgroup flacpp_metadata FLAC++/metadata.h: metadata interfaces
 *  \ingroup flacpp
 *
 *  \brief
 *  This module provides classes for creating and manipulating FLAC
 *  metadata blocks in memory, and three progressively more powerful
 *  interfaces for traversing and editing metadata in FLAC files.
 *
 *  The behavior closely mimics the C layer interface; be sure to read
 *  the detailed description of the
 *  \link flac_metadata C metadata module \endlink.
 */

Josh Coalson's avatar
Josh Coalson committed
58

Josh Coalson's avatar
Josh Coalson committed
59
60
61
namespace FLAC {
	namespace Metadata {

Josh Coalson's avatar
Josh Coalson committed
62
63
64
65
66
67
		// ============================================================
		//
		//  Metadata objects
		//
		// ============================================================

Josh Coalson's avatar
Josh Coalson committed
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
		/** \defgroup flacpp_metadata_object FLAC++/metadata.h: metadata object classes
		 *  \ingroup flacpp_metadata
		 *
		 * This module contains classes representing FLAC metadata
		 * blocks in memory.
		 *
		 * The behavior closely mimics the C layer interface; be
		 * sure to read the detailed description of the
		 * \link flac_metadata_object C metadata object module \endlink.
		 *
		 * Any time a metadata object is constructed or assigned, you
		 * should check is_valid() to make sure the underlying
		 * ::FLAC__StreamMetadata object was able to be created.
		 *
		 * \warning
		 * When the get_*() methods of any metadata object method
		 * return you a const pointer, DO NOT disobey and write into it.
		 * Always use the set_*() methods.
		 *
		 * \{
		 */

		/** Base class for all metadata block types.
		 */
92
		class FLACPP_API Prototype {
Josh Coalson's avatar
Josh Coalson committed
93
		protected:
Josh Coalson's avatar
Josh Coalson committed
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
			Prototype(const Prototype &);
			Prototype(const ::FLAC__StreamMetadata &);
			Prototype(const ::FLAC__StreamMetadata *);
			//@}

			/** Constructs an object with copy control.  When \a copy
			 *  is \c true, behaves identically to
			 *  FLAC::Metadata::Prototype::Prototype(const ::FLAC__StreamMetadata *object).
			 *  When \a copy is \c false, the instance takes ownership of
			 *  the pointer and the ::FLAC__StreamMetadata object will
			 *  be freed by the destructor.
			 *
			 *  \assert
			 *    \code object != NULL \endcode
			 */
Josh Coalson's avatar
Josh Coalson committed
113
			Prototype(::FLAC__StreamMetadata *object, bool copy);
Josh Coalson's avatar
Josh Coalson committed
114

Josh Coalson's avatar
Josh Coalson committed
115
116
			//@{
			/** Assign from another object.  Always performs a deep copy. */
Josh Coalson's avatar
Josh Coalson committed
117
			void operator=(const Prototype &);
Josh Coalson's avatar
Josh Coalson committed
118
119
120
			void operator=(const ::FLAC__StreamMetadata &);
			void operator=(const ::FLAC__StreamMetadata *);
			//@}
121

Josh Coalson's avatar
Josh Coalson committed
122
123
			/** Deletes the underlying ::FLAC__StreamMetadata object.
			 */
Josh Coalson's avatar
Josh Coalson committed
124
125
			virtual void clear();

126
			::FLAC__StreamMetadata *object_;
Josh Coalson's avatar
Josh Coalson committed
127
		public:
Josh Coalson's avatar
Josh Coalson committed
128
129
			/** Deletes the underlying ::FLAC__StreamMetadata object.
			 */
130
131
			virtual ~Prototype();

Josh Coalson's avatar
Josh Coalson committed
132
133
			//@{
			/** Check for equality, performing a deep compare by following pointers. */
134
135
136
			inline bool operator==(const Prototype &) const;
			inline bool operator==(const ::FLAC__StreamMetadata &) const;
			inline bool operator==(const ::FLAC__StreamMetadata *) const;
Josh Coalson's avatar
Josh Coalson committed
137
138
139
140
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
141
142
143
			inline bool operator!=(const Prototype &) const;
			inline bool operator!=(const ::FLAC__StreamMetadata &) const;
			inline bool operator!=(const ::FLAC__StreamMetadata *) const;
Josh Coalson's avatar
Josh Coalson committed
144
			//@}
145

Josh Coalson's avatar
Josh Coalson committed
146
147
148
			friend class SimpleIterator;
			friend class Iterator;

Josh Coalson's avatar
Josh Coalson committed
149
150
151
152
			/** Returns \c true if the object was correctly constructed
			 *  (i.e. the underlying ::FLAC__StreamMetadata object was
			 *  properly allocated), else \c false.
			 */
153
			inline bool is_valid() const;
Josh Coalson's avatar
Josh Coalson committed
154

Josh Coalson's avatar
Josh Coalson committed
155
156
157
158
159
160
			/** Returns \c true if this block is the last block in a
			 *  stream, else \c false.
			 *
			 * \assert
			 *   \code is_valid() \endcode
			 */
Josh Coalson's avatar
Josh Coalson committed
161
			bool get_is_last() const;
162

Josh Coalson's avatar
Josh Coalson committed
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
			/** Returns the type of the block.
			 *
			 * \assert
			 *   \code is_valid() \endcode
			 */
			::FLAC__MetadataType get_type() const;

			/** Returns the stream length of the metadata block.
			 *
			 * \note
			 *   The length does not include the metadata block header,
			 *   per spec.
			 *
			 * \assert
			 *   \code is_valid() \endcode
			 */
			unsigned get_length() const;

			/** Sets the "is_last" flag for the block.  When using the iterators
			 *  it is not necessary to set this flag; they will do it for you.
			 *
			 * \assert
			 *   \code is_valid() \endcode
			 */
187
			void set_is_last(bool);
Josh Coalson's avatar
Josh Coalson committed
188
		private:
Josh Coalson's avatar
Josh Coalson committed
189
190
			/** Private and undefined so you can't use it. */
			Prototype();
Josh Coalson's avatar
Josh Coalson committed
191
192
193
194

			// These are used only by Iterator
			bool is_reference_;
			inline void set_reference(bool x) { is_reference_ = x; }
Josh Coalson's avatar
Josh Coalson committed
195
196
		};

Josh Coalson's avatar
Josh Coalson committed
197
		inline bool Prototype::operator==(const Prototype &object) const
198
		{ return (bool)::FLAC__metadata_object_is_equal(object_, object.object_); }
199

Josh Coalson's avatar
Josh Coalson committed
200
		inline bool Prototype::operator==(const ::FLAC__StreamMetadata &object) const
201
		{ return (bool)::FLAC__metadata_object_is_equal(object_, &object); }
202

Josh Coalson's avatar
Josh Coalson committed
203
		inline bool Prototype::operator==(const ::FLAC__StreamMetadata *object) const
204
		{ return (bool)::FLAC__metadata_object_is_equal(object_, object); }
205

Josh Coalson's avatar
Josh Coalson committed
206
		inline bool Prototype::operator!=(const Prototype &object) const
207
208
		{ return !operator==(object); }

Josh Coalson's avatar
Josh Coalson committed
209
		inline bool Prototype::operator!=(const ::FLAC__StreamMetadata &object) const
210
211
		{ return !operator==(object); }

Josh Coalson's avatar
Josh Coalson committed
212
		inline bool Prototype::operator!=(const ::FLAC__StreamMetadata *object) const
213
214
215
216
217
		{ return !operator==(object); }

		inline bool Prototype::is_valid() const
		{ return 0 != object_; }

Josh Coalson's avatar
Josh Coalson committed
218
		/** Create a deep copy of an object and return it. */
219
		FLACPP_API Prototype *clone(const Prototype *);
220

Josh Coalson's avatar
Josh Coalson committed
221
222

		/** STREAMINFO metadata block.
Josh Coalson's avatar
Josh Coalson committed
223
		 *  See <A HREF="../format.html#metadata_block_streaminfo">format specification</A>.
Josh Coalson's avatar
Josh Coalson committed
224
		 */
225
		class FLACPP_API StreamInfo : public Prototype {
Josh Coalson's avatar
Josh Coalson committed
226
227
		public:
			StreamInfo();
Josh Coalson's avatar
Josh Coalson committed
228
229
230
231
232

			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
233
234
235
			inline StreamInfo(const StreamInfo &object): Prototype(object) { }
			inline StreamInfo(const ::FLAC__StreamMetadata &object): Prototype(object) { }
			inline StreamInfo(const ::FLAC__StreamMetadata *object): Prototype(object) { }
Josh Coalson's avatar
Josh Coalson committed
236
237
238
239
240
			//@}

			/** Constructs an object with copy control.  See
			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
			 */
241
			inline StreamInfo(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
Josh Coalson's avatar
Josh Coalson committed
242

Josh Coalson's avatar
Josh Coalson committed
243
244
			~StreamInfo();

Josh Coalson's avatar
Josh Coalson committed
245
246
			//@{
			/** Assign from another object.  Always performs a deep copy. */
Josh Coalson's avatar
Josh Coalson committed
247
			inline void operator=(const StreamInfo &object) { Prototype::operator=(object); }
248
249
			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
Josh Coalson's avatar
Josh Coalson committed
250
			//@}
Josh Coalson's avatar
Josh Coalson committed
251

Josh Coalson's avatar
Josh Coalson committed
252
253
			//@{
			/** Check for equality, performing a deep compare by following pointers. */
254
			inline bool operator==(const StreamInfo &object) const { return Prototype::operator==(object); }
255
256
			inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
Josh Coalson's avatar
Josh Coalson committed
257
258
259
260
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
261
			inline bool operator!=(const StreamInfo &object) const { return Prototype::operator!=(object); }
262
263
			inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
Josh Coalson's avatar
Josh Coalson committed
264
			//@}
265

Josh Coalson's avatar
Josh Coalson committed
266
267
			//@{
			/** See <A HREF="../format.html#metadata_block_streaminfo">format specification</A>. */
Josh Coalson's avatar
Josh Coalson committed
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
			unsigned get_min_blocksize() const;
			unsigned get_max_blocksize() const;
			unsigned get_min_framesize() const;
			unsigned get_max_framesize() const;
			unsigned get_sample_rate() const;
			unsigned get_channels() const;
			unsigned get_bits_per_sample() const;
			FLAC__uint64 get_total_samples() const;
			const FLAC__byte *get_md5sum() const;

			void set_min_blocksize(unsigned value);
			void set_max_blocksize(unsigned value);
			void set_min_framesize(unsigned value);
			void set_max_framesize(unsigned value);
			void set_sample_rate(unsigned value);
			void set_channels(unsigned value);
			void set_bits_per_sample(unsigned value);
			void set_total_samples(FLAC__uint64 value);
			void set_md5sum(const FLAC__byte value[16]);
Josh Coalson's avatar
Josh Coalson committed
287
			//@}
Josh Coalson's avatar
Josh Coalson committed
288
289
		};

Josh Coalson's avatar
Josh Coalson committed
290
291
		/** PADDING metadata block.
		 *  See <A HREF="../format.html#metadata_block_padding">format specification</A>.
Josh Coalson's avatar
Josh Coalson committed
292
		 */
293
		class FLACPP_API Padding : public Prototype {
Josh Coalson's avatar
Josh Coalson committed
294
295
		public:
			Padding();
Josh Coalson's avatar
Josh Coalson committed
296
297
298
299
300

			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
301
302
303
			inline Padding(const Padding &object): Prototype(object) { }
			inline Padding(const ::FLAC__StreamMetadata &object): Prototype(object) { }
			inline Padding(const ::FLAC__StreamMetadata *object): Prototype(object) { }
Josh Coalson's avatar
Josh Coalson committed
304
305
306
307
308
			//@}

			/** Constructs an object with copy control.  See
			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
			 */
309
			inline Padding(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
Josh Coalson's avatar
Josh Coalson committed
310

Josh Coalson's avatar
Josh Coalson committed
311
			~Padding();
Josh Coalson's avatar
Josh Coalson committed
312

Josh Coalson's avatar
Josh Coalson committed
313
314
			//@{
			/** Assign from another object.  Always performs a deep copy. */
Josh Coalson's avatar
Josh Coalson committed
315
			inline void operator=(const Padding &object) { Prototype::operator=(object); }
316
317
			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
Josh Coalson's avatar
Josh Coalson committed
318
			//@}
319

Josh Coalson's avatar
Josh Coalson committed
320
321
			//@{
			/** Check for equality, performing a deep compare by following pointers. */
322
			inline bool operator==(const Padding &object) const { return Prototype::operator==(object); }
323
324
			inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
Josh Coalson's avatar
Josh Coalson committed
325
326
327
328
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
329
			inline bool operator!=(const Padding &object) const { return Prototype::operator!=(object); }
330
331
			inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
Josh Coalson's avatar
Josh Coalson committed
332
			//@}
333

334
			void set_length(unsigned length);
Josh Coalson's avatar
Josh Coalson committed
335
336
		};

Josh Coalson's avatar
Josh Coalson committed
337
338
		/** APPLICATION metadata block.
		 *  See <A HREF="../format.html#metadata_block_application">format specification</A>.
Josh Coalson's avatar
Josh Coalson committed
339
		 */
340
		class FLACPP_API Application : public Prototype {
Josh Coalson's avatar
Josh Coalson committed
341
342
		public:
			Application();
Josh Coalson's avatar
Josh Coalson committed
343
344
345
346
347
			//
			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
348
349
350
			inline Application(const Application &object): Prototype(object) { }
			inline Application(const ::FLAC__StreamMetadata &object): Prototype(object) { }
			inline Application(const ::FLAC__StreamMetadata *object): Prototype(object) { }
Josh Coalson's avatar
Josh Coalson committed
351
352
353
354
355
			//@}

			/** Constructs an object with copy control.  See
			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
			 */
356
			inline Application(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
Josh Coalson's avatar
Josh Coalson committed
357

Josh Coalson's avatar
Josh Coalson committed
358
359
			~Application();

Josh Coalson's avatar
Josh Coalson committed
360
361
			//@{
			/** Assign from another object.  Always performs a deep copy. */
Josh Coalson's avatar
Josh Coalson committed
362
			inline void operator=(const Application &object) { Prototype::operator=(object); }
363
364
			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
Josh Coalson's avatar
Josh Coalson committed
365
			//@}
Josh Coalson's avatar
Josh Coalson committed
366

Josh Coalson's avatar
Josh Coalson committed
367
368
			//@{
			/** Check for equality, performing a deep compare by following pointers. */
369
			inline bool operator==(const Application &object) const { return Prototype::operator==(object); }
370
371
			inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
Josh Coalson's avatar
Josh Coalson committed
372
373
374
375
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
376
			inline bool operator!=(const Application &object) const { return Prototype::operator!=(object); }
377
378
			inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
Josh Coalson's avatar
Josh Coalson committed
379
			//@}
380

Josh Coalson's avatar
Josh Coalson committed
381
382
383
			const FLAC__byte *get_id() const;
			const FLAC__byte *get_data() const;

384
			void set_id(const FLAC__byte value[4]);
Josh Coalson's avatar
Josh Coalson committed
385
386
			//! This form always copies \a data
			bool set_data(const FLAC__byte *data, unsigned length);
387
			bool set_data(FLAC__byte *data, unsigned length, bool copy);
Josh Coalson's avatar
Josh Coalson committed
388
389
		};

Josh Coalson's avatar
Josh Coalson committed
390
391
		/** SEEKTABLE metadata block.
		 *  See <A HREF="../format.html#metadata_block_seektable">format specification</A>.
Josh Coalson's avatar
Josh Coalson committed
392
		 */
393
		class FLACPP_API SeekTable : public Prototype {
Josh Coalson's avatar
Josh Coalson committed
394
395
		public:
			SeekTable();
Josh Coalson's avatar
Josh Coalson committed
396
397
398
399
400

			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
401
402
403
			inline SeekTable(const SeekTable &object): Prototype(object) { }
			inline SeekTable(const ::FLAC__StreamMetadata &object): Prototype(object) { }
			inline SeekTable(const ::FLAC__StreamMetadata *object): Prototype(object) { }
Josh Coalson's avatar
Josh Coalson committed
404
405
406
407
408
			//@}

			/** Constructs an object with copy control.  See
			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
			 */
409
			inline SeekTable(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
Josh Coalson's avatar
Josh Coalson committed
410

Josh Coalson's avatar
Josh Coalson committed
411
			~SeekTable();
Josh Coalson's avatar
Josh Coalson committed
412

Josh Coalson's avatar
Josh Coalson committed
413
414
			//@{
			/** Assign from another object.  Always performs a deep copy. */
Josh Coalson's avatar
Josh Coalson committed
415
			inline void operator=(const SeekTable &object) { Prototype::operator=(object); }
416
417
			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
Josh Coalson's avatar
Josh Coalson committed
418
			//@}
419

Josh Coalson's avatar
Josh Coalson committed
420
421
			//@{
			/** Check for equality, performing a deep compare by following pointers. */
422
			inline bool operator==(const SeekTable &object) const { return Prototype::operator==(object); }
423
424
			inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
Josh Coalson's avatar
Josh Coalson committed
425
426
427
428
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
429
			inline bool operator!=(const SeekTable &object) const { return Prototype::operator!=(object); }
430
431
			inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
Josh Coalson's avatar
Josh Coalson committed
432
			//@}
433

434
			unsigned get_num_points() const;
435
			::FLAC__StreamMetadata_SeekPoint get_point(unsigned index) const;
436

Josh Coalson's avatar
Josh Coalson committed
437
			//! See FLAC__metadata_object_seektable_set_point()
438
			void set_point(unsigned index, const ::FLAC__StreamMetadata_SeekPoint &point);
Josh Coalson's avatar
Josh Coalson committed
439
440

			//! See FLAC__metadata_object_seektable_insert_point()
441
			bool insert_point(unsigned index, const ::FLAC__StreamMetadata_SeekPoint &point);
Josh Coalson's avatar
Josh Coalson committed
442
443

			//! See FLAC__metadata_object_seektable_delete_point()
444
			bool delete_point(unsigned index);
445

Josh Coalson's avatar
Josh Coalson committed
446
			//! See FLAC__metadata_object_seektable_is_legal()
447
			bool is_legal() const;
Josh Coalson's avatar
Josh Coalson committed
448
449
		};

Josh Coalson's avatar
Josh Coalson committed
450
451
		/** VORBIS_COMMENT metadata block.
		 *  See <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>.
Josh Coalson's avatar
Josh Coalson committed
452
		 */
453
		class FLACPP_API VorbisComment : public Prototype {
Josh Coalson's avatar
Josh Coalson committed
454
		public:
Josh Coalson's avatar
Josh Coalson committed
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
			/** Convenience class for encapsulating Vorbis comment
			 *  entries.  An entry is a vendor string or a comment
			 *  field.  In the case of a vendor string, the field
			 *  name is undefined; only the field value is relevant.
			 *
			 *  A \a field as used in the methods refers to an
			 *  entire 'NAME=VALUE' string; the string is not null-
			 *  terminated and a length field is required since the
			 *  string may contain embedded nulls.
			 *
			 *  A \a field_name is what is on the left side of the
			 *  first '=' in the \a field.  By definition it is ASCII
			 *  and so is null-terminated and does not require a
			 *  length to describe it.  \a field_name is undefined
			 *  for a vendor string entry.
			 *
			 *  A \a field_value is what is on the right side of the
			 *  first '=' in the \a field.  By definition, this may
			 *  contain embedded nulls and so a \a field_value_length
			 *  is requires to describe it.
			 *
			 *  Always check is_valid() after the constructor or operator=
			 *  to make sure memory was properly allocated.
Josh Coalson's avatar
Josh Coalson committed
478
			 */
479
			class FLACPP_API Entry {
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
			public:
				Entry();
				Entry(const char *field, unsigned field_length);
				Entry(const char *field_name, const char *field_value, unsigned field_value_length);
				Entry(const Entry &entry);
				void operator=(const Entry &entry);

				virtual ~Entry();

				virtual bool is_valid() const;

				unsigned get_field_length() const;
				unsigned get_field_name_length() const;
				unsigned get_field_value_length() const;

495
				::FLAC__StreamMetadata_VorbisComment_Entry get_entry() const;
496
497
498
499
500
501
502
503
504
				const char *get_field() const;
				const char *get_field_name() const;
				const char *get_field_value() const;

				bool set_field(const char *field, unsigned field_length);
				bool set_field_name(const char *field_name);
				bool set_field_value(const char *field_value, unsigned field_value_length);
			protected:
				bool is_valid_;
505
				::FLAC__StreamMetadata_VorbisComment_Entry entry_;
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
				char *field_name_;
				unsigned field_name_length_;
				char *field_value_;
				unsigned field_value_length_;
			private:
				void zero();
				void clear();
				void clear_entry();
				void clear_field_name();
				void clear_field_value();
				void construct(const char *field, unsigned field_length);
				void construct(const char *field_name, const char *field_value, unsigned field_value_length);
				void compose_field();
				void parse_field();
			};

Josh Coalson's avatar
Josh Coalson committed
522
			VorbisComment();
Josh Coalson's avatar
Josh Coalson committed
523
524
525
526
527

			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
528
529
530
			inline VorbisComment(const VorbisComment &object): Prototype(object) { }
			inline VorbisComment(const ::FLAC__StreamMetadata &object): Prototype(object) { }
			inline VorbisComment(const ::FLAC__StreamMetadata *object): Prototype(object) { }
Josh Coalson's avatar
Josh Coalson committed
531
532
533
534
535
			//@}

			/** Constructs an object with copy control.  See
			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
			 */
536
			inline VorbisComment(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
Josh Coalson's avatar
Josh Coalson committed
537

Josh Coalson's avatar
Josh Coalson committed
538
			~VorbisComment();
Josh Coalson's avatar
Josh Coalson committed
539

Josh Coalson's avatar
Josh Coalson committed
540
541
			//@{
			/** Assign from another object.  Always performs a deep copy. */
Josh Coalson's avatar
Josh Coalson committed
542
			inline void operator=(const VorbisComment &object) { Prototype::operator=(object); }
543
544
			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
Josh Coalson's avatar
Josh Coalson committed
545
			//@}
546

Josh Coalson's avatar
Josh Coalson committed
547
548
			//@{
			/** Check for equality, performing a deep compare by following pointers. */
549
			inline bool operator==(const VorbisComment &object) const { return Prototype::operator==(object); }
550
551
			inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
Josh Coalson's avatar
Josh Coalson committed
552
553
554
555
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
556
			inline bool operator!=(const VorbisComment &object) const { return Prototype::operator!=(object); }
557
558
			inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
Josh Coalson's avatar
Josh Coalson committed
559
			//@}
560

561
			unsigned get_num_comments() const;
562
			Entry get_vendor_string() const; // only the Entry's field name should be used
563
564
			Entry get_comment(unsigned index) const;

Josh Coalson's avatar
Josh Coalson committed
565
			//! See FLAC__metadata_object_vorbiscomment_set_vendor_string()
Josh Coalson's avatar
Josh Coalson committed
566
			//! \note Only the Entry's field name will be used.
Josh Coalson's avatar
Josh Coalson committed
567
			bool set_vendor_string(const Entry &entry);
Josh Coalson's avatar
Josh Coalson committed
568

Josh Coalson's avatar
Josh Coalson committed
569
			//! See FLAC__metadata_object_vorbiscomment_set_comment()
570
			bool set_comment(unsigned index, const Entry &entry);
Josh Coalson's avatar
Josh Coalson committed
571

Josh Coalson's avatar
Josh Coalson committed
572
			//! See FLAC__metadata_object_vorbiscomment_insert_comment()
573
			bool insert_comment(unsigned index, const Entry &entry);
Josh Coalson's avatar
Josh Coalson committed
574

Josh Coalson's avatar
Josh Coalson committed
575
			//! See FLAC__metadata_object_vorbiscomment_delete_comment()
576
			bool delete_comment(unsigned index);
Josh Coalson's avatar
Josh Coalson committed
577
578
		};

Josh Coalson's avatar
Josh Coalson committed
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
		/** CUESHEET metadata block.
		 *  See <A HREF="../format.html#metadata_block_cuesheet">format specification</A>.
		 */
		class FLACPP_API CueSheet : public Prototype {
		public:
			/** Convenience class for encapsulating a cue sheet
			 *  track.
			 *
			 *  Always check is_valid() after the constructor or operator=
			 *  to make sure memory was properly allocated.
			 */
			class FLACPP_API Track {
			protected:
				::FLAC__StreamMetadata_CueSheet_Track *object_;
			public:
				Track();
				Track(const ::FLAC__StreamMetadata_CueSheet_Track *track);
				Track(const Track &track);
				void operator=(const Track &track);

				virtual ~Track();

				virtual bool is_valid() const;

				inline FLAC__uint64 get_offset() const { return object_->offset; }
				inline FLAC__byte get_number() const { return object_->number; }
				inline const char *get_isrc() const { return object_->isrc; }
				inline unsigned get_type() const { return object_->type; }
				inline bool get_pre_emphasis() const { return object_->pre_emphasis; }

				inline bool get_num_indices() const { return object_->num_indices; }
				::FLAC__StreamMetadata_CueSheet_Index get_index(unsigned i) const;

				inline const ::FLAC__StreamMetadata_CueSheet_Track *get_track() const { return object_; }

				inline void set_offset(FLAC__uint64 value) { object_->offset = value; }
				inline void set_number(FLAC__byte value) { object_->number = value; }
616
				void set_isrc(const char value[12]);
Josh Coalson's avatar
Josh Coalson committed
617
618
619
				void set_type(unsigned value);
				inline void set_pre_emphasis(bool value) { object_->pre_emphasis = value? 1 : 0; }

620
621
622
 				void set_index(unsigned i, const ::FLAC__StreamMetadata_CueSheet_Index &index);
				//@@@@ It's awkward but to insert/delete index points
				//@@@@ you must use the routines in the CueSheet class.
Josh Coalson's avatar
Josh Coalson committed
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
			};

			CueSheet();

			//@{
			/** Constructs a copy of the given object.  This form
			 *  always performs a deep copy.
			 */
			inline CueSheet(const CueSheet &object): Prototype(object) { }
			inline CueSheet(const ::FLAC__StreamMetadata &object): Prototype(object) { }
			inline CueSheet(const ::FLAC__StreamMetadata *object): Prototype(object) { }
			//@}

			/** Constructs an object with copy control.  See
			 *  Prototype(::FLAC__StreamMetadata *object, bool copy).
			 */
			inline CueSheet(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }

			~CueSheet();

			//@{
			/** Assign from another object.  Always performs a deep copy. */
			inline void operator=(const CueSheet &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
			inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
			//@}

			//@{
			/** Check for equality, performing a deep compare by following pointers. */
			inline bool operator==(const CueSheet &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
			inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
			//@}

			//@{
			/** Check for inequality, performing a deep compare by following pointers. */
			inline bool operator!=(const CueSheet &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
			inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
			//@}

			const char *get_media_catalog_number() const;
			FLAC__uint64 get_lead_in() const;

			unsigned get_num_tracks() const;
			Track get_track(unsigned i) const;

670
671
672
673
			void set_media_catalog_number(const char value[128]);
			void set_lead_in(FLAC__uint64 value);

			void set_index(unsigned track_num, unsigned index_num, const ::FLAC__StreamMetadata_CueSheet_Index &index);
Josh Coalson's avatar
Josh Coalson committed
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693

			//! See FLAC__metadata_object_cuesheet_track_insert_index()
			bool insert_index(unsigned track_num, unsigned index_num, const ::FLAC__StreamMetadata_CueSheet_Index &index);

			//! See FLAC__metadata_object_cuesheet_track_delete_index()
			bool delete_index(unsigned track_num, unsigned index_num);

			//! See FLAC__metadata_object_cuesheet_set_track()
			bool set_track(unsigned i, const Track &track);

			//! See FLAC__metadata_object_cuesheet_insert_track()
			bool insert_track(unsigned i, const Track &track);

			//! See FLAC__metadata_object_cuesheet_delete_track()
			bool delete_track(unsigned i);

			//! See FLAC__metadata_object_cuesheet_is_legal()
			bool is_legal(bool check_cd_da_subset = false, const char **violation = 0) const;
		};

Josh Coalson's avatar
Josh Coalson committed
694
695
		/* \} */

696

Josh Coalson's avatar
Josh Coalson committed
697
698
699
700
		/** \defgroup flacpp_metadata_level0 FLAC++/metadata.h: metadata level 0 interface
		 *  \ingroup flacpp_metadata
		 *
		 *  \brief
Josh Coalson's avatar
Josh Coalson committed
701
		 *  Level 0 metadata iterator.
Josh Coalson's avatar
Josh Coalson committed
702
		 *
Josh Coalson's avatar
Josh Coalson committed
703
704
		 *  See the \link flac_metadata_level0 C layer equivalent \endlink
		 *  for more.
Josh Coalson's avatar
Josh Coalson committed
705
706
707
708
		 *
		 * \{
		 */

Josh Coalson's avatar
Josh Coalson committed
709
	 	//! See FLAC__metadata_get_streaminfo().
710
		FLACPP_API bool get_streaminfo(const char *filename, StreamInfo &streaminfo);
Josh Coalson's avatar
Josh Coalson committed
711

Josh Coalson's avatar
Josh Coalson committed
712
713
		/* \} */

714

Josh Coalson's avatar
Josh Coalson committed
715
716
717
		/** \defgroup flacpp_metadata_level1 FLAC++/metadata.h: metadata level 1 interface
		 *  \ingroup flacpp_metadata
		 *
Josh Coalson's avatar
Josh Coalson committed
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
		 *  \brief
		 *  Level 1 metadata iterator.
		 *
		 *  The flow through the iterator in the C++ layer is similar
		 *  to the C layer:
		 *    - Create a SimpleIterator instance
		 *    - Check SimpleIterator::is_valid()
		 *    - Call SimpleIterator::init() and check the return
		 *    - Traverse and/or edit.  Edits are written to file
		 *      immediately.
		 *    - Destroy the SimpleIterator instance
		 *
		 *  The ownership of pointers in the C++ layer follows that in
		 *  the C layer, i.e.
		 *    - The objects returned by get_block() are yours to
		 *      modify, but changes are not reflected in the FLAC file
		 *      until you call set_block().  The objects are also
		 *      yours to delete; they are not automatically deleted
		 *      when passed to set_block() or insert_block_after().
Josh Coalson's avatar
Josh Coalson committed
737
		 *
Josh Coalson's avatar
Josh Coalson committed
738
739
		 *  See the \link flac_metadata_level1 C layer equivalent \endlink
		 *  for more.
Josh Coalson's avatar
Josh Coalson committed
740
741
742
743
		 *
		 * \{
		 */

Josh Coalson's avatar
Josh Coalson committed
744
745
		/** This class is a wrapper around the FLAC__metadata_simple_iterator
		 *  structures and methods; see ::FLAC__Metadata_SimpleIterator.
Josh Coalson's avatar
Josh Coalson committed
746
		 */
747
		class FLACPP_API SimpleIterator {
Josh Coalson's avatar
Josh Coalson committed
748
		public:
749
			class FLACPP_API Status {
Josh Coalson's avatar
Josh Coalson committed
750
			public:
751
752
753
				inline Status(::FLAC__Metadata_SimpleIteratorStatus status): status_(status) { }
				inline operator ::FLAC__Metadata_SimpleIteratorStatus() const { return status_; }
				inline const char *as_cstring() const { return ::FLAC__Metadata_SimpleIteratorStatusString[status_]; }
Josh Coalson's avatar
Josh Coalson committed
754
			protected:
755
				::FLAC__Metadata_SimpleIteratorStatus status_;
Josh Coalson's avatar
Josh Coalson committed
756
757
758
759
760
			};

			SimpleIterator();
			virtual ~SimpleIterator();

761
			bool init(const char *filename, bool read_only, bool preserve_file_stats);
Josh Coalson's avatar
Josh Coalson committed
762
763
764
765
766
767
768
769

			bool is_valid() const;
			Status status();
			bool is_writable() const;

			bool next();
			bool prev();

770
			::FLAC__MetadataType get_block_type() const;
Josh Coalson's avatar
Josh Coalson committed
771
772
773
774
775
776
			Prototype *get_block();
			bool set_block(Prototype *block, bool use_padding = true);
			bool insert_block_after(Prototype *block, bool use_padding = true);
			bool delete_block(bool use_padding = true);

		protected:
777
			::FLAC__Metadata_SimpleIterator *iterator_;
Josh Coalson's avatar
Josh Coalson committed
778
779
780
			void clear();
		};

Josh Coalson's avatar
Josh Coalson committed
781
782
		/* \} */

783

Josh Coalson's avatar
Josh Coalson committed
784
785
786
		/** \defgroup flacpp_metadata_level2 FLAC++/metadata.h: metadata level 2 interface
		 *  \ingroup flacpp_metadata
		 *
Josh Coalson's avatar
Josh Coalson committed
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
		 *  \brief
		 *  Level 2 metadata iterator.
		 *
		 *  The flow through the iterator in the C++ layer is similar
		 *  to the C layer:
		 *    - Create a Chain instance
		 *    - Check Chain::is_valid()
		 *    - Call Chain::read() and check the return
		 *    - Traverse and/or edit with an Iterator or with
		 *      Chain::merge_padding() or Chain::sort_padding()
		 *    - Write changes back to FLAC file with Chain::write()
		 *    - Destroy the Chain instance
		 *
		 *  The ownership of pointers in the C++ layer follows that in
		 *  the C layer, i.e.
		 *    - The objects returned by Iterator::get_block() are
		 *      owned by the iterator and should not be deleted.
		 *      When you modify the block, you are directly editing
		 *      what's in the chain and do not need to call
		 *      Iterator::set_block().  However the changes will not
		 *      be reflected in the FLAC file until the chain is
		 *      written with Chain::write().
		 *    - When you pass an object to Iterator::set_block(),
		 *      Iterator::insert_block_before(), or
		 *      Iterator::insert_block_after(), the iterator takes
		 *      ownership of the block and it will be deleted with the
		 *      chain.
Josh Coalson's avatar
Josh Coalson committed
814
		 *
Josh Coalson's avatar
Josh Coalson committed
815
816
		 *  See the \link flac_metadata_level2 C layer equivalent \endlink
		 *  for more.
Josh Coalson's avatar
Josh Coalson committed
817
818
819
820
		 *
		 * \{
		 */

Josh Coalson's avatar
Josh Coalson committed
821
822
		/** This class is a wrapper around the FLAC__metadata_chain
		 *  structures and methods; see ::FLAC__Metadata_Chain.
Josh Coalson's avatar
Josh Coalson committed
823
		 */
824
		class FLACPP_API Chain {
Josh Coalson's avatar
Josh Coalson committed
825
		public:
826
			class FLACPP_API Status {
Josh Coalson's avatar
Josh Coalson committed
827
			public:
828
829
830
				inline Status(::FLAC__Metadata_ChainStatus status): status_(status) { }
				inline operator ::FLAC__Metadata_ChainStatus() const { return status_; }
				inline const char *as_cstring() const { return ::FLAC__Metadata_ChainStatusString[status_]; }
Josh Coalson's avatar
Josh Coalson committed
831
			protected:
832
				::FLAC__Metadata_ChainStatus status_;
Josh Coalson's avatar
Josh Coalson committed
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
			};

			Chain();
			virtual ~Chain();

			friend class Iterator;

			bool is_valid() const;
			Status status();

			bool read(const char *filename);
			bool write(bool use_padding = true, bool preserve_file_stats = false);

			void merge_padding();
			void sort_padding();

		protected:
850
			::FLAC__Metadata_Chain *chain_;
Josh Coalson's avatar
Josh Coalson committed
851
852
853
			virtual void clear();
		};

Josh Coalson's avatar
Josh Coalson committed
854
855
		/** This class is a wrapper around the FLAC__metadata_iterator
		 *  structures and methods; see ::FLAC__Metadata_Iterator.
Josh Coalson's avatar
Josh Coalson committed
856
		 */
857
		class FLACPP_API Iterator {
Josh Coalson's avatar
Josh Coalson committed
858
859
860
861
862
863
		public:
			Iterator();
			virtual ~Iterator();

			bool is_valid() const;

864
			void init(Chain &chain);
Josh Coalson's avatar
Josh Coalson committed
865
866
867
868

			bool next();
			bool prev();

869
			::FLAC__MetadataType get_block_type() const;
Josh Coalson's avatar
Josh Coalson committed
870
871
872
873
874
875
876
			Prototype *get_block();
			bool set_block(Prototype *block);
			bool delete_block(bool replace_with_padding);
			bool insert_block_before(Prototype *block);
			bool insert_block_after(Prototype *block);

		protected:
877
			::FLAC__Metadata_Iterator *iterator_;
Josh Coalson's avatar
Josh Coalson committed
878
			virtual void clear();
Josh Coalson's avatar
Josh Coalson committed
879
880
		};

Josh Coalson's avatar
Josh Coalson committed
881
882
		/* \} */

Josh Coalson's avatar
Josh Coalson committed
883
884
885
886
	};
};

#endif