Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members

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 "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
00042    metaflac in src/metaflac/)
00043    ------------------------------------------------------------------*/
00044 
00122 #ifdef __cplusplus
00123 extern "C" {
00124 #endif
00125 
00126 
00157 FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo);
00158 
00176 FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags);
00177 
00195 FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet);
00196 
00235 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);
00236 
00237 /* \} */
00238 
00239 
00295 struct FLAC__Metadata_SimpleIterator;
00301 typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator;
00302 
00307 typedef enum {
00308 
00309     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0,
00312     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT,
00315     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE,
00318     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE,
00321     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE,
00324     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA,
00327     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR,
00330     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR,
00333     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR,
00336     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR,
00339     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR,
00342     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR,
00345     FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR
00348 } FLAC__Metadata_SimpleIteratorStatus;
00349 
00355 extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[];
00356 
00357 
00363 FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void);
00364 
00371 FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator);
00372 
00383 FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator);
00384 
00404 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);
00405 
00416 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator);
00417 
00430 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator);
00431 
00444 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator);
00445 
00459 FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator);
00460 
00476 FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator);
00477 
00532 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
00533 
00557 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding);
00558 
00576 FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding);
00577 
00578 /* \} */
00579 
00580 
00638 struct FLAC__Metadata_Chain;
00641 typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain;
00642 
00643 struct FLAC__Metadata_Iterator;
00646 typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator;
00647 
00648 typedef enum {
00649     FLAC__METADATA_CHAIN_STATUS_OK = 0,
00652     FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT,
00655     FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE,
00658     FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE,
00661     FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE,
00664     FLAC__METADATA_CHAIN_STATUS_BAD_METADATA,
00667     FLAC__METADATA_CHAIN_STATUS_READ_ERROR,
00670     FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR,
00673     FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR,
00676     FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR,
00679     FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR,
00682     FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR,
00685     FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR,
00688     FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS,
00691     FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH,
00700     FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL
00710 } FLAC__Metadata_ChainStatus;
00711 
00717 extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[];
00718 
00719 /*********** FLAC__Metadata_Chain ***********/
00720 
00726 FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void);
00727 
00734 FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain);
00735 
00746 FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain);
00747 
00760 FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename);
00761 
00762 /*@@@@ add to unit tests*/
00778 FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename);
00779 
00800 FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
00801 
00802 /*@@@@ add to unit tests*/
00826 FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
00827 
00854 FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding);
00855 
00900 FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats);
00901 
00930 FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks);
00931 
00981 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);
00982 
00995 FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain);
00996 
01010 FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain);
01011 
01012 
01013 /*********** FLAC__Metadata_Iterator ***********/
01014 
01020 FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void);
01021 
01028 FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator);
01029 
01039 FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain);
01040 
01053 FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator);
01054 
01067 FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator);
01068 
01079 FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator);
01080 
01100 FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator);
01101 
01117 FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
01118 
01135 FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding);
01136 
01154 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
01155 
01172 FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block);
01173 
01174 /* \} */
01175 
01176 
01242 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type);
01243 
01256 FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object);
01257 
01267 FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object);
01268 
01282 FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2);
01283 
01305 FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy);
01306 
01322 FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points);
01323 
01334 FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
01335 
01348 FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point);
01349 
01361 FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num);
01362 
01374 FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object);
01375 
01391 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num);
01392 
01408 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number);
01409 
01426 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num);
01427 
01448 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
01449 
01476 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
01477 
01493 FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact);
01494 
01518 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
01519 
01535 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
01536 
01562 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
01563 
01592 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
01593 
01617 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
01618 
01652 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
01653 
01665 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num);
01666 
01686 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);
01687 
01707 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);
01708 
01721 FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length);
01722 
01740 FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name);
01741 
01753 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name);
01754 
01766 FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name);
01767 
01775 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void);
01776 
01790 FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object);
01791 
01798 FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object);
01799 
01818 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
01819 
01841 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);
01842 
01865 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
01866 
01884 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
01885 
01901 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
01902 
01923 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
01924 
01946 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
01947 
01965 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
01966 
01980 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
01981 
02001 FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation);
02002 
02003 /* @@@@ add to unit tests */
02015 FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object);
02016 
02038 FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy);
02039 
02060 FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy);
02061 
02085 FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy);
02086 
02104 FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation);
02105 
02106 /* \} */
02107 
02108 #ifdef __cplusplus
02109 }
02110 #endif
02111 
02112 #endif