# metadata.h

Go to the documentation of this file.

    00001 /* libFLAC - Free Lossless Audio Codec library
    00002  * Copyright (C) 2001,2002,2003,2004,2005,2006,2007  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 <sys/types.h> /* for off_t */
    00036 #include "export.h"
    00037 #include "callback.h"
    00038 #include "format.h"
    00039
    00040 /* --------------------------------------------------------------------
    00041    (For an example of how all these routines are used, see the source
    00042    code for the unit tests in src/test_libFLAC/metadata_*.c, or
    00043    metaflac in src/metaflac/)
    00044    ------------------------------------------------------------------*/
    00045
    00123 #ifdef __cplusplus
    00124 extern "C" {
    00125 #endif
    00126
    00127
    00158 FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
    00159
    00177 FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
    00178
    00196 FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
    00197
    00236 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);
    00237
    00238 /* \} */
    00239
    00240
    00296 struct FLAC__Metadata_SimpleIterator;
    00302 typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
    00303
    00308 typedef enum {
    00309
    00310     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
    00313     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
    00316     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
    00319     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
    00322     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
    00325     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
    00328     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
    00331     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
    00334     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
    00337     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
    00340     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
    00343     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
    00346     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
    00349 } FLAC__Metadata_SimpleIteratorStatus;
    00350
    00356 extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
    00357
    00358
    00364 FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
    00365
    00372 FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
    00373
    00384 FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
    00385
    00405 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);
    00406
    00417 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
    00418
    00431 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
    00432
    00445 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
    00446
    00458 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator);
    00459
    00474 FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator);
    00475
    00488 FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
    00489
    00505 FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator);
    00506
    00530 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id);
    00531
    00548 FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
    00549
    00604 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
    00605
    00629 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
    00630
    00648 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
    00649
    00650 /* \} */
    00651
    00652
    00710 struct FLAC__Metadata_Chain;
    00713 typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
    00714
    00715 struct FLAC__Metadata_Iterator;
    00718 typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
    00719
    00720 typedef enum {
    00721     FLAC__METADATA_CHAIN_STATUS_OK = 0,
    00724     FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
    00727     FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
    00730     FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
    00733     FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
    00736     FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
    00739     FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
    00742     FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
    00745     FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
    00748     FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
    00751     FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
    00754     FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
    00757     FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
    00760     FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
    00763     FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
    00772     FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
    00782 } FLAC__Metadata_ChainStatus;
    00783
    00789 extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
    00790
    00791 /*********** FLAC__Metadata_Chain ***********/
    00792
    00798 FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
    00799
    00806 FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
    00807
    00818 FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
    00819
    00832 FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
    00833
    00849 FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
    00850
    00871 FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    00872
    00896 FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    00897
    00924 FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
    00925
    00970 FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
    00971
    01000 FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
    01001
    01051 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);
    01052
    01065 FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
    01066
    01080 FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
    01081
    01082
    01083 /*********** FLAC__Metadata_Iterator ***********/
    01084
    01090 FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
    01091
    01098 FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
    01099
    01109 FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
    01110
    01123 FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
    01124
    01137 FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
    01138
    01149 FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
    01150
    01170 FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
    01171
    01187 FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
    01188
    01205 FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
    01206
    01224 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
    01225
    01242 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
    01243
    01244 /* \} */
    01245
    01246
    01312 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
    01313
    01326 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
    01327
    01337 FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
    01338
    01352 FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
    01353
    01375 FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
    01376
    01392 FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
    01393
    01404 FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
    01405
    01418 FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
    01419
    01431 FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
    01432
    01444 FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
    01445
    01461 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
    01462
    01478 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
    01479
    01496 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
    01497
    01518 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
    01519
    01546 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
    01547
    01563 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
    01564
    01588 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01589
    01605 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
    01606
    01632 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01633
    01662 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01663
    01687 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
    01688
    01722 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
    01723
    01735 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
    01736
    01756 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);
    01757
    01777 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);
    01778
    01791 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
    01792
    01810 FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
    01811
    01823 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
    01824
    01836 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
    01837
    01845 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
    01846
    01860 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
    01861
    01868 FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
    01869
    01888 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
    01889
    01911 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);
    01912
    01935 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
    01936
    01954 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
    01955
    01971 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
    01972
    01993 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
    01994
    02016 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
    02017
    02035 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
    02036
    02050 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
    02051
    02071 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
    02072
    02084 FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
    02085
    02107 FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
    02108
    02129 FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
    02130
    02154 FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
    02155
    02173 FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
    02174
    02175 /* \} */
    02176
    02177 #ifdef __cplusplus
    02178 }
    02179 #endif
    02180
    02181 #endif

Copyright (c) 2000,2001,2002,2003,2004,2005,2006,2007 Josh Coalson |