← Back to branch summary

~ubuntu-branches/ubuntu/lucid/flac/lucid-security

« back to all changes in this revision

Viewing changes to include/FLAC/metadata.h

  • Committer: Bazaar Package Importer
  • Author(s): Joshua Kwan
  • Date: 2007-05-29 22:56:36 UTC
  • mfrom: (1.1.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20070529225636-ljeff8xxip09qaap
Tags: 1.1.4-1
http://bugs.debian.org/405167
http://bugs.debian.org/411311
* New upstream release. closes: #405167, #411311
  - libOggFLAC and libOggFLAC++ have been merged into libFLAC, so
    remove their corresponding packages.
  - Because of the API changes required to effect the above, there has
    been yet another soname bump. libflac7 -> libflac8 and
    libflac++5 -> libflac++6. Emails have been dispatched to the
    maintainers of dependent packages.
* Some notes on patches that were removed:
  - 02_stdin_stdout, 06_manpage_mention_utf8_convert: merged upstream
  - 08_manpage_warnings: Upstream has changed the manpage so it defintely
    can't fit in in 80 cols, so just forget about it. We'll live.
  - 05_eof_warnings_are_errors: Upstream decided to add a -w option to
    flac to treat all warnings as errors. I am going to defer to that
    for now, but if people think it's stupid let me know and I'll port
    the patch forward.
  - 04_stack_smasher: was a backport from 1.1.3, so it's obsolete.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/FLAC/metadata.h
1
1
/* libFLAC - Free Lossless Audio Codec library
2
 
 * Copyright (C) 2001,2002,2003,2004,2005  Josh Coalson
 
2
 * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  Josh Coalson
3
3
 *
4
4
 * Redistribution and use in source and binary forms, with or without
5
5
 * modification, are permitted provided that the following conditions
36
36
#include "callback.h"
37
37
#include "format.h"
38
38
 
39
 
/******************************************************************************
40
 
        (For an example of how all these routines are used, see the source
41
 
        code for the unit tests in src/test_libFLAC/metadata_*.c, or metaflac
42
 
        in src/metaflac/)
43
 
******************************************************************************/
 
39
/* --------------------------------------------------------------------
 
40
   (For an example of how all these routines are used, see the source
 
41
   code for the unit tests in src/test_libFLAC/metadata_*.c, or
 
42
   metaflac in src/metaflac/)
 
43
   ------------------------------------------------------------------*/
44
44
 
45
45
/** \file include/FLAC/metadata.h
46
46
 *
59
59
 *  \brief
60
60
 *  This module provides functions for creating and manipulating FLAC
61
61
 *  metadata blocks in memory, and three progressively more powerful
62
 
 *  interfaces for traversing and editing metadata in FLAC files.
 
62
 *  interfaces for traversing and editing metadata in native FLAC files.
 
63
 *  Note that currently only the Chain interface (level 2) supports Ogg
 
64
 *  FLAC files, and it is read-only i.e. no writing back changed
 
65
 *  metadata to file.
63
66
 *
64
67
 *  There are three metadata interfaces of increasing complexity:
65
68
 *
66
69
 *  Level 0:
67
 
 *  Read-only access to the STREAMINFO and VORBIS_COMMENT blocks.
 
70
 *  Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and
 
71
 *  PICTURE blocks.
68
72
 *
69
73
 *  Level 1:
70
74
 *  Read-write access to all metadata blocks.  This level is write-
96
100
 *
97
101
 *  All levels access files via their filenames.  In addition, level 2
98
102
 *  has additional alternative read and write functions that take an I/O
99
 
 *  handle and callbacks, for times when access by filename is not possible.
 
103
 *  handle and callbacks, for situations where access by filename is not
 
104
 *  possible.
100
105
 *
101
106
 *  In addition to the three interfaces, this module defines functions for
102
107
 *  creating and manipulating various metadata objects in memory.  As we see
124
129
 *
125
130
 *  \brief
126
131
 *  The level 0 interface consists of individual routines to read the
127
 
 *  STREAMINFO and VORBIS_COMMENT blocks, requiring only a filename.
 
132
 *  STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring
 
133
 *  only a filename.
128
134
 *
129
 
 *  It skips any ID3v2 tag at the head of the file.
 
135
 *  They try to skip any ID3v2 tag at the head of the file.
130
136
 *
131
137
 * \{
132
138
 */
133
139
 
134
140
/** Read the STREAMINFO metadata block of the given FLAC file.  This function
135
 
 *  will skip any ID3v2 tag at the head of the file.
 
141
 *  will try to skip any ID3v2 tag at the head of the file.
136
142
 *
137
143
 * \param filename    The path to the FLAC file to read.
138
144
 * \param streaminfo  A pointer to space for the STREAMINFO block.  Since
151
157
FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
152
158
 
153
159
/** Read the VORBIS_COMMENT metadata block of the given FLAC file.  This
154
 
 *  function will skip any ID3v2 tag at the head of the file.
 
160
 *  function will try to skip any ID3v2 tag at the head of the file.
155
161
 *
156
162
 * \param filename    The path to the FLAC file to read.
157
163
 * \param tags        The address where the returned pointer will be
159
165
 *                    the caller using FLAC__metadata_object_delete().
160
166
 * \assert
161
167
 *    \code filename != NULL \endcode
162
 
 *    \code streaminfo != NULL \endcode
 
168
 *    \code tags != NULL \endcode
163
169
 * \retval FLAC__bool
164
170
 *    \c true if a valid VORBIS_COMMENT block was read from \a filename,
165
 
 *    and \a *tags will be set to the address of the tag structure.
 
171
 *    and \a *tags will be set to the address of the metadata structure.
166
172
 *    Returns \c false if there was a memory allocation error, a file
167
173
 *    decoder error, or the file contained no VORBIS_COMMENT block, and
168
174
 *    \a *tags will be set to \c NULL.
169
175
 */
170
176
FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
171
177
 
 
178
/** Read the CUESHEET metadata block of the given FLAC file.  This
 
179
 *  function will try to skip any ID3v2 tag at the head of the file.
 
180
 *
 
181
 * \param filename    The path to the FLAC file to read.
 
182
 * \param cuesheet    The address where the returned pointer will be
 
183
 *                    stored.  The \a cuesheet object must be deleted by
 
184
 *                    the caller using FLAC__metadata_object_delete().
 
185
 * \assert
 
186
 *    \code filename != NULL \endcode
 
187
 *    \code cuesheet != NULL \endcode
 
188
 * \retval FLAC__bool
 
189
 *    \c true if a valid CUESHEET block was read from \a filename,
 
190
 *    and \a *cuesheet will be set to the address of the metadata
 
191
 *    structure.  Returns \c false if there was a memory allocation
 
192
 *    error, a file decoder error, or the file contained no CUESHEET
 
193
 *    block, and \a *cuesheet will be set to \c NULL.
 
194
 */
 
195
FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
 
196
 
 
197
/** Read a PICTURE metadata block of the given FLAC file.  This
 
198
 *  function will try to skip any ID3v2 tag at the head of the file.
 
199
 *  Since there can be more than one PICTURE block in a file, this
 
200
 *  function takes a number of parameters that act as constraints to
 
201
 *  the search.  The PICTURE block with the largest area matching all
 
202
 *  the constraints will be returned, or \a *picture will be set to
 
203
 *  \c NULL if there was no such block.
 
204
 *
 
205
 * \param filename    The path to the FLAC file to read.
 
206
 * \param picture     The address where the returned pointer will be
 
207
 *                    stored.  The \a picture object must be deleted by
 
208
 *                    the caller using FLAC__metadata_object_delete().
 
209
 * \param type        The desired picture type.  Use \c -1 to mean
 
210
 *                    "any type".
 
211
 * \param mime_type   The desired MIME type, e.g. "image/jpeg".  The
 
212
 *                    string will be matched exactly.  Use \c NULL to
 
213
 *                    mean "any MIME type".
 
214
 * \param description The desired description.  The string will be
 
215
 *                    matched exactly.  Use \c NULL to mean "any
 
216
 *                    description".
 
217
 * \param max_width   The maximum width in pixels desired.  Use
 
218
 *                    \c (unsigned)(-1) to mean "any width".
 
219
 * \param max_height  The maximum height in pixels desired.  Use
 
220
 *                    \c (unsigned)(-1) to mean "any height".
 
221
 * \param max_depth   The maximum color depth in bits-per-pixel desired.
 
222
 *                    Use \c (unsigned)(-1) to mean "any depth".
 
223
 * \param max_colors  The maximum number of colors desired.  Use
 
224
 *                    \c (unsigned)(-1) to mean "any number of colors".
 
225
 * \assert
 
226
 *    \code filename != NULL \endcode
 
227
 *    \code picture != NULL \endcode
 
228
 * \retval FLAC__bool
 
229
 *    \c true if a valid PICTURE block was read from \a filename,
 
230
 *    and \a *picture will be set to the address of the metadata
 
231
 *    structure.  Returns \c false if there was a memory allocation
 
232
 *    error, a file decoder error, or the file contained no PICTURE
 
233
 *    block, and \a *picture will be set to \c NULL.
 
234
 */
 
235
FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors);
 
236
 
172
237
/* \} */
173
238
 
174
239
 
184
249
 * - Create an iterator using FLAC__metadata_simple_iterator_new()
185
250
 * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check
186
251
 *   the exit code.  Call FLAC__metadata_simple_iterator_is_writable() to
187
 
 *   see if the file is writable, or read-only access is allowed.
 
252
 *   see if the file is writable, or only read access is allowed.
188
253
 * - Use FLAC__metadata_simple_iterator_next() and
189
 
 *   FLAC__metadata_simple_iterator_prev() to move around the blocks.
 
254
 *   FLAC__metadata_simple_iterator_prev() to traverse the blocks.
190
255
 *   This is does not read the actual blocks themselves.
191
256
 *   FLAC__metadata_simple_iterator_next() is relatively fast.
192
257
 *   FLAC__metadata_simple_iterator_prev() is slower since it needs to search
295
360
 * \retval FLAC__Metadata_SimpleIterator*
296
361
 *    \c NULL if there was an error allocating memory, else the new instance.
297
362
 */
298
 
FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new();
 
363
FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
299
364
 
300
365
/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
301
366
 *
521
586
 * all metadata is read into memory, operated on in memory, and then written
522
587
 * to file, which is more efficient than level 1 when editing multiple blocks.
523
588
 *
 
589
 * Currently Ogg FLAC is supported for read only, via
 
590
 * FLAC__metadata_chain_read_ogg() but a subsequent
 
591
 * FLAC__metadata_chain_write() will fail.
 
592
 *
524
593
 * The general usage of this interface is:
525
594
 *
526
595
 * - Create a new chain using FLAC__metadata_chain_new().  A chain is a
527
596
 *   linked list of FLAC metadata blocks.
528
597
 * - Read all metadata into the the chain from a FLAC file using
529
 
 *   FLAC__metadata_chain_read() and check the status.
 
598
 *   FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and
 
599
 *   check the status.
530
600
 * - Optionally, consolidate the padding using
531
601
 *   FLAC__metadata_chain_merge_padding() or
532
602
 *   FLAC__metadata_chain_sort_padding().
548
618
 * Even though the FLAC file is not open while the chain is being
549
619
 * manipulated, you must not alter the file externally during
550
620
 * this time.  The chain assumes the FLAC file will not change
551
 
 * between the time of FLAC__metadata_chain_read() and
552
 
 * FLAC__metadata_chain_write().
 
621
 * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg()
 
622
 * and FLAC__metadata_chain_write().
553
623
 *
554
624
 * \note
555
625
 * Do not modify the is_last, length, or type fields of returned
620
690
 
621
691
        FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
622
692
        /**< FLAC__metadata_chain_write() was called on a chain read by
623
 
         *   FLAC__metadata_chain_read_with_callbacks(), or
624
 
         *   FLAC__metadata_chain_write_with_callbacks() or
625
 
         *   FLAC__metadata_chain_write_with_callbacks_and_tempfile() was
626
 
         *   called on a chain read by FLAC__metadata_chain_read().  Matching
627
 
         *   read/write methods must always be used. */
 
693
         *   FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
 
694
         *   or 
 
695
         *   FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile()
 
696
         *   was called on a chain read by
 
697
         *   FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
 
698
         *   Matching read/write methods must always be used. */
628
699
 
629
700
        FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
630
701
        /**< FLAC__metadata_chain_write_with_callbacks() was called when the
652
723
 * \retval FLAC__Metadata_Chain*
653
724
 *    \c NULL if there was an error allocating memory, else the new instance.
654
725
 */
655
 
FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new();
 
726
FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
656
727
 
657
728
/** Free a chain instance.  Deletes the object pointed to by \a chain.
658
729
 *
688
759
 */
689
760
FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
690
761
 
 
762
/*@@@@ add to unit tests*/
 
763
/** Read all metadata from an Ogg FLAC file into the chain.
 
764
 *
 
765
 * \note Ogg FLAC metadata data writing is not supported yet and
 
766
 * FLAC__metadata_chain_write() will fail.
 
767
 *
 
768
 * \param chain    A pointer to an existing chain.
 
769
 * \param filename The path to the Ogg FLAC file to read.
 
770
 * \assert
 
771
 *    \code chain != NULL \endcode
 
772
 *    \code filename != NULL \endcode
 
773
 * \retval FLAC__bool
 
774
 *    \c true if a valid list of metadata blocks was read from
 
775
 *    \a filename, else \c false.  On failure, check the status with
 
776
 *    FLAC__metadata_chain_status().
 
777
 */
 
778
FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
 
779
 
691
780
/** Read all metadata from a FLAC stream into the chain via I/O callbacks.
692
781
 *
693
782
 *  The \a handle need only be open for reading, but must be seekable.
710
799
 */
711
800
FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
712
801
 
 
802
/*@@@@ add to unit tests*/
 
803
/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks.
 
804
 *
 
805
 *  The \a handle need only be open for reading, but must be seekable.
 
806
 *  The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb"
 
807
 *  for Windows).
 
808
 *
 
809
 * \note Ogg FLAC metadata data writing is not supported yet and
 
810
 * FLAC__metadata_chain_write() will fail.
 
811
 *
 
812
 * \param chain    A pointer to an existing chain.
 
813
 * \param handle   The I/O handle of the Ogg FLAC stream to read.  The
 
814
 *                 handle will NOT be closed after the metadata is read;
 
815
 *                 that is the duty of the caller.
 
816
 * \param callbacks
 
817
 *                 A set of callbacks to use for I/O.  The mandatory
 
818
 *                 callbacks are \a read, \a seek, and \a tell.
 
819
 * \assert
 
820
 *    \code chain != NULL \endcode
 
821
 * \retval FLAC__bool
 
822
 *    \c true if a valid list of metadata blocks was read from
 
823
 *    \a handle, else \c false.  On failure, check the status with
 
824
 *    FLAC__metadata_chain_status().
 
825
 */
 
826
FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
 
827
 
713
828
/** Checks if writing the given chain would require the use of a
714
829
 *  temporary file, or if it could be written in place.
715
830
 *
770
885
 *  be preserved even if the FLAC file is written.
771
886
 *
772
887
 *  For this write function to be used, the chain must have been read with
773
 
 *  FLAC__metadata_chain_read(), not FLAC__metadata_chain_read_with_callbacks().
 
888
 *  FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not
 
889
 *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks().
774
890
 *
775
891
 * \param chain               A pointer to an existing chain.
776
892
 * \param use_padding         See above.
793
909
 *  for Windows).
794
910
 *
795
911
 *  For this write function to be used, the chain must have been read with
796
 
 *  FLAC__metadata_chain_read_with_callbacks(), not FLAC__metadata_chain_read().
 
912
 *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
 
913
 *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
797
914
 *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
798
915
 *  \c false.
799
916
 *
836
953
 *  truncate it on return).
837
954
 *
838
955
 *  For this write function to be used, the chain must have been read with
839
 
 *  FLAC__metadata_chain_read_with_callbacks(), not FLAC__metadata_chain_read().
 
956
 *  FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(),
 
957
 *  not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg().
840
958
 *  Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned
841
959
 *  \c true.
842
960
 *
899
1017
 * \retval FLAC__Metadata_Iterator*
900
1018
 *    \c NULL if there was an error allocating memory, else the new instance.
901
1019
 */
902
 
FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new();
 
1020
FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
903
1021
 
904
1022
/** Free an iterator instance.  Deletes the object pointed to by \a iterator.
905
1023
 *
1166
1284
/** Sets the application data of an APPLICATION block.
1167
1285
 *
1168
1286
 *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
1169
 
 *  takes ownership of the pointer.
 
1287
 *  takes ownership of the pointer.  The existing data will be freed if this
 
1288
 *  function is successful, otherwise the original data will remain if \a copy
 
1289
 *  is \c true and malloc() fails.
 
1290
 *
 
1291
 * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
1170
1292
 *
1171
1293
 * \param object  A pointer to an existing APPLICATION object.
1172
1294
 * \param data    A pointer to the data to set.
1319
1441
 * \assert
1320
1442
 *    \code object != NULL \endcode
1321
1443
 *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 
1444
 *    \code total_samples > 0 \endcode
1322
1445
 * \retval FLAC__bool
1323
1446
 *    \c false if memory allocation fails, else \c true.
1324
1447
 */
1325
1448
FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
1326
1449
 
 
1450
/** Append a set of evenly-spaced seek point templates to the end of a
 
1451
 *  seek table.
 
1452
 *
 
1453
 * \note
 
1454
 * As with the other ..._seektable_template_... functions, you should
 
1455
 * call FLAC__metadata_object_seektable_template_sort() when finished
 
1456
 * to make the seek table legal.
 
1457
 *
 
1458
 * \param object  A pointer to an existing SEEKTABLE object.
 
1459
 * \param samples The number of samples apart to space the placeholder
 
1460
 *                points.  The first point will be at sample \c 0, the
 
1461
 *                second at sample \a samples, then 2*\a samples, and
 
1462
 *                so on.  As long as \a samples and \a total_samples
 
1463
 *                are greater than \c 0, there will always be at least
 
1464
 *                one seekpoint at sample \c 0.
 
1465
 * \param total_samples  The total number of samples to be encoded;
 
1466
 *                       the seekpoints will be spaced
 
1467
 *                       \a samples samples apart.
 
1468
 * \assert
 
1469
 *    \code object != NULL \endcode
 
1470
 *    \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
 
1471
 *    \code samples > 0 \endcode
 
1472
 *    \code total_samples > 0 \endcode
 
1473
 * \retval FLAC__bool
 
1474
 *    \c false if memory allocation fails, else \c true.
 
1475
 */
 
1476
FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
 
1477
 
1327
1478
/** Sort a seek table's seek points according to the format specification,
1328
1479
 *  removing duplicates.
1329
1480
 *
1621
1772
 * \retval FLAC__StreamMetadata_CueSheet_Track*
1622
1773
 *    \c NULL if there was an error allocating memory, else the new instance.
1623
1774
 */
1624
 
FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new();
 
1775
FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
1625
1776
 
1626
1777
/** Create a copy of an existing CUESHEET track object.
1627
1778
 *
1849
2000
 */
1850
2001
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
1851
2002
 
 
2003
/* @@@@ add to unit tests */
 
2004
/** Calculate and return the CDDB/freedb ID for a cue sheet.  The function
 
2005
 *  assumes the cue sheet corresponds to a CD; the result is undefined
 
2006
 *  if the cuesheet's is_cd bit is not set.
 
2007
 *
 
2008
 * \param object     A pointer to an existing CUESHEET object.
 
2009
 * \assert
 
2010
 *    \code object != NULL \endcode
 
2011
 *    \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
 
2012
 * \retval FLAC__uint32
 
2013
 *    The unsigned integer representation of the CDDB/freedb ID
 
2014
 */
 
2015
FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
 
2016
 
 
2017
/** Sets the MIME type of a PICTURE block.
 
2018
 *
 
2019
 *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
 
2020
 *  takes ownership of the pointer.  The existing string will be freed if this
 
2021
 *  function is successful, otherwise the original string will remain if \a copy
 
2022
 *  is \c true and malloc() fails.
 
2023
 *
 
2024
 * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true.
 
2025
 *
 
2026
 * \param object      A pointer to an existing PICTURE object.
 
2027
 * \param mime_type   A pointer to the MIME type string.  The string must be
 
2028
 *                    ASCII characters 0x20-0x7e, NUL-terminated.  No validation
 
2029
 *                    is done.
 
2030
 * \param copy        See above.
 
2031
 * \assert
 
2032
 *    \code object != NULL \endcode
 
2033
 *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 
2034
 *    \code (mime_type != NULL) \endcode
 
2035
 * \retval FLAC__bool
 
2036
 *    \c false if \a copy is \c true and malloc() fails, else \c true.
 
2037
 */
 
2038
FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
 
2039
 
 
2040
/** Sets the description of a PICTURE block.
 
2041
 *
 
2042
 *  If \a copy is \c true, a copy of the string is stored; otherwise, the object
 
2043
 *  takes ownership of the pointer.  The existing string will be freed if this
 
2044
 *  function is successful, otherwise the original string will remain if \a copy
 
2045
 *  is \c true and malloc() fails.
 
2046
 *
 
2047
 * \note It is safe to pass a const pointer to \a description if \a copy is \c true.
 
2048
 *
 
2049
 * \param object      A pointer to an existing PICTURE object.
 
2050
 * \param description A pointer to the description string.  The string must be
 
2051
 *                    valid UTF-8, NUL-terminated.  No validation is done.
 
2052
 * \param copy        See above.
 
2053
 * \assert
 
2054
 *    \code object != NULL \endcode
 
2055
 *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 
2056
 *    \code (description != NULL) \endcode
 
2057
 * \retval FLAC__bool
 
2058
 *    \c false if \a copy is \c true and malloc() fails, else \c true.
 
2059
 */
 
2060
FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
 
2061
 
 
2062
/** Sets the picture data of a PICTURE block.
 
2063
 *
 
2064
 *  If \a copy is \c true, a copy of the data is stored; otherwise, the object
 
2065
 *  takes ownership of the pointer.  Also sets the \a data_length field of the
 
2066
 *  metadata object to what is passed in as the \a length parameter.  The
 
2067
 *  existing data will be freed if this function is successful, otherwise the
 
2068
 *  original data and data_length will remain if \a copy is \c true and
 
2069
 *  malloc() fails.
 
2070
 *
 
2071
 * \note It is safe to pass a const pointer to \a data if \a copy is \c true.
 
2072
 *
 
2073
 * \param object  A pointer to an existing PICTURE object.
 
2074
 * \param data    A pointer to the data to set.
 
2075
 * \param length  The length of \a data in bytes.
 
2076
 * \param copy    See above.
 
2077
 * \assert
 
2078
 *    \code object != NULL \endcode
 
2079
 *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 
2080
 *    \code (data != NULL && length > 0) ||
 
2081
 * (data == NULL && length == 0 && copy == false) \endcode
 
2082
 * \retval FLAC__bool
 
2083
 *    \c false if \a copy is \c true and malloc() fails, else \c true.
 
2084
 */
 
2085
FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
 
2086
 
 
2087
/** Check a PICTURE block to see if it conforms to the FLAC specification.
 
2088
 *  See the format specification for limits on the contents of the
 
2089
 *  PICTURE block.
 
2090
 *
 
2091
 * \param object     A pointer to existing PICTURE block to be checked.
 
2092
 * \param violation  Address of a pointer to a string.  If there is a
 
2093
 *                   violation, a pointer to a string explanation of the
 
2094
 *                   violation will be returned here. \a violation may be
 
2095
 *                   \c NULL if you don't need the returned string.  Do not
 
2096
 *                   free the returned string; it will always point to static
 
2097
 *                   data.
 
2098
 * \assert
 
2099
 *    \code object != NULL \endcode
 
2100
 *    \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode
 
2101
 * \retval FLAC__bool
 
2102
 *    \c false if PICTURE block is illegal, else \c true.
 
2103
 */
 
2104
FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
 
2105
 
1852
2106
/* \} */
1853
2107
 
1854
2108
#ifdef __cplusplus