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