include/FLAC/metadata.h Source File

Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# include/FLAC/metadata.h

Go to the documentation of this file.

    00001 /* libFLAC - Free Lossless Audio Codec library
    00002  * Copyright (C) 2001,2002,2003,2004,2005  Josh Coalson
    00003  *
    00004  * Redistribution and use in source and binary forms, with or without
    00005  * modification, are permitted provided that the following conditions
    00006  * are met:
    00007  *
    00008  * - Redistributions of source code must retain the above copyright
    00009  * notice, this list of conditions and the following disclaimer.
    00010  *
    00011  * - Redistributions in binary form must reproduce the above copyright
    00012  * notice, this list of conditions and the following disclaimer in the
    00013  * documentation and/or other materials provided with the distribution.
    00014  *
    00015  * - Neither the name of the Xiph.org Foundation nor the names of its
    00016  * contributors may be used to endorse or promote products derived from
    00017  * this software without specific prior written permission.
    00018  *
    00019  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    00020  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    00021  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    00022  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
    00023  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    00024  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    00025  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    00026  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    00027  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    00028  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    00030  */
    00031
    00032 #ifndef FLAC__METADATA_H
    00033 #define FLAC__METADATA_H
    00034
    00035 #include "export.h"
    00036 #include "callback.h"
    00037 #include "format.h"
    00038
    00039 /******************************************************************************
    00040     (For an example of how all these routines are used, see the source
    00041     code for the unit tests in src/test_libFLAC/metadata_*.c, or metaflac
    00042     in src/metaflac/)
    00043 ******************************************************************************/
    00044
    00117 #ifdef __cplusplus
    00118 extern "C" {
    00119 #endif
    00120
    00121
    00151 FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
    00152
    00170 FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
    00171
    00172 /* \} */
    00173
    00174
    00230 struct FLAC__Metadata_SimpleIterator;
    00236 typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
    00237
    00242 typedef enum {
    00243
    00244     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
    00247     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
    00250     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
    00253     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
    00256     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
    00259     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
    00262     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
    00265     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
    00268     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
    00271     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
    00274     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
    00277     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
    00280     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
    00283 } FLAC__Metadata_SimpleIteratorStatus;
    00284
    00290 extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
    00291
    00292
    00298 FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new();
    00299
    00306 FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
    00307
    00318 FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
    00319
    00339 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);
    00340
    00351 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
    00352
    00365 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
    00366
    00379 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
    00380
    00394 FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
    00395
    00411 FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
    00412
    00467 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
    00468
    00492 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
    00493
    00511 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
    00512
    00513 /* \} */
    00514
    00515
    00568 struct FLAC__Metadata_Chain;
    00571 typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
    00572
    00573 struct FLAC__Metadata_Iterator;
    00576 typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
    00577
    00578 typedef enum {
    00579     FLAC__METADATA_CHAIN_STATUS_OK = 0,
    00582     FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
    00585     FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
    00588     FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
    00591     FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
    00594     FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
    00597     FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
    00600     FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
    00603     FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
    00606     FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
    00609     FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
    00612     FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
    00615     FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
    00618     FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
    00621     FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
    00629     FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
    00639 } FLAC__Metadata_ChainStatus;
    00640
    00646 extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
    00647
    00648 /*********** FLAC__Metadata_Chain ***********/
    00649
    00655 FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new();
    00656
    00663 FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
    00664
    00675 FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
    00676
    00689 FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
    00690
    00711 FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    00712
    00739 FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
    00740
    00784 FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
    00785
    00813 FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    00814
    00863 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);
    00864
    00877 FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
    00878
    00892 FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
    00893
    00894
    00895 /*********** FLAC__Metadata_Iterator ***********/
    00896
    00902 FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new();
    00903
    00910 FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
    00911
    00921 FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
    00922
    00935 FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
    00936
    00949 FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
    00950
    00961 FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
    00962
    00982 FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
    00983
    00999 FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
    01000
    01017 FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
    01018
    01036 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
    01037
    01054 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
    01055
    01056 /* \} */
    01057
    01058
    01124 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
    01125
    01138 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
    01139
    01149 FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
    01150
    01164 FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
    01165
    01183 FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
    01184
    01200 FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
    01201
    01212 FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
    01213
    01226 FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
    01227
    01239 FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
    01240
    01252 FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
    01253
    01269 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
    01270
    01286 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
    01287
    01304 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
    01305
    01325 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
    01326
    01342 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
    01343
    01367 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01368
    01384 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
    01385
    01411 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01412
    01441 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01442
    01466 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01467
    01501 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
    01502
    01514 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
    01515
    01535 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);
    01536
    01556 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);
    01557
    01570 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
    01571
    01589 FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
    01590
    01602 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
    01603
    01615 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
    01616
    01624 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new();
    01625
    01639 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
    01640
    01647 FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
    01648
    01667 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
    01668
    01690 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);
    01691
    01714 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
    01715
    01733 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
    01734
    01750 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
    01751
    01772 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
    01773
    01795 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
    01796
    01814 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
    01815
    01829 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
    01830
    01850 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
    01851
    01852 /* \} */
    01853
    01854 #ifdef __cplusplus
    01855 }
    01856 #endif
    01857
    01858 #endif