diff options
Diffstat (limited to 'apps/codecs/libFLAC/include/FLAC/metadata.h')
-rw-r--r-- | apps/codecs/libFLAC/include/FLAC/metadata.h | 1858 |
1 files changed, 1858 insertions, 0 deletions
diff --git a/apps/codecs/libFLAC/include/FLAC/metadata.h b/apps/codecs/libFLAC/include/FLAC/metadata.h new file mode 100644 index 0000000000..ff40e6d5ed --- /dev/null +++ b/apps/codecs/libFLAC/include/FLAC/metadata.h | |||
@@ -0,0 +1,1858 @@ | |||
1 | /* libFLAC - Free Lossless Audio Codec library | ||
2 | * Copyright (C) 2001,2002,2003,2004,2005 Josh Coalson | ||
3 | * | ||
4 | * Redistribution and use in source and binary forms, with or without | ||
5 | * modification, are permitted provided that the following conditions | ||
6 | * are met: | ||
7 | * | ||
8 | * - Redistributions of source code must retain the above copyright | ||
9 | * notice, this list of conditions and the following disclaimer. | ||
10 | * | ||
11 | * - Redistributions in binary form must reproduce the above copyright | ||
12 | * notice, this list of conditions and the following disclaimer in the | ||
13 | * documentation and/or other materials provided with the distribution. | ||
14 | * | ||
15 | * - Neither the name of the Xiph.org Foundation nor the names of its | ||
16 | * contributors may be used to endorse or promote products derived from | ||
17 | * this software without specific prior written permission. | ||
18 | * | ||
19 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
20 | * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
21 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
22 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR | ||
23 | * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | ||
24 | * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | ||
25 | * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | ||
26 | * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | ||
27 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | ||
28 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
29 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
30 | */ | ||
31 | |||
32 | #ifndef FLAC__METADATA_H | ||
33 | #define FLAC__METADATA_H | ||
34 | |||
35 | #include "export.h" | ||
36 | #include "callback.h" | ||
37 | #include "format.h" | ||
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 | ******************************************************************************/ | ||
44 | |||
45 | /** \file include/FLAC/metadata.h | ||
46 | * | ||
47 | * \brief | ||
48 | * This module provides functions for creating and manipulating FLAC | ||
49 | * metadata blocks in memory, and three progressively more powerful | ||
50 | * interfaces for traversing and editing metadata in FLAC files. | ||
51 | * | ||
52 | * See the detailed documentation for each interface in the | ||
53 | * \link flac_metadata metadata \endlink module. | ||
54 | */ | ||
55 | |||
56 | /** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces | ||
57 | * \ingroup flac | ||
58 | * | ||
59 | * \brief | ||
60 | * This module provides functions for creating and manipulating FLAC | ||
61 | * metadata blocks in memory, and three progressively more powerful | ||
62 | * interfaces for traversing and editing metadata in FLAC files. | ||
63 | * | ||
64 | * There are three metadata interfaces of increasing complexity: | ||
65 | * | ||
66 | * Level 0: | ||
67 | * Read-only access to the STREAMINFO and VORBIS_COMMENT blocks. | ||
68 | * | ||
69 | * Level 1: | ||
70 | * Read-write access to all metadata blocks. This level is write- | ||
71 | * efficient in most cases (more on this below), and uses less memory | ||
72 | * than level 2. | ||
73 | * | ||
74 | * Level 2: | ||
75 | * Read-write access to all metadata blocks. This level is write- | ||
76 | * efficient in all cases, but uses more memory since all metadata for | ||
77 | * the whole file is read into memory and manipulated before writing | ||
78 | * out again. | ||
79 | * | ||
80 | * What do we mean by efficient? Since FLAC metadata appears at the | ||
81 | * beginning of the file, when writing metadata back to a FLAC file | ||
82 | * it is possible to grow or shrink the metadata such that the entire | ||
83 | * file must be rewritten. However, if the size remains the same during | ||
84 | * changes or PADDING blocks are utilized, only the metadata needs to be | ||
85 | * overwritten, which is much faster. | ||
86 | * | ||
87 | * Efficient means the whole file is rewritten at most one time, and only | ||
88 | * when necessary. Level 1 is not efficient only in the case that you | ||
89 | * cause more than one metadata block to grow or shrink beyond what can | ||
90 | * be accomodated by padding. In this case you should probably use level | ||
91 | * 2, which allows you to edit all the metadata for a file in memory and | ||
92 | * write it out all at once. | ||
93 | * | ||
94 | * All levels know how to skip over and not disturb an ID3v2 tag at the | ||
95 | * front of the file. | ||
96 | * | ||
97 | * All levels access files via their filenames. In addition, level 2 | ||
98 | * 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. | ||
100 | * | ||
101 | * In addition to the three interfaces, this module defines functions for | ||
102 | * creating and manipulating various metadata objects in memory. As we see | ||
103 | * from the Format module, FLAC metadata blocks in memory are very primitive | ||
104 | * structures for storing information in an efficient way. Reading | ||
105 | * information from the structures is easy but creating or modifying them | ||
106 | * directly is more complex. The metadata object routines here facilitate | ||
107 | * this by taking care of the consistency and memory management drudgery. | ||
108 | * | ||
109 | * Unless you will be using the level 1 or 2 interfaces to modify existing | ||
110 | * metadata however, you will not probably not need these. | ||
111 | * | ||
112 | * From a dependency standpoint, none of the encoders or decoders require | ||
113 | * the metadata module. This is so that embedded users can strip out the | ||
114 | * metadata module from libFLAC to reduce the size and complexity. | ||
115 | */ | ||
116 | |||
117 | #ifdef __cplusplus | ||
118 | extern "C" { | ||
119 | #endif | ||
120 | |||
121 | |||
122 | /** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface | ||
123 | * \ingroup flac_metadata | ||
124 | * | ||
125 | * \brief | ||
126 | * The level 0 interface consists of individual routines to read the | ||
127 | * STREAMINFO and VORBIS_COMMENT blocks, requiring only a filename. | ||
128 | * | ||
129 | * It skips any ID3v2 tag at the head of the file. | ||
130 | * | ||
131 | * \{ | ||
132 | */ | ||
133 | |||
134 | /** Read the STREAMINFO metadata block of the given FLAC file. This function | ||
135 | * will skip any ID3v2 tag at the head of the file. | ||
136 | * | ||
137 | * \param filename The path to the FLAC file to read. | ||
138 | * \param streaminfo A pointer to space for the STREAMINFO block. Since | ||
139 | * FLAC__StreamMetadata is a simple structure with no | ||
140 | * memory allocation involved, you pass the address of | ||
141 | * an existing structure. It need not be initialized. | ||
142 | * \assert | ||
143 | * \code filename != NULL \endcode | ||
144 | * \code streaminfo != NULL \endcode | ||
145 | * \retval FLAC__bool | ||
146 | * \c true if a valid STREAMINFO block was read from \a filename. Returns | ||
147 | * \c false if there was a memory allocation error, a file decoder error, | ||
148 | * or the file contained no STREAMINFO block. (A memory allocation error | ||
149 | * is possible because this function must set up a file decoder.) | ||
150 | */ | ||
151 | FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo); | ||
152 | |||
153 | /** 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. | ||
155 | * | ||
156 | * \param filename The path to the FLAC file to read. | ||
157 | * \param tags The address where the returned pointer will be | ||
158 | * stored. The \a tags object must be deleted by | ||
159 | * the caller using FLAC__metadata_object_delete(). | ||
160 | * \assert | ||
161 | * \code filename != NULL \endcode | ||
162 | * \code streaminfo != NULL \endcode | ||
163 | * \retval FLAC__bool | ||
164 | * \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. | ||
166 | * Returns \c false if there was a memory allocation error, a file | ||
167 | * decoder error, or the file contained no VORBIS_COMMENT block, and | ||
168 | * \a *tags will be set to \c NULL. | ||
169 | */ | ||
170 | FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags); | ||
171 | |||
172 | /* \} */ | ||
173 | |||
174 | |||
175 | /** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface | ||
176 | * \ingroup flac_metadata | ||
177 | * | ||
178 | * \brief | ||
179 | * The level 1 interface provides read-write access to FLAC file metadata and | ||
180 | * operates directly on the FLAC file. | ||
181 | * | ||
182 | * The general usage of this interface is: | ||
183 | * | ||
184 | * - Create an iterator using FLAC__metadata_simple_iterator_new() | ||
185 | * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check | ||
186 | * the exit code. Call FLAC__metadata_simple_iterator_is_writable() to | ||
187 | * see if the file is writable, or read-only access is allowed. | ||
188 | * - Use FLAC__metadata_simple_iterator_next() and | ||
189 | * FLAC__metadata_simple_iterator_prev() to move around the blocks. | ||
190 | * This is does not read the actual blocks themselves. | ||
191 | * FLAC__metadata_simple_iterator_next() is relatively fast. | ||
192 | * FLAC__metadata_simple_iterator_prev() is slower since it needs to search | ||
193 | * forward from the front of the file. | ||
194 | * - Use FLAC__metadata_simple_iterator_get_block_type() or | ||
195 | * FLAC__metadata_simple_iterator_get_block() to access the actual data at | ||
196 | * the current iterator position. The returned object is yours to modify | ||
197 | * and free. | ||
198 | * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block | ||
199 | * back. You must have write permission to the original file. Make sure to | ||
200 | * read the whole comment to FLAC__metadata_simple_iterator_set_block() | ||
201 | * below. | ||
202 | * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks. | ||
203 | * Use the object creation functions from | ||
204 | * \link flac_metadata_object here \endlink to generate new objects. | ||
205 | * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block | ||
206 | * currently referred to by the iterator, or replace it with padding. | ||
207 | * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when | ||
208 | * finished. | ||
209 | * | ||
210 | * \note | ||
211 | * The FLAC file remains open the whole time between | ||
212 | * FLAC__metadata_simple_iterator_init() and | ||
213 | * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering | ||
214 | * the file during this time. | ||
215 | * | ||
216 | * \note | ||
217 | * Do not modify the \a is_last, \a length, or \a type fields of returned | ||
218 | * FLAC__StreamMetadata objects. These are managed automatically. | ||
219 | * | ||
220 | * \note | ||
221 | * If any of the modification functions | ||
222 | * (FLAC__metadata_simple_iterator_set_block(), | ||
223 | * FLAC__metadata_simple_iterator_delete_block(), | ||
224 | * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false, | ||
225 | * you should delete the iterator as it may no longer be valid. | ||
226 | * | ||
227 | * \{ | ||
228 | */ | ||
229 | |||
230 | struct FLAC__Metadata_SimpleIterator; | ||
231 | /** The opaque structure definition for the level 1 iterator type. | ||
232 | * See the | ||
233 | * \link flac_metadata_level1 metadata level 1 module \endlink | ||
234 | * for a detailed description. | ||
235 | */ | ||
236 | typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator; | ||
237 | |||
238 | /** Status type for FLAC__Metadata_SimpleIterator. | ||
239 | * | ||
240 | * The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status(). | ||
241 | */ | ||
242 | typedef enum { | ||
243 | |||
244 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0, | ||
245 | /**< The iterator is in the normal OK state */ | ||
246 | |||
247 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, | ||
248 | /**< The data passed into a function violated the function's usage criteria */ | ||
249 | |||
250 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE, | ||
251 | /**< The iterator could not open the target file */ | ||
252 | |||
253 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE, | ||
254 | /**< The iterator could not find the FLAC signature at the start of the file */ | ||
255 | |||
256 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE, | ||
257 | /**< The iterator tried to write to a file that was not writable */ | ||
258 | |||
259 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA, | ||
260 | /**< The iterator encountered input that does not conform to the FLAC metadata specification */ | ||
261 | |||
262 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR, | ||
263 | /**< The iterator encountered an error while reading the FLAC file */ | ||
264 | |||
265 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, | ||
266 | /**< The iterator encountered an error while seeking in the FLAC file */ | ||
267 | |||
268 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR, | ||
269 | /**< The iterator encountered an error while writing the FLAC file */ | ||
270 | |||
271 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR, | ||
272 | /**< The iterator encountered an error renaming the FLAC file */ | ||
273 | |||
274 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR, | ||
275 | /**< The iterator encountered an error removing the temporary file */ | ||
276 | |||
277 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR, | ||
278 | /**< Memory allocation failed */ | ||
279 | |||
280 | FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR | ||
281 | /**< The caller violated an assertion or an unexpected error occurred */ | ||
282 | |||
283 | } FLAC__Metadata_SimpleIteratorStatus; | ||
284 | |||
285 | /** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string. | ||
286 | * | ||
287 | * Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array | ||
288 | * will give the string equivalent. The contents should not be modified. | ||
289 | */ | ||
290 | extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[]; | ||
291 | |||
292 | |||
293 | /** Create a new iterator instance. | ||
294 | * | ||
295 | * \retval FLAC__Metadata_SimpleIterator* | ||
296 | * \c NULL if there was an error allocating memory, else the new instance. | ||
297 | */ | ||
298 | FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(); | ||
299 | |||
300 | /** Free an iterator instance. Deletes the object pointed to by \a iterator. | ||
301 | * | ||
302 | * \param iterator A pointer to an existing iterator. | ||
303 | * \assert | ||
304 | * \code iterator != NULL \endcode | ||
305 | */ | ||
306 | FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator); | ||
307 | |||
308 | /** Get the current status of the iterator. Call this after a function | ||
309 | * returns \c false to get the reason for the error. Also resets the status | ||
310 | * to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK. | ||
311 | * | ||
312 | * \param iterator A pointer to an existing iterator. | ||
313 | * \assert | ||
314 | * \code iterator != NULL \endcode | ||
315 | * \retval FLAC__Metadata_SimpleIteratorStatus | ||
316 | * The current status of the iterator. | ||
317 | */ | ||
318 | FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator); | ||
319 | |||
320 | /** Initialize the iterator to point to the first metadata block in the | ||
321 | * given FLAC file. | ||
322 | * | ||
323 | * \param iterator A pointer to an existing iterator. | ||
324 | * \param filename The path to the FLAC file. | ||
325 | * \param read_only If \c true, the FLAC file will be opened | ||
326 | * in read-only mode; if \c false, the FLAC | ||
327 | * file will be opened for edit even if no | ||
328 | * edits are performed. | ||
329 | * \param preserve_file_stats If \c true, the owner and modification | ||
330 | * time will be preserved even if the FLAC | ||
331 | * file is written to. | ||
332 | * \assert | ||
333 | * \code iterator != NULL \endcode | ||
334 | * \code filename != NULL \endcode | ||
335 | * \retval FLAC__bool | ||
336 | * \c false if a memory allocation error occurs, the file can't be | ||
337 | * opened, or another error occurs, else \c true. | ||
338 | */ | ||
339 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats); | ||
340 | |||
341 | /** Returns \c true if the FLAC file is writable. If \c false, calls to | ||
342 | * FLAC__metadata_simple_iterator_set_block() and | ||
343 | * FLAC__metadata_simple_iterator_insert_block_after() will fail. | ||
344 | * | ||
345 | * \param iterator A pointer to an existing iterator. | ||
346 | * \assert | ||
347 | * \code iterator != NULL \endcode | ||
348 | * \retval FLAC__bool | ||
349 | * See above. | ||
350 | */ | ||
351 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator); | ||
352 | |||
353 | /** Moves the iterator forward one metadata block, returning \c false if | ||
354 | * already at the end. | ||
355 | * | ||
356 | * \param iterator A pointer to an existing initialized iterator. | ||
357 | * \assert | ||
358 | * \code iterator != NULL \endcode | ||
359 | * \a iterator has been successfully initialized with | ||
360 | * FLAC__metadata_simple_iterator_init() | ||
361 | * \retval FLAC__bool | ||
362 | * \c false if already at the last metadata block of the chain, else | ||
363 | * \c true. | ||
364 | */ | ||
365 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator); | ||
366 | |||
367 | /** Moves the iterator backward one metadata block, returning \c false if | ||
368 | * already at the beginning. | ||
369 | * | ||
370 | * \param iterator A pointer to an existing initialized iterator. | ||
371 | * \assert | ||
372 | * \code iterator != NULL \endcode | ||
373 | * \a iterator has been successfully initialized with | ||
374 | * FLAC__metadata_simple_iterator_init() | ||
375 | * \retval FLAC__bool | ||
376 | * \c false if already at the first metadata block of the chain, else | ||
377 | * \c true. | ||
378 | */ | ||
379 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator); | ||
380 | |||
381 | /** Get the type of the metadata block at the current position. This | ||
382 | * avoids reading the actual block data which can save time for large | ||
383 | * blocks. | ||
384 | * | ||
385 | * \param iterator A pointer to an existing initialized iterator. | ||
386 | * \assert | ||
387 | * \code iterator != NULL \endcode | ||
388 | * \a iterator has been successfully initialized with | ||
389 | * FLAC__metadata_simple_iterator_init() | ||
390 | * \retval FLAC__MetadataType | ||
391 | * The type of the metadata block at the current iterator position. | ||
392 | */ | ||
393 | |||
394 | FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator); | ||
395 | |||
396 | /** Get the metadata block at the current position. You can modify the | ||
397 | * block but must use FLAC__metadata_simple_iterator_set_block() to | ||
398 | * write it back to the FLAC file. | ||
399 | * | ||
400 | * You must call FLAC__metadata_object_delete() on the returned object | ||
401 | * when you are finished with it. | ||
402 | * | ||
403 | * \param iterator A pointer to an existing initialized iterator. | ||
404 | * \assert | ||
405 | * \code iterator != NULL \endcode | ||
406 | * \a iterator has been successfully initialized with | ||
407 | * FLAC__metadata_simple_iterator_init() | ||
408 | * \retval FLAC__StreamMetadata* | ||
409 | * The current metadata block. | ||
410 | */ | ||
411 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator); | ||
412 | |||
413 | /** Write a block back to the FLAC file. This function tries to be | ||
414 | * as efficient as possible; how the block is actually written is | ||
415 | * shown by the following: | ||
416 | * | ||
417 | * Existing block is a STREAMINFO block and the new block is a | ||
418 | * STREAMINFO block: the new block is written in place. Make sure | ||
419 | * you know what you're doing when changing the values of a | ||
420 | * STREAMINFO block. | ||
421 | * | ||
422 | * Existing block is a STREAMINFO block and the new block is a | ||
423 | * not a STREAMINFO block: this is an error since the first block | ||
424 | * must be a STREAMINFO block. Returns \c false without altering the | ||
425 | * file. | ||
426 | * | ||
427 | * Existing block is not a STREAMINFO block and the new block is a | ||
428 | * STREAMINFO block: this is an error since there may be only one | ||
429 | * STREAMINFO block. Returns \c false without altering the file. | ||
430 | * | ||
431 | * Existing block and new block are the same length: the existing | ||
432 | * block will be replaced by the new block, written in place. | ||
433 | * | ||
434 | * Existing block is longer than new block: if use_padding is \c true, | ||
435 | * the existing block will be overwritten in place with the new | ||
436 | * block followed by a PADDING block, if possible, to make the total | ||
437 | * size the same as the existing block. Remember that a padding | ||
438 | * block requires at least four bytes so if the difference in size | ||
439 | * between the new block and existing block is less than that, the | ||
440 | * entire file will have to be rewritten, using the new block's | ||
441 | * exact size. If use_padding is \c false, the entire file will be | ||
442 | * rewritten, replacing the existing block by the new block. | ||
443 | * | ||
444 | * Existing block is shorter than new block: if use_padding is \c true, | ||
445 | * the function will try and expand the new block into the following | ||
446 | * PADDING block, if it exists and doing so won't shrink the PADDING | ||
447 | * block to less than 4 bytes. If there is no following PADDING | ||
448 | * block, or it will shrink to less than 4 bytes, or use_padding is | ||
449 | * \c false, the entire file is rewritten, replacing the existing block | ||
450 | * with the new block. Note that in this case any following PADDING | ||
451 | * block is preserved as is. | ||
452 | * | ||
453 | * After writing the block, the iterator will remain in the same | ||
454 | * place, i.e. pointing to the new block. | ||
455 | * | ||
456 | * \param iterator A pointer to an existing initialized iterator. | ||
457 | * \param block The block to set. | ||
458 | * \param use_padding See above. | ||
459 | * \assert | ||
460 | * \code iterator != NULL \endcode | ||
461 | * \a iterator has been successfully initialized with | ||
462 | * FLAC__metadata_simple_iterator_init() | ||
463 | * \code block != NULL \endcode | ||
464 | * \retval FLAC__bool | ||
465 | * \c true if successful, else \c false. | ||
466 | */ | ||
467 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); | ||
468 | |||
469 | /** This is similar to FLAC__metadata_simple_iterator_set_block() | ||
470 | * except that instead of writing over an existing block, it appends | ||
471 | * a block after the existing block. \a use_padding is again used to | ||
472 | * tell the function to try an expand into following padding in an | ||
473 | * attempt to avoid rewriting the entire file. | ||
474 | * | ||
475 | * This function will fail and return \c false if given a STREAMINFO | ||
476 | * block. | ||
477 | * | ||
478 | * After writing the block, the iterator will be pointing to the | ||
479 | * new block. | ||
480 | * | ||
481 | * \param iterator A pointer to an existing initialized iterator. | ||
482 | * \param block The block to set. | ||
483 | * \param use_padding See above. | ||
484 | * \assert | ||
485 | * \code iterator != NULL \endcode | ||
486 | * \a iterator has been successfully initialized with | ||
487 | * FLAC__metadata_simple_iterator_init() | ||
488 | * \code block != NULL \endcode | ||
489 | * \retval FLAC__bool | ||
490 | * \c true if successful, else \c false. | ||
491 | */ | ||
492 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); | ||
493 | |||
494 | /** Deletes the block at the current position. This will cause the | ||
495 | * entire FLAC file to be rewritten, unless \a use_padding is \c true, | ||
496 | * in which case the block will be replaced by an equal-sized PADDING | ||
497 | * block. The iterator will be left pointing to the block before the | ||
498 | * one just deleted. | ||
499 | * | ||
500 | * You may not delete the STREAMINFO block. | ||
501 | * | ||
502 | * \param iterator A pointer to an existing initialized iterator. | ||
503 | * \param use_padding See above. | ||
504 | * \assert | ||
505 | * \code iterator != NULL \endcode | ||
506 | * \a iterator has been successfully initialized with | ||
507 | * FLAC__metadata_simple_iterator_init() | ||
508 | * \retval FLAC__bool | ||
509 | * \c true if successful, else \c false. | ||
510 | */ | ||
511 | FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding); | ||
512 | |||
513 | /* \} */ | ||
514 | |||
515 | |||
516 | /** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface | ||
517 | * \ingroup flac_metadata | ||
518 | * | ||
519 | * \brief | ||
520 | * The level 2 interface provides read-write access to FLAC file metadata; | ||
521 | * all metadata is read into memory, operated on in memory, and then written | ||
522 | * to file, which is more efficient than level 1 when editing multiple blocks. | ||
523 | * | ||
524 | * The general usage of this interface is: | ||
525 | * | ||
526 | * - Create a new chain using FLAC__metadata_chain_new(). A chain is a | ||
527 | * linked list of FLAC metadata blocks. | ||
528 | * - Read all metadata into the the chain from a FLAC file using | ||
529 | * FLAC__metadata_chain_read() and check the status. | ||
530 | * - Optionally, consolidate the padding using | ||
531 | * FLAC__metadata_chain_merge_padding() or | ||
532 | * FLAC__metadata_chain_sort_padding(). | ||
533 | * - Create a new iterator using FLAC__metadata_iterator_new() | ||
534 | * - Initialize the iterator to point to the first element in the chain | ||
535 | * using FLAC__metadata_iterator_init() | ||
536 | * - Traverse the chain using FLAC__metadata_iterator_next and | ||
537 | * FLAC__metadata_iterator_prev(). | ||
538 | * - Get a block for reading or modification using | ||
539 | * FLAC__metadata_iterator_get_block(). The pointer to the object | ||
540 | * inside the chain is returned, so the block is yours to modify. | ||
541 | * Changes will be reflected in the FLAC file when you write the | ||
542 | * chain. You can also add and delete blocks (see functions below). | ||
543 | * - When done, write out the chain using FLAC__metadata_chain_write(). | ||
544 | * Make sure to read the whole comment to the function below. | ||
545 | * - Delete the chain using FLAC__metadata_chain_delete(). | ||
546 | * | ||
547 | * \note | ||
548 | * Even though the FLAC file is not open while the chain is being | ||
549 | * manipulated, you must not alter the file externally during | ||
550 | * 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(). | ||
553 | * | ||
554 | * \note | ||
555 | * Do not modify the is_last, length, or type fields of returned | ||
556 | * FLAC__StreamMetadata objects. These are managed automatically. | ||
557 | * | ||
558 | * \note | ||
559 | * The metadata objects returned by FLAC__metadata_iterator_get_block() | ||
560 | * are owned by the chain; do not FLAC__metadata_object_delete() them. | ||
561 | * In the same way, blocks passed to FLAC__metadata_iterator_set_block() | ||
562 | * become owned by the chain and they will be deleted when the chain is | ||
563 | * deleted. | ||
564 | * | ||
565 | * \{ | ||
566 | */ | ||
567 | |||
568 | struct FLAC__Metadata_Chain; | ||
569 | /** The opaque structure definition for the level 2 chain type. | ||
570 | */ | ||
571 | typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain; | ||
572 | |||
573 | struct FLAC__Metadata_Iterator; | ||
574 | /** The opaque structure definition for the level 2 iterator type. | ||
575 | */ | ||
576 | typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator; | ||
577 | |||
578 | typedef enum { | ||
579 | FLAC__METADATA_CHAIN_STATUS_OK = 0, | ||
580 | /**< The chain is in the normal OK state */ | ||
581 | |||
582 | FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT, | ||
583 | /**< The data passed into a function violated the function's usage criteria */ | ||
584 | |||
585 | FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE, | ||
586 | /**< The chain could not open the target file */ | ||
587 | |||
588 | FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE, | ||
589 | /**< The chain could not find the FLAC signature at the start of the file */ | ||
590 | |||
591 | FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE, | ||
592 | /**< The chain tried to write to a file that was not writable */ | ||
593 | |||
594 | FLAC__METADATA_CHAIN_STATUS_BAD_METADATA, | ||
595 | /**< The chain encountered input that does not conform to the FLAC metadata specification */ | ||
596 | |||
597 | FLAC__METADATA_CHAIN_STATUS_READ_ERROR, | ||
598 | /**< The chain encountered an error while reading the FLAC file */ | ||
599 | |||
600 | FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR, | ||
601 | /**< The chain encountered an error while seeking in the FLAC file */ | ||
602 | |||
603 | FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR, | ||
604 | /**< The chain encountered an error while writing the FLAC file */ | ||
605 | |||
606 | FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR, | ||
607 | /**< The chain encountered an error renaming the FLAC file */ | ||
608 | |||
609 | FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR, | ||
610 | /**< The chain encountered an error removing the temporary file */ | ||
611 | |||
612 | FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR, | ||
613 | /**< Memory allocation failed */ | ||
614 | |||
615 | FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR, | ||
616 | /**< The caller violated an assertion or an unexpected error occurred */ | ||
617 | |||
618 | FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS, | ||
619 | /**< One or more of the required callbacks was NULL */ | ||
620 | |||
621 | FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH, | ||
622 | /**< 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. */ | ||
628 | |||
629 | FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL | ||
630 | /**< FLAC__metadata_chain_write_with_callbacks() was called when the | ||
631 | * chain write requires a tempfile; use | ||
632 | * FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead. | ||
633 | * Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was | ||
634 | * called when the chain write does not require a tempfile; use | ||
635 | * FLAC__metadata_chain_write_with_callbacks() instead. | ||
636 | * Always check FLAC__metadata_chain_check_if_tempfile_needed() | ||
637 | * before writing via callbacks. */ | ||
638 | |||
639 | } FLAC__Metadata_ChainStatus; | ||
640 | |||
641 | /** Maps a FLAC__Metadata_ChainStatus to a C string. | ||
642 | * | ||
643 | * Using a FLAC__Metadata_ChainStatus as the index to this array | ||
644 | * will give the string equivalent. The contents should not be modified. | ||
645 | */ | ||
646 | extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[]; | ||
647 | |||
648 | /*********** FLAC__Metadata_Chain ***********/ | ||
649 | |||
650 | /** Create a new chain instance. | ||
651 | * | ||
652 | * \retval FLAC__Metadata_Chain* | ||
653 | * \c NULL if there was an error allocating memory, else the new instance. | ||
654 | */ | ||
655 | FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(); | ||
656 | |||
657 | /** Free a chain instance. Deletes the object pointed to by \a chain. | ||
658 | * | ||
659 | * \param chain A pointer to an existing chain. | ||
660 | * \assert | ||
661 | * \code chain != NULL \endcode | ||
662 | */ | ||
663 | FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain); | ||
664 | |||
665 | /** Get the current status of the chain. Call this after a function | ||
666 | * returns \c false to get the reason for the error. Also resets the | ||
667 | * status to FLAC__METADATA_CHAIN_STATUS_OK. | ||
668 | * | ||
669 | * \param chain A pointer to an existing chain. | ||
670 | * \assert | ||
671 | * \code chain != NULL \endcode | ||
672 | * \retval FLAC__Metadata_ChainStatus | ||
673 | * The current status of the chain. | ||
674 | */ | ||
675 | FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain); | ||
676 | |||
677 | /** Read all metadata from a FLAC file into the chain. | ||
678 | * | ||
679 | * \param chain A pointer to an existing chain. | ||
680 | * \param filename The path to the FLAC file to read. | ||
681 | * \assert | ||
682 | * \code chain != NULL \endcode | ||
683 | * \code filename != NULL \endcode | ||
684 | * \retval FLAC__bool | ||
685 | * \c true if a valid list of metadata blocks was read from | ||
686 | * \a filename, else \c false. On failure, check the status with | ||
687 | * FLAC__metadata_chain_status(). | ||
688 | */ | ||
689 | FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename); | ||
690 | |||
691 | /** Read all metadata from a FLAC stream into the chain via I/O callbacks. | ||
692 | * | ||
693 | * The \a handle need only be open for reading, but must be seekable. | ||
694 | * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" | ||
695 | * for Windows). | ||
696 | * | ||
697 | * \param chain A pointer to an existing chain. | ||
698 | * \param handle The I/O handle of the FLAC stream to read. The | ||
699 | * handle will NOT be closed after the metadata is read; | ||
700 | * that is the duty of the caller. | ||
701 | * \param callbacks | ||
702 | * A set of callbacks to use for I/O. The mandatory | ||
703 | * callbacks are \a read, \a seek, and \a tell. | ||
704 | * \assert | ||
705 | * \code chain != NULL \endcode | ||
706 | * \retval FLAC__bool | ||
707 | * \c true if a valid list of metadata blocks was read from | ||
708 | * \a handle, else \c false. On failure, check the status with | ||
709 | * FLAC__metadata_chain_status(). | ||
710 | */ | ||
711 | FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); | ||
712 | |||
713 | /** Checks if writing the given chain would require the use of a | ||
714 | * temporary file, or if it could be written in place. | ||
715 | * | ||
716 | * Under certain conditions, padding can be utilized so that writing | ||
717 | * edited metadata back to the FLAC file does not require rewriting the | ||
718 | * entire file. If rewriting is required, then a temporary workfile is | ||
719 | * required. When writing metadata using callbacks, you must check | ||
720 | * this function to know whether to call | ||
721 | * FLAC__metadata_chain_write_with_callbacks() or | ||
722 | * FLAC__metadata_chain_write_with_callbacks_and_tempfile(). When | ||
723 | * writing with FLAC__metadata_chain_write(), the temporary file is | ||
724 | * handled internally. | ||
725 | * | ||
726 | * \param chain A pointer to an existing chain. | ||
727 | * \param use_padding | ||
728 | * Whether or not padding will be allowed to be used | ||
729 | * during the write. The value of \a use_padding given | ||
730 | * here must match the value later passed to | ||
731 | * FLAC__metadata_chain_write_with_callbacks() or | ||
732 | * FLAC__metadata_chain_write_with_callbacks_with_tempfile(). | ||
733 | * \assert | ||
734 | * \code chain != NULL \endcode | ||
735 | * \retval FLAC__bool | ||
736 | * \c true if writing the current chain would require a tempfile, or | ||
737 | * \c false if metadata can be written in place. | ||
738 | */ | ||
739 | FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding); | ||
740 | |||
741 | /** Write all metadata out to the FLAC file. This function tries to be as | ||
742 | * efficient as possible; how the metadata is actually written is shown by | ||
743 | * the following: | ||
744 | * | ||
745 | * If the current chain is the same size as the existing metadata, the new | ||
746 | * data is written in place. | ||
747 | * | ||
748 | * If the current chain is longer than the existing metadata, and | ||
749 | * \a use_padding is \c true, and the last block is a PADDING block of | ||
750 | * sufficient length, the function will truncate the final padding block | ||
751 | * so that the overall size of the metadata is the same as the existing | ||
752 | * metadata, and then just rewrite the metadata. Otherwise, if not all of | ||
753 | * the above conditions are met, the entire FLAC file must be rewritten. | ||
754 | * If you want to use padding this way it is a good idea to call | ||
755 | * FLAC__metadata_chain_sort_padding() first so that you have the maximum | ||
756 | * amount of padding to work with, unless you need to preserve ordering | ||
757 | * of the PADDING blocks for some reason. | ||
758 | * | ||
759 | * If the current chain is shorter than the existing metadata, and | ||
760 | * \a use_padding is \c true, and the final block is a PADDING block, the padding | ||
761 | * is extended to make the overall size the same as the existing data. If | ||
762 | * \a use_padding is \c true and the last block is not a PADDING block, a new | ||
763 | * PADDING block is added to the end of the new data to make it the same | ||
764 | * size as the existing data (if possible, see the note to | ||
765 | * FLAC__metadata_simple_iterator_set_block() about the four byte limit) | ||
766 | * and the new data is written in place. If none of the above apply or | ||
767 | * \a use_padding is \c false, the entire FLAC file is rewritten. | ||
768 | * | ||
769 | * If \a preserve_file_stats is \c true, the owner and modification time will | ||
770 | * be preserved even if the FLAC file is written. | ||
771 | * | ||
772 | * 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(). | ||
774 | * | ||
775 | * \param chain A pointer to an existing chain. | ||
776 | * \param use_padding See above. | ||
777 | * \param preserve_file_stats See above. | ||
778 | * \assert | ||
779 | * \code chain != NULL \endcode | ||
780 | * \retval FLAC__bool | ||
781 | * \c true if the write succeeded, else \c false. On failure, | ||
782 | * check the status with FLAC__metadata_chain_status(). | ||
783 | */ | ||
784 | FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats); | ||
785 | |||
786 | /** Write all metadata out to a FLAC stream via callbacks. | ||
787 | * | ||
788 | * (See FLAC__metadata_chain_write() for the details on how padding is | ||
789 | * used to write metadata in place if possible.) | ||
790 | * | ||
791 | * The \a handle must be open for updating and be seekable. The | ||
792 | * equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b" | ||
793 | * for Windows). | ||
794 | * | ||
795 | * 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(). | ||
797 | * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned | ||
798 | * \c false. | ||
799 | * | ||
800 | * \param chain A pointer to an existing chain. | ||
801 | * \param use_padding See FLAC__metadata_chain_write() | ||
802 | * \param handle The I/O handle of the FLAC stream to write. The | ||
803 | * handle will NOT be closed after the metadata is | ||
804 | * written; that is the duty of the caller. | ||
805 | * \param callbacks A set of callbacks to use for I/O. The mandatory | ||
806 | * callbacks are \a write and \a seek. | ||
807 | * \assert | ||
808 | * \code chain != NULL \endcode | ||
809 | * \retval FLAC__bool | ||
810 | * \c true if the write succeeded, else \c false. On failure, | ||
811 | * check the status with FLAC__metadata_chain_status(). | ||
812 | */ | ||
813 | FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); | ||
814 | |||
815 | /** Write all metadata out to a FLAC stream via callbacks. | ||
816 | * | ||
817 | * (See FLAC__metadata_chain_write() for the details on how padding is | ||
818 | * used to write metadata in place if possible.) | ||
819 | * | ||
820 | * This version of the write-with-callbacks function must be used when | ||
821 | * FLAC__metadata_chain_check_if_tempfile_needed() returns true. In | ||
822 | * this function, you must supply an I/O handle corresponding to the | ||
823 | * FLAC file to edit, and a temporary handle to which the new FLAC | ||
824 | * file will be written. It is the caller's job to move this temporary | ||
825 | * FLAC file on top of the original FLAC file to complete the metadata | ||
826 | * edit. | ||
827 | * | ||
828 | * The \a handle must be open for reading and be seekable. The | ||
829 | * equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" | ||
830 | * for Windows). | ||
831 | * | ||
832 | * The \a temp_handle must be open for writing. The | ||
833 | * equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb" | ||
834 | * for Windows). It should be an empty stream, or at least positioned | ||
835 | * at the start-of-file (in which case it is the caller's duty to | ||
836 | * truncate it on return). | ||
837 | * | ||
838 | * 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(). | ||
840 | * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned | ||
841 | * \c true. | ||
842 | * | ||
843 | * \param chain A pointer to an existing chain. | ||
844 | * \param use_padding See FLAC__metadata_chain_write() | ||
845 | * \param handle The I/O handle of the original FLAC stream to read. | ||
846 | * The handle will NOT be closed after the metadata is | ||
847 | * written; that is the duty of the caller. | ||
848 | * \param callbacks A set of callbacks to use for I/O on \a handle. | ||
849 | * The mandatory callbacks are \a read, \a seek, and | ||
850 | * \a eof. | ||
851 | * \param temp_handle The I/O handle of the FLAC stream to write. The | ||
852 | * handle will NOT be closed after the metadata is | ||
853 | * written; that is the duty of the caller. | ||
854 | * \param temp_callbacks | ||
855 | * A set of callbacks to use for I/O on temp_handle. | ||
856 | * The only mandatory callback is \a write. | ||
857 | * \assert | ||
858 | * \code chain != NULL \endcode | ||
859 | * \retval FLAC__bool | ||
860 | * \c true if the write succeeded, else \c false. On failure, | ||
861 | * check the status with FLAC__metadata_chain_status(). | ||
862 | */ | ||
863 | FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks); | ||
864 | |||
865 | /** Merge adjacent PADDING blocks into a single block. | ||
866 | * | ||
867 | * \note This function does not write to the FLAC file, it only | ||
868 | * modifies the chain. | ||
869 | * | ||
870 | * \warning Any iterator on the current chain will become invalid after this | ||
871 | * call. You should delete the iterator and get a new one. | ||
872 | * | ||
873 | * \param chain A pointer to an existing chain. | ||
874 | * \assert | ||
875 | * \code chain != NULL \endcode | ||
876 | */ | ||
877 | FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain); | ||
878 | |||
879 | /** This function will move all PADDING blocks to the end on the metadata, | ||
880 | * then merge them into a single block. | ||
881 | * | ||
882 | * \note This function does not write to the FLAC file, it only | ||
883 | * modifies the chain. | ||
884 | * | ||
885 | * \warning Any iterator on the current chain will become invalid after this | ||
886 | * call. You should delete the iterator and get a new one. | ||
887 | * | ||
888 | * \param chain A pointer to an existing chain. | ||
889 | * \assert | ||
890 | * \code chain != NULL \endcode | ||
891 | */ | ||
892 | FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain); | ||
893 | |||
894 | |||
895 | /*********** FLAC__Metadata_Iterator ***********/ | ||
896 | |||
897 | /** Create a new iterator instance. | ||
898 | * | ||
899 | * \retval FLAC__Metadata_Iterator* | ||
900 | * \c NULL if there was an error allocating memory, else the new instance. | ||
901 | */ | ||
902 | FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(); | ||
903 | |||
904 | /** Free an iterator instance. Deletes the object pointed to by \a iterator. | ||
905 | * | ||
906 | * \param iterator A pointer to an existing iterator. | ||
907 | * \assert | ||
908 | * \code iterator != NULL \endcode | ||
909 | */ | ||
910 | FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator); | ||
911 | |||
912 | /** Initialize the iterator to point to the first metadata block in the | ||
913 | * given chain. | ||
914 | * | ||
915 | * \param iterator A pointer to an existing iterator. | ||
916 | * \param chain A pointer to an existing and initialized (read) chain. | ||
917 | * \assert | ||
918 | * \code iterator != NULL \endcode | ||
919 | * \code chain != NULL \endcode | ||
920 | */ | ||
921 | FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain); | ||
922 | |||
923 | /** Moves the iterator forward one metadata block, returning \c false if | ||
924 | * already at the end. | ||
925 | * | ||
926 | * \param iterator A pointer to an existing initialized iterator. | ||
927 | * \assert | ||
928 | * \code iterator != NULL \endcode | ||
929 | * \a iterator has been successfully initialized with | ||
930 | * FLAC__metadata_iterator_init() | ||
931 | * \retval FLAC__bool | ||
932 | * \c false if already at the last metadata block of the chain, else | ||
933 | * \c true. | ||
934 | */ | ||
935 | FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator); | ||
936 | |||
937 | /** Moves the iterator backward one metadata block, returning \c false if | ||
938 | * already at the beginning. | ||
939 | * | ||
940 | * \param iterator A pointer to an existing initialized iterator. | ||
941 | * \assert | ||
942 | * \code iterator != NULL \endcode | ||
943 | * \a iterator has been successfully initialized with | ||
944 | * FLAC__metadata_iterator_init() | ||
945 | * \retval FLAC__bool | ||
946 | * \c false if already at the first metadata block of the chain, else | ||
947 | * \c true. | ||
948 | */ | ||
949 | FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator); | ||
950 | |||
951 | /** Get the type of the metadata block at the current position. | ||
952 | * | ||
953 | * \param iterator A pointer to an existing initialized iterator. | ||
954 | * \assert | ||
955 | * \code iterator != NULL \endcode | ||
956 | * \a iterator has been successfully initialized with | ||
957 | * FLAC__metadata_iterator_init() | ||
958 | * \retval FLAC__MetadataType | ||
959 | * The type of the metadata block at the current iterator position. | ||
960 | */ | ||
961 | FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator); | ||
962 | |||
963 | /** Get the metadata block at the current position. You can modify | ||
964 | * the block in place but must write the chain before the changes | ||
965 | * are reflected to the FLAC file. You do not need to call | ||
966 | * FLAC__metadata_iterator_set_block() to reflect the changes; | ||
967 | * the pointer returned by FLAC__metadata_iterator_get_block() | ||
968 | * points directly into the chain. | ||
969 | * | ||
970 | * \warning | ||
971 | * Do not call FLAC__metadata_object_delete() on the returned object; | ||
972 | * to delete a block use FLAC__metadata_iterator_delete_block(). | ||
973 | * | ||
974 | * \param iterator A pointer to an existing initialized iterator. | ||
975 | * \assert | ||
976 | * \code iterator != NULL \endcode | ||
977 | * \a iterator has been successfully initialized with | ||
978 | * FLAC__metadata_iterator_init() | ||
979 | * \retval FLAC__StreamMetadata* | ||
980 | * The current metadata block. | ||
981 | */ | ||
982 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator); | ||
983 | |||
984 | /** Set the metadata block at the current position, replacing the existing | ||
985 | * block. The new block passed in becomes owned by the chain and it will be | ||
986 | * deleted when the chain is deleted. | ||
987 | * | ||
988 | * \param iterator A pointer to an existing initialized iterator. | ||
989 | * \param block A pointer to a metadata block. | ||
990 | * \assert | ||
991 | * \code iterator != NULL \endcode | ||
992 | * \a iterator has been successfully initialized with | ||
993 | * FLAC__metadata_iterator_init() | ||
994 | * \code block != NULL \endcode | ||
995 | * \retval FLAC__bool | ||
996 | * \c false if the conditions in the above description are not met, or | ||
997 | * a memory allocation error occurs, otherwise \c true. | ||
998 | */ | ||
999 | FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); | ||
1000 | |||
1001 | /** Removes the current block from the chain. If \a replace_with_padding is | ||
1002 | * \c true, the block will instead be replaced with a padding block of equal | ||
1003 | * size. You can not delete the STREAMINFO block. The iterator will be | ||
1004 | * left pointing to the block before the one just "deleted", even if | ||
1005 | * \a replace_with_padding is \c true. | ||
1006 | * | ||
1007 | * \param iterator A pointer to an existing initialized iterator. | ||
1008 | * \param replace_with_padding See above. | ||
1009 | * \assert | ||
1010 | * \code iterator != NULL \endcode | ||
1011 | * \a iterator has been successfully initialized with | ||
1012 | * FLAC__metadata_iterator_init() | ||
1013 | * \retval FLAC__bool | ||
1014 | * \c false if the conditions in the above description are not met, | ||
1015 | * otherwise \c true. | ||
1016 | */ | ||
1017 | FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding); | ||
1018 | |||
1019 | /** Insert a new block before the current block. You cannot insert a block | ||
1020 | * before the first STREAMINFO block. You cannot insert a STREAMINFO block | ||
1021 | * as there can be only one, the one that already exists at the head when you | ||
1022 | * read in a chain. The chain takes ownership of the new block and it will be | ||
1023 | * deleted when the chain is deleted. The iterator will be left pointing to | ||
1024 | * the new block. | ||
1025 | * | ||
1026 | * \param iterator A pointer to an existing initialized iterator. | ||
1027 | * \param block A pointer to a metadata block to insert. | ||
1028 | * \assert | ||
1029 | * \code iterator != NULL \endcode | ||
1030 | * \a iterator has been successfully initialized with | ||
1031 | * FLAC__metadata_iterator_init() | ||
1032 | * \retval FLAC__bool | ||
1033 | * \c false if the conditions in the above description are not met, or | ||
1034 | * a memory allocation error occurs, otherwise \c true. | ||
1035 | */ | ||
1036 | FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); | ||
1037 | |||
1038 | /** Insert a new block after the current block. You cannot insert a STREAMINFO | ||
1039 | * block as there can be only one, the one that already exists at the head when | ||
1040 | * you read in a chain. The chain takes ownership of the new block and it will | ||
1041 | * be deleted when the chain is deleted. The iterator will be left pointing to | ||
1042 | * the new block. | ||
1043 | * | ||
1044 | * \param iterator A pointer to an existing initialized iterator. | ||
1045 | * \param block A pointer to a metadata block to insert. | ||
1046 | * \assert | ||
1047 | * \code iterator != NULL \endcode | ||
1048 | * \a iterator has been successfully initialized with | ||
1049 | * FLAC__metadata_iterator_init() | ||
1050 | * \retval FLAC__bool | ||
1051 | * \c false if the conditions in the above description are not met, or | ||
1052 | * a memory allocation error occurs, otherwise \c true. | ||
1053 | */ | ||
1054 | FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); | ||
1055 | |||
1056 | /* \} */ | ||
1057 | |||
1058 | |||
1059 | /** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods | ||
1060 | * \ingroup flac_metadata | ||
1061 | * | ||
1062 | * \brief | ||
1063 | * This module contains methods for manipulating FLAC metadata objects. | ||
1064 | * | ||
1065 | * Since many are variable length we have to be careful about the memory | ||
1066 | * management. We decree that all pointers to data in the object are | ||
1067 | * owned by the object and memory-managed by the object. | ||
1068 | * | ||
1069 | * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete() | ||
1070 | * functions to create all instances. When using the | ||
1071 | * FLAC__metadata_object_set_*() functions to set pointers to data, set | ||
1072 | * \a copy to \c true to have the function make it's own copy of the data, or | ||
1073 | * to \c false to give the object ownership of your data. In the latter case | ||
1074 | * your pointer must be freeable by free() and will be free()d when the object | ||
1075 | * is FLAC__metadata_object_delete()d. It is legal to pass a null pointer as | ||
1076 | * the data pointer to a FLAC__metadata_object_set_*() function as long as | ||
1077 | * the length argument is 0 and the \a copy argument is \c false. | ||
1078 | * | ||
1079 | * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function | ||
1080 | * will return \c NULL in the case of a memory allocation error, otherwise a new | ||
1081 | * object. The FLAC__metadata_object_set_*() functions return \c false in the | ||
1082 | * case of a memory allocation error. | ||
1083 | * | ||
1084 | * We don't have the convenience of C++ here, so note that the library relies | ||
1085 | * on you to keep the types straight. In other words, if you pass, for | ||
1086 | * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to | ||
1087 | * FLAC__metadata_object_application_set_data(), you will get an assertion | ||
1088 | * failure. | ||
1089 | * | ||
1090 | * For convenience the FLAC__metadata_object_vorbiscomment_*() functions | ||
1091 | * maintain a trailing NUL on each Vorbis comment entry. This is not counted | ||
1092 | * toward the length or stored in the stream, but it can make working with plain | ||
1093 | * comments (those that don't contain embedded-NULs in the value) easier. | ||
1094 | * Entries passed into these functions have trailing NULs added if missing, and | ||
1095 | * returned entries are guaranteed to have a trailing NUL. | ||
1096 | * | ||
1097 | * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis | ||
1098 | * comment entry/name/value will first validate that it complies with the Vorbis | ||
1099 | * comment specification and return false if it does not. | ||
1100 | * | ||
1101 | * There is no need to recalculate the length field on metadata blocks you | ||
1102 | * have modified. They will be calculated automatically before they are | ||
1103 | * written back to a file. | ||
1104 | * | ||
1105 | * \{ | ||
1106 | */ | ||
1107 | |||
1108 | |||
1109 | /** Create a new metadata object instance of the given type. | ||
1110 | * | ||
1111 | * The object will be "empty"; i.e. values and data pointers will be \c 0, | ||
1112 | * with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have | ||
1113 | * the vendor string set (but zero comments). | ||
1114 | * | ||
1115 | * Do not pass in a value greater than or equal to | ||
1116 | * \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're | ||
1117 | * doing. | ||
1118 | * | ||
1119 | * \param type Type of object to create | ||
1120 | * \retval FLAC__StreamMetadata* | ||
1121 | * \c NULL if there was an error allocating memory or the type code is | ||
1122 | * greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance. | ||
1123 | */ | ||
1124 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type); | ||
1125 | |||
1126 | /** Create a copy of an existing metadata object. | ||
1127 | * | ||
1128 | * The copy is a "deep" copy, i.e. dynamically allocated data within the | ||
1129 | * object is also copied. The caller takes ownership of the new block and | ||
1130 | * is responsible for freeing it with FLAC__metadata_object_delete(). | ||
1131 | * | ||
1132 | * \param object Pointer to object to copy. | ||
1133 | * \assert | ||
1134 | * \code object != NULL \endcode | ||
1135 | * \retval FLAC__StreamMetadata* | ||
1136 | * \c NULL if there was an error allocating memory, else the new instance. | ||
1137 | */ | ||
1138 | FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object); | ||
1139 | |||
1140 | /** Free a metadata object. Deletes the object pointed to by \a object. | ||
1141 | * | ||
1142 | * The delete is a "deep" delete, i.e. dynamically allocated data within the | ||
1143 | * object is also deleted. | ||
1144 | * | ||
1145 | * \param object A pointer to an existing object. | ||
1146 | * \assert | ||
1147 | * \code object != NULL \endcode | ||
1148 | */ | ||
1149 | FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object); | ||
1150 | |||
1151 | /** Compares two metadata objects. | ||
1152 | * | ||
1153 | * The compare is "deep", i.e. dynamically allocated data within the | ||
1154 | * object is also compared. | ||
1155 | * | ||
1156 | * \param block1 A pointer to an existing object. | ||
1157 | * \param block2 A pointer to an existing object. | ||
1158 | * \assert | ||
1159 | * \code block1 != NULL \endcode | ||
1160 | * \code block2 != NULL \endcode | ||
1161 | * \retval FLAC__bool | ||
1162 | * \c true if objects are identical, else \c false. | ||
1163 | */ | ||
1164 | FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2); | ||
1165 | |||
1166 | /** Sets the application data of an APPLICATION block. | ||
1167 | * | ||
1168 | * If \a copy is \c true, a copy of the data is stored; otherwise, the object | ||
1169 | * takes ownership of the pointer. | ||
1170 | * | ||
1171 | * \param object A pointer to an existing APPLICATION object. | ||
1172 | * \param data A pointer to the data to set. | ||
1173 | * \param length The length of \a data in bytes. | ||
1174 | * \param copy See above. | ||
1175 | * \assert | ||
1176 | * \code object != NULL \endcode | ||
1177 | * \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode | ||
1178 | * \code (data != NULL && length > 0) || | ||
1179 | * (data == NULL && length == 0 && copy == false) \endcode | ||
1180 | * \retval FLAC__bool | ||
1181 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1182 | */ | ||
1183 | FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy); | ||
1184 | |||
1185 | /** Resize the seekpoint array. | ||
1186 | * | ||
1187 | * If the size shrinks, elements will truncated; if it grows, new placeholder | ||
1188 | * points will be added to the end. | ||
1189 | * | ||
1190 | * \param object A pointer to an existing SEEKTABLE object. | ||
1191 | * \param new_num_points The desired length of the array; may be \c 0. | ||
1192 | * \assert | ||
1193 | * \code object != NULL \endcode | ||
1194 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1195 | * \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) || | ||
1196 | * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode | ||
1197 | * \retval FLAC__bool | ||
1198 | * \c false if memory allocation error, else \c true. | ||
1199 | */ | ||
1200 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points); | ||
1201 | |||
1202 | /** Set a seekpoint in a seektable. | ||
1203 | * | ||
1204 | * \param object A pointer to an existing SEEKTABLE object. | ||
1205 | * \param point_num Index into seekpoint array to set. | ||
1206 | * \param point The point to set. | ||
1207 | * \assert | ||
1208 | * \code object != NULL \endcode | ||
1209 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1210 | * \code object->data.seek_table.num_points > point_num \endcode | ||
1211 | */ | ||
1212 | FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); | ||
1213 | |||
1214 | /** Insert a seekpoint into a seektable. | ||
1215 | * | ||
1216 | * \param object A pointer to an existing SEEKTABLE object. | ||
1217 | * \param point_num Index into seekpoint array to set. | ||
1218 | * \param point The point to set. | ||
1219 | * \assert | ||
1220 | * \code object != NULL \endcode | ||
1221 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1222 | * \code object->data.seek_table.num_points >= point_num \endcode | ||
1223 | * \retval FLAC__bool | ||
1224 | * \c false if memory allocation error, else \c true. | ||
1225 | */ | ||
1226 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); | ||
1227 | |||
1228 | /** Delete a seekpoint from a seektable. | ||
1229 | * | ||
1230 | * \param object A pointer to an existing SEEKTABLE object. | ||
1231 | * \param point_num Index into seekpoint array to set. | ||
1232 | * \assert | ||
1233 | * \code object != NULL \endcode | ||
1234 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1235 | * \code object->data.seek_table.num_points > point_num \endcode | ||
1236 | * \retval FLAC__bool | ||
1237 | * \c false if memory allocation error, else \c true. | ||
1238 | */ | ||
1239 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num); | ||
1240 | |||
1241 | /** Check a seektable to see if it conforms to the FLAC specification. | ||
1242 | * See the format specification for limits on the contents of the | ||
1243 | * seektable. | ||
1244 | * | ||
1245 | * \param object A pointer to an existing SEEKTABLE object. | ||
1246 | * \assert | ||
1247 | * \code object != NULL \endcode | ||
1248 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1249 | * \retval FLAC__bool | ||
1250 | * \c false if seek table is illegal, else \c true. | ||
1251 | */ | ||
1252 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object); | ||
1253 | |||
1254 | /** Append a number of placeholder points to the end of a seek table. | ||
1255 | * | ||
1256 | * \note | ||
1257 | * As with the other ..._seektable_template_... functions, you should | ||
1258 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1259 | * to make the seek table legal. | ||
1260 | * | ||
1261 | * \param object A pointer to an existing SEEKTABLE object. | ||
1262 | * \param num The number of placeholder points to append. | ||
1263 | * \assert | ||
1264 | * \code object != NULL \endcode | ||
1265 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1266 | * \retval FLAC__bool | ||
1267 | * \c false if memory allocation fails, else \c true. | ||
1268 | */ | ||
1269 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num); | ||
1270 | |||
1271 | /** Append a specific seek point template to the end of a seek table. | ||
1272 | * | ||
1273 | * \note | ||
1274 | * As with the other ..._seektable_template_... functions, you should | ||
1275 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1276 | * to make the seek table legal. | ||
1277 | * | ||
1278 | * \param object A pointer to an existing SEEKTABLE object. | ||
1279 | * \param sample_number The sample number of the seek point template. | ||
1280 | * \assert | ||
1281 | * \code object != NULL \endcode | ||
1282 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1283 | * \retval FLAC__bool | ||
1284 | * \c false if memory allocation fails, else \c true. | ||
1285 | */ | ||
1286 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number); | ||
1287 | |||
1288 | /** Append specific seek point templates to the end of a seek table. | ||
1289 | * | ||
1290 | * \note | ||
1291 | * As with the other ..._seektable_template_... functions, you should | ||
1292 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1293 | * to make the seek table legal. | ||
1294 | * | ||
1295 | * \param object A pointer to an existing SEEKTABLE object. | ||
1296 | * \param sample_numbers An array of sample numbers for the seek points. | ||
1297 | * \param num The number of seek point templates to append. | ||
1298 | * \assert | ||
1299 | * \code object != NULL \endcode | ||
1300 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1301 | * \retval FLAC__bool | ||
1302 | * \c false if memory allocation fails, else \c true. | ||
1303 | */ | ||
1304 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num); | ||
1305 | |||
1306 | /** Append a set of evenly-spaced seek point templates to the end of a | ||
1307 | * seek table. | ||
1308 | * | ||
1309 | * \note | ||
1310 | * As with the other ..._seektable_template_... functions, you should | ||
1311 | * call FLAC__metadata_object_seektable_template_sort() when finished | ||
1312 | * to make the seek table legal. | ||
1313 | * | ||
1314 | * \param object A pointer to an existing SEEKTABLE object. | ||
1315 | * \param num The number of placeholder points to append. | ||
1316 | * \param total_samples The total number of samples to be encoded; | ||
1317 | * the seekpoints will be spaced approximately | ||
1318 | * \a total_samples / \a num samples apart. | ||
1319 | * \assert | ||
1320 | * \code object != NULL \endcode | ||
1321 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1322 | * \retval FLAC__bool | ||
1323 | * \c false if memory allocation fails, else \c true. | ||
1324 | */ | ||
1325 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples); | ||
1326 | |||
1327 | /** Sort a seek table's seek points according to the format specification, | ||
1328 | * removing duplicates. | ||
1329 | * | ||
1330 | * \param object A pointer to a seek table to be sorted. | ||
1331 | * \param compact If \c false, behaves like FLAC__format_seektable_sort(). | ||
1332 | * If \c true, duplicates are deleted and the seek table is | ||
1333 | * shrunk appropriately; the number of placeholder points | ||
1334 | * present in the seek table will be the same after the call | ||
1335 | * as before. | ||
1336 | * \assert | ||
1337 | * \code object != NULL \endcode | ||
1338 | * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode | ||
1339 | * \retval FLAC__bool | ||
1340 | * \c false if realloc() fails, else \c true. | ||
1341 | */ | ||
1342 | FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact); | ||
1343 | |||
1344 | /** Sets the vendor string in a VORBIS_COMMENT block. | ||
1345 | * | ||
1346 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1347 | * one already. | ||
1348 | * | ||
1349 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1350 | * takes ownership of the \c entry.entry pointer. | ||
1351 | * | ||
1352 | * \note If this function returns \c false, the caller still owns the | ||
1353 | * pointer. | ||
1354 | * | ||
1355 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1356 | * \param entry The entry to set the vendor string to. | ||
1357 | * \param copy See above. | ||
1358 | * \assert | ||
1359 | * \code object != NULL \endcode | ||
1360 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1361 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1362 | * (entry.entry == NULL && entry.length == 0) \endcode | ||
1363 | * \retval FLAC__bool | ||
1364 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1365 | * Vorbis comment specification, else \c true. | ||
1366 | */ | ||
1367 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1368 | |||
1369 | /** Resize the comment array. | ||
1370 | * | ||
1371 | * If the size shrinks, elements will truncated; if it grows, new empty | ||
1372 | * fields will be added to the end. | ||
1373 | * | ||
1374 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1375 | * \param new_num_comments The desired length of the array; may be \c 0. | ||
1376 | * \assert | ||
1377 | * \code object != NULL \endcode | ||
1378 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1379 | * \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) || | ||
1380 | * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode | ||
1381 | * \retval FLAC__bool | ||
1382 | * \c false if memory allocation fails, else \c true. | ||
1383 | */ | ||
1384 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments); | ||
1385 | |||
1386 | /** Sets a comment in a VORBIS_COMMENT block. | ||
1387 | * | ||
1388 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1389 | * one already. | ||
1390 | * | ||
1391 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1392 | * takes ownership of the \c entry.entry pointer. | ||
1393 | * | ||
1394 | * \note If this function returns \c false, the caller still owns the | ||
1395 | * pointer. | ||
1396 | * | ||
1397 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1398 | * \param comment_num Index into comment array to set. | ||
1399 | * \param entry The entry to set the comment to. | ||
1400 | * \param copy See above. | ||
1401 | * \assert | ||
1402 | * \code object != NULL \endcode | ||
1403 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1404 | * \code comment_num < object->data.vorbis_comment.num_comments \endcode | ||
1405 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1406 | * (entry.entry == NULL && entry.length == 0) \endcode | ||
1407 | * \retval FLAC__bool | ||
1408 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1409 | * Vorbis comment specification, else \c true. | ||
1410 | */ | ||
1411 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1412 | |||
1413 | /** Insert a comment in a VORBIS_COMMENT block at the given index. | ||
1414 | * | ||
1415 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1416 | * one already. | ||
1417 | * | ||
1418 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1419 | * takes ownership of the \c entry.entry pointer. | ||
1420 | * | ||
1421 | * \note If this function returns \c false, the caller still owns the | ||
1422 | * pointer. | ||
1423 | * | ||
1424 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1425 | * \param comment_num The index at which to insert the comment. The comments | ||
1426 | * at and after \a comment_num move right one position. | ||
1427 | * To append a comment to the end, set \a comment_num to | ||
1428 | * \c object->data.vorbis_comment.num_comments . | ||
1429 | * \param entry The comment to insert. | ||
1430 | * \param copy See above. | ||
1431 | * \assert | ||
1432 | * \code object != NULL \endcode | ||
1433 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1434 | * \code object->data.vorbis_comment.num_comments >= comment_num \endcode | ||
1435 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1436 | * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode | ||
1437 | * \retval FLAC__bool | ||
1438 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1439 | * Vorbis comment specification, else \c true. | ||
1440 | */ | ||
1441 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1442 | |||
1443 | /** Appends a comment to a VORBIS_COMMENT block. | ||
1444 | * | ||
1445 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1446 | * one already. | ||
1447 | * | ||
1448 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1449 | * takes ownership of the \c entry.entry pointer. | ||
1450 | * | ||
1451 | * \note If this function returns \c false, the caller still owns the | ||
1452 | * pointer. | ||
1453 | * | ||
1454 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1455 | * \param entry The comment to insert. | ||
1456 | * \param copy See above. | ||
1457 | * \assert | ||
1458 | * \code object != NULL \endcode | ||
1459 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1460 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1461 | * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode | ||
1462 | * \retval FLAC__bool | ||
1463 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1464 | * Vorbis comment specification, else \c true. | ||
1465 | */ | ||
1466 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); | ||
1467 | |||
1468 | /** Replaces comments in a VORBIS_COMMENT block with a new one. | ||
1469 | * | ||
1470 | * For convenience, a trailing NUL is added to the entry if it doesn't have | ||
1471 | * one already. | ||
1472 | * | ||
1473 | * Depending on the the value of \a all, either all or just the first comment | ||
1474 | * whose field name(s) match the given entry's name will be replaced by the | ||
1475 | * given entry. If no comments match, \a entry will simply be appended. | ||
1476 | * | ||
1477 | * If \a copy is \c true, a copy of the entry is stored; otherwise, the object | ||
1478 | * takes ownership of the \c entry.entry pointer. | ||
1479 | * | ||
1480 | * \note If this function returns \c false, the caller still owns the | ||
1481 | * pointer. | ||
1482 | * | ||
1483 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1484 | * \param entry The comment to insert. | ||
1485 | * \param all If \c true, all comments whose field name matches | ||
1486 | * \a entry's field name will be removed, and \a entry will | ||
1487 | * be inserted at the position of the first matching | ||
1488 | * comment. If \c false, only the first comment whose | ||
1489 | * field name matches \a entry's field name will be | ||
1490 | * replaced with \a entry. | ||
1491 | * \param copy See above. | ||
1492 | * \assert | ||
1493 | * \code object != NULL \endcode | ||
1494 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1495 | * \code (entry.entry != NULL && entry.length > 0) || | ||
1496 | * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode | ||
1497 | * \retval FLAC__bool | ||
1498 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1499 | * Vorbis comment specification, else \c true. | ||
1500 | */ | ||
1501 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy); | ||
1502 | |||
1503 | /** Delete a comment in a VORBIS_COMMENT block at the given index. | ||
1504 | * | ||
1505 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1506 | * \param comment_num The index of the comment to delete. | ||
1507 | * \assert | ||
1508 | * \code object != NULL \endcode | ||
1509 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1510 | * \code object->data.vorbis_comment.num_comments > comment_num \endcode | ||
1511 | * \retval FLAC__bool | ||
1512 | * \c false if realloc() fails, else \c true. | ||
1513 | */ | ||
1514 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num); | ||
1515 | |||
1516 | /** Creates a Vorbis comment entry from NUL-terminated name and value strings. | ||
1517 | * | ||
1518 | * On return, the filled-in \a entry->entry pointer will point to malloc()ed | ||
1519 | * memory and shall be owned by the caller. For convenience the entry will | ||
1520 | * have a terminating NUL. | ||
1521 | * | ||
1522 | * \param entry A pointer to a Vorbis comment entry. The entry's | ||
1523 | * \c entry pointer should not point to allocated | ||
1524 | * memory as it will be overwritten. | ||
1525 | * \param field_name The field name in ASCII, \c NUL terminated. | ||
1526 | * \param field_value The field value in UTF-8, \c NUL terminated. | ||
1527 | * \assert | ||
1528 | * \code entry != NULL \endcode | ||
1529 | * \code field_name != NULL \endcode | ||
1530 | * \code field_value != NULL \endcode | ||
1531 | * \retval FLAC__bool | ||
1532 | * \c false if malloc() fails, or if \a field_name or \a field_value does | ||
1533 | * not comply with the Vorbis comment specification, else \c true. | ||
1534 | */ | ||
1535 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value); | ||
1536 | |||
1537 | /** Splits a Vorbis comment entry into NUL-terminated name and value strings. | ||
1538 | * | ||
1539 | * The returned pointers to name and value will be allocated by malloc() | ||
1540 | * and shall be owned by the caller. | ||
1541 | * | ||
1542 | * \param entry An existing Vorbis comment entry. | ||
1543 | * \param field_name The address of where the returned pointer to the | ||
1544 | * field name will be stored. | ||
1545 | * \param field_value The address of where the returned pointer to the | ||
1546 | * field value will be stored. | ||
1547 | * \assert | ||
1548 | * \code (entry.entry != NULL && entry.length > 0) \endcode | ||
1549 | * \code memchr(entry.entry, '=', entry.length) != NULL \endcode | ||
1550 | * \code field_name != NULL \endcode | ||
1551 | * \code field_value != NULL \endcode | ||
1552 | * \retval FLAC__bool | ||
1553 | * \c false if memory allocation fails or \a entry does not comply with the | ||
1554 | * Vorbis comment specification, else \c true. | ||
1555 | */ | ||
1556 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value); | ||
1557 | |||
1558 | /** Check if the given Vorbis comment entry's field name matches the given | ||
1559 | * field name. | ||
1560 | * | ||
1561 | * \param entry An existing Vorbis comment entry. | ||
1562 | * \param field_name The field name to check. | ||
1563 | * \param field_name_length The length of \a field_name, not including the | ||
1564 | * terminating \c NUL. | ||
1565 | * \assert | ||
1566 | * \code (entry.entry != NULL && entry.length > 0) \endcode | ||
1567 | * \retval FLAC__bool | ||
1568 | * \c true if the field names match, else \c false | ||
1569 | */ | ||
1570 | FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length); | ||
1571 | |||
1572 | /** Find a Vorbis comment with the given field name. | ||
1573 | * | ||
1574 | * The search begins at entry number \a offset; use an offset of 0 to | ||
1575 | * search from the beginning of the comment array. | ||
1576 | * | ||
1577 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1578 | * \param offset The offset into the comment array from where to start | ||
1579 | * the search. | ||
1580 | * \param field_name The field name of the comment to find. | ||
1581 | * \assert | ||
1582 | * \code object != NULL \endcode | ||
1583 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1584 | * \code field_name != NULL \endcode | ||
1585 | * \retval int | ||
1586 | * The offset in the comment array of the first comment whose field | ||
1587 | * name matches \a field_name, or \c -1 if no match was found. | ||
1588 | */ | ||
1589 | FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name); | ||
1590 | |||
1591 | /** Remove first Vorbis comment matching the given field name. | ||
1592 | * | ||
1593 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1594 | * \param field_name The field name of comment to delete. | ||
1595 | * \assert | ||
1596 | * \code object != NULL \endcode | ||
1597 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1598 | * \retval int | ||
1599 | * \c -1 for memory allocation error, \c 0 for no matching entries, | ||
1600 | * \c 1 for one matching entry deleted. | ||
1601 | */ | ||
1602 | FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name); | ||
1603 | |||
1604 | /** Remove all Vorbis comments matching the given field name. | ||
1605 | * | ||
1606 | * \param object A pointer to an existing VORBIS_COMMENT object. | ||
1607 | * \param field_name The field name of comments to delete. | ||
1608 | * \assert | ||
1609 | * \code object != NULL \endcode | ||
1610 | * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode | ||
1611 | * \retval int | ||
1612 | * \c -1 for memory allocation error, \c 0 for no matching entries, | ||
1613 | * else the number of matching entries deleted. | ||
1614 | */ | ||
1615 | FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name); | ||
1616 | |||
1617 | /** Create a new CUESHEET track instance. | ||
1618 | * | ||
1619 | * The object will be "empty"; i.e. values and data pointers will be \c 0. | ||
1620 | * | ||
1621 | * \retval FLAC__StreamMetadata_CueSheet_Track* | ||
1622 | * \c NULL if there was an error allocating memory, else the new instance. | ||
1623 | */ | ||
1624 | FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(); | ||
1625 | |||
1626 | /** Create a copy of an existing CUESHEET track object. | ||
1627 | * | ||
1628 | * The copy is a "deep" copy, i.e. dynamically allocated data within the | ||
1629 | * object is also copied. The caller takes ownership of the new object and | ||
1630 | * is responsible for freeing it with | ||
1631 | * FLAC__metadata_object_cuesheet_track_delete(). | ||
1632 | * | ||
1633 | * \param object Pointer to object to copy. | ||
1634 | * \assert | ||
1635 | * \code object != NULL \endcode | ||
1636 | * \retval FLAC__StreamMetadata_CueSheet_Track* | ||
1637 | * \c NULL if there was an error allocating memory, else the new instance. | ||
1638 | */ | ||
1639 | FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object); | ||
1640 | |||
1641 | /** Delete a CUESHEET track object | ||
1642 | * | ||
1643 | * \param object A pointer to an existing CUESHEET track object. | ||
1644 | * \assert | ||
1645 | * \code object != NULL \endcode | ||
1646 | */ | ||
1647 | FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object); | ||
1648 | |||
1649 | /** Resize a track's index point array. | ||
1650 | * | ||
1651 | * If the size shrinks, elements will truncated; if it grows, new blank | ||
1652 | * indices will be added to the end. | ||
1653 | * | ||
1654 | * \param object A pointer to an existing CUESHEET object. | ||
1655 | * \param track_num The index of the track to modify. NOTE: this is not | ||
1656 | * necessarily the same as the track's \a number field. | ||
1657 | * \param new_num_indices The desired length of the array; may be \c 0. | ||
1658 | * \assert | ||
1659 | * \code object != NULL \endcode | ||
1660 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1661 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1662 | * \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) || | ||
1663 | * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode | ||
1664 | * \retval FLAC__bool | ||
1665 | * \c false if memory allocation error, else \c true. | ||
1666 | */ | ||
1667 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices); | ||
1668 | |||
1669 | /** Insert an index point in a CUESHEET track at the given index. | ||
1670 | * | ||
1671 | * \param object A pointer to an existing CUESHEET object. | ||
1672 | * \param track_num The index of the track to modify. NOTE: this is not | ||
1673 | * necessarily the same as the track's \a number field. | ||
1674 | * \param index_num The index into the track's index array at which to | ||
1675 | * insert the index point. NOTE: this is not necessarily | ||
1676 | * the same as the index point's \a number field. The | ||
1677 | * indices at and after \a index_num move right one | ||
1678 | * position. To append an index point to the end, set | ||
1679 | * \a index_num to | ||
1680 | * \c object->data.cue_sheet.tracks[track_num].num_indices . | ||
1681 | * \param index The index point to insert. | ||
1682 | * \assert | ||
1683 | * \code object != NULL \endcode | ||
1684 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1685 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1686 | * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode | ||
1687 | * \retval FLAC__bool | ||
1688 | * \c false if realloc() fails, else \c true. | ||
1689 | */ | ||
1690 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index); | ||
1691 | |||
1692 | /** Insert a blank index point in a CUESHEET track at the given index. | ||
1693 | * | ||
1694 | * A blank index point is one in which all field values are zero. | ||
1695 | * | ||
1696 | * \param object A pointer to an existing CUESHEET object. | ||
1697 | * \param track_num The index of the track to modify. NOTE: this is not | ||
1698 | * necessarily the same as the track's \a number field. | ||
1699 | * \param index_num The index into the track's index array at which to | ||
1700 | * insert the index point. NOTE: this is not necessarily | ||
1701 | * the same as the index point's \a number field. The | ||
1702 | * indices at and after \a index_num move right one | ||
1703 | * position. To append an index point to the end, set | ||
1704 | * \a index_num to | ||
1705 | * \c object->data.cue_sheet.tracks[track_num].num_indices . | ||
1706 | * \assert | ||
1707 | * \code object != NULL \endcode | ||
1708 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1709 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1710 | * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode | ||
1711 | * \retval FLAC__bool | ||
1712 | * \c false if realloc() fails, else \c true. | ||
1713 | */ | ||
1714 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); | ||
1715 | |||
1716 | /** Delete an index point in a CUESHEET track at the given index. | ||
1717 | * | ||
1718 | * \param object A pointer to an existing CUESHEET object. | ||
1719 | * \param track_num The index into the track array of the track to | ||
1720 | * modify. NOTE: this is not necessarily the same | ||
1721 | * as the track's \a number field. | ||
1722 | * \param index_num The index into the track's index array of the index | ||
1723 | * to delete. NOTE: this is not necessarily the same | ||
1724 | * as the index's \a number field. | ||
1725 | * \assert | ||
1726 | * \code object != NULL \endcode | ||
1727 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1728 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1729 | * \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode | ||
1730 | * \retval FLAC__bool | ||
1731 | * \c false if realloc() fails, else \c true. | ||
1732 | */ | ||
1733 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); | ||
1734 | |||
1735 | /** Resize the track array. | ||
1736 | * | ||
1737 | * If the size shrinks, elements will truncated; if it grows, new blank | ||
1738 | * tracks will be added to the end. | ||
1739 | * | ||
1740 | * \param object A pointer to an existing CUESHEET object. | ||
1741 | * \param new_num_tracks The desired length of the array; may be \c 0. | ||
1742 | * \assert | ||
1743 | * \code object != NULL \endcode | ||
1744 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1745 | * \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) || | ||
1746 | * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode | ||
1747 | * \retval FLAC__bool | ||
1748 | * \c false if memory allocation error, else \c true. | ||
1749 | */ | ||
1750 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks); | ||
1751 | |||
1752 | /** Sets a track in a CUESHEET block. | ||
1753 | * | ||
1754 | * If \a copy is \c true, a copy of the track is stored; otherwise, the object | ||
1755 | * takes ownership of the \a track pointer. | ||
1756 | * | ||
1757 | * \param object A pointer to an existing CUESHEET object. | ||
1758 | * \param track_num Index into track array to set. NOTE: this is not | ||
1759 | * necessarily the same as the track's \a number field. | ||
1760 | * \param track The track to set the track to. You may safely pass in | ||
1761 | * a const pointer if \a copy is \c true. | ||
1762 | * \param copy See above. | ||
1763 | * \assert | ||
1764 | * \code object != NULL \endcode | ||
1765 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1766 | * \code track_num < object->data.cue_sheet.num_tracks \endcode | ||
1767 | * \code (track->indices != NULL && track->num_indices > 0) || | ||
1768 | * (track->indices == NULL && track->num_indices == 0) | ||
1769 | * \retval FLAC__bool | ||
1770 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1771 | */ | ||
1772 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); | ||
1773 | |||
1774 | /** Insert a track in a CUESHEET block at the given index. | ||
1775 | * | ||
1776 | * If \a copy is \c true, a copy of the track is stored; otherwise, the object | ||
1777 | * takes ownership of the \a track pointer. | ||
1778 | * | ||
1779 | * \param object A pointer to an existing CUESHEET object. | ||
1780 | * \param track_num The index at which to insert the track. NOTE: this | ||
1781 | * is not necessarily the same as the track's \a number | ||
1782 | * field. The tracks at and after \a track_num move right | ||
1783 | * one position. To append a track to the end, set | ||
1784 | * \a track_num to \c object->data.cue_sheet.num_tracks . | ||
1785 | * \param track The track to insert. You may safely pass in a const | ||
1786 | * pointer if \a copy is \c true. | ||
1787 | * \param copy See above. | ||
1788 | * \assert | ||
1789 | * \code object != NULL \endcode | ||
1790 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1791 | * \code object->data.cue_sheet.num_tracks >= track_num \endcode | ||
1792 | * \retval FLAC__bool | ||
1793 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1794 | */ | ||
1795 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); | ||
1796 | |||
1797 | /** Insert a blank track in a CUESHEET block at the given index. | ||
1798 | * | ||
1799 | * A blank track is one in which all field values are zero. | ||
1800 | * | ||
1801 | * \param object A pointer to an existing CUESHEET object. | ||
1802 | * \param track_num The index at which to insert the track. NOTE: this | ||
1803 | * is not necessarily the same as the track's \a number | ||
1804 | * field. The tracks at and after \a track_num move right | ||
1805 | * one position. To append a track to the end, set | ||
1806 | * \a track_num to \c object->data.cue_sheet.num_tracks . | ||
1807 | * \assert | ||
1808 | * \code object != NULL \endcode | ||
1809 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1810 | * \code object->data.cue_sheet.num_tracks >= track_num \endcode | ||
1811 | * \retval FLAC__bool | ||
1812 | * \c false if \a copy is \c true and malloc() fails, else \c true. | ||
1813 | */ | ||
1814 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num); | ||
1815 | |||
1816 | /** Delete a track in a CUESHEET block at the given index. | ||
1817 | * | ||
1818 | * \param object A pointer to an existing CUESHEET object. | ||
1819 | * \param track_num The index into the track array of the track to | ||
1820 | * delete. NOTE: this is not necessarily the same | ||
1821 | * as the track's \a number field. | ||
1822 | * \assert | ||
1823 | * \code object != NULL \endcode | ||
1824 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1825 | * \code object->data.cue_sheet.num_tracks > track_num \endcode | ||
1826 | * \retval FLAC__bool | ||
1827 | * \c false if realloc() fails, else \c true. | ||
1828 | */ | ||
1829 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num); | ||
1830 | |||
1831 | /** Check a cue sheet to see if it conforms to the FLAC specification. | ||
1832 | * See the format specification for limits on the contents of the | ||
1833 | * cue sheet. | ||
1834 | * | ||
1835 | * \param object A pointer to an existing CUESHEET object. | ||
1836 | * \param check_cd_da_subset If \c true, check CUESHEET against more | ||
1837 | * stringent requirements for a CD-DA (audio) disc. | ||
1838 | * \param violation Address of a pointer to a string. If there is a | ||
1839 | * violation, a pointer to a string explanation of the | ||
1840 | * violation will be returned here. \a violation may be | ||
1841 | * \c NULL if you don't need the returned string. Do not | ||
1842 | * free the returned string; it will always point to static | ||
1843 | * data. | ||
1844 | * \assert | ||
1845 | * \code object != NULL \endcode | ||
1846 | * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode | ||
1847 | * \retval FLAC__bool | ||
1848 | * \c false if cue sheet is illegal, else \c true. | ||
1849 | */ | ||
1850 | FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation); | ||
1851 | |||
1852 | /* \} */ | ||
1853 | |||
1854 | #ifdef __cplusplus | ||
1855 | } | ||
1856 | #endif | ||
1857 | |||
1858 | #endif | ||