FLAC/metadata.h: metadata object methods
[FLAC/metadata.h: metadata interfaces]

---

Detailed Description

This module contains methods for manipulating FLAC metadata objects.

Since many are variable length we have to be careful about the memory management. We decree that all pointers to data in the object are owned by the object and memory-managed by the object.

Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete() functions to create all instances. When using the FLAC__metadata_object_set_*() functions to set pointers to data, set copy to true to have the function make it's own copy of the data, or to false to give the object ownership of your data. In the latter case your pointer must be freeable by free() and will be free()d when the object is FLAC__metadata_object_delete()d. It is legal to pass a null pointer as the data pointer to a FLAC__metadata_object_set_*() function as long as the length argument is 0 and the copy argument is false.

The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function will return NULL in the case of a memory allocation error, otherwise a new object. The FLAC__metadata_object_set_*() functions return false in the case of a memory allocation error.

We don't have the convenience of C++ here, so note that the library relies on you to keep the types straight. In other words, if you pass, for example, a FLAC__StreamMetadata* that represents a STREAMINFO block to FLAC__metadata_object_application_set_data(), you will get an assertion failure.

There is no need to recalculate the length field on metadata blocks you have modified. They will be calculated automatically before they are written back to a file.

Functions
FLAC__StreamMetadata *	FLAC__metadata_object_new (FLAC__MetadataType type)
FLAC__StreamMetadata *	FLAC__metadata_object_clone (const FLAC__StreamMetadata *object)
void	FLAC__metadata_object_delete (FLAC__StreamMetadata *object)
FLAC__bool	FLAC__metadata_object_is_equal (const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2)
FLAC__bool	FLAC__metadata_object_application_set_data (FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy)
FLAC__bool	FLAC__metadata_object_seektable_resize_points (FLAC__StreamMetadata *object, unsigned new_num_points)
void	FLAC__metadata_object_seektable_set_point (FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point)
FLAC__bool	FLAC__metadata_object_seektable_insert_point (FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point)
FLAC__bool	FLAC__metadata_object_seektable_delete_point (FLAC__StreamMetadata *object, unsigned point_num)
FLAC__bool	FLAC__metadata_object_seektable_is_legal (const FLAC__StreamMetadata *object)
FLAC__bool	FLAC__metadata_object_seektable_template_append_placeholders (FLAC__StreamMetadata *object, unsigned num)
FLAC__bool	FLAC__metadata_object_seektable_template_append_point (FLAC__StreamMetadata *object, FLAC__uint64 sample_number)
FLAC__bool	FLAC__metadata_object_seektable_template_append_points (FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num)
FLAC__bool	FLAC__metadata_object_seektable_template_append_spaced_points (FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples)
FLAC__bool	FLAC__metadata_object_seektable_template_sort (FLAC__StreamMetadata *object, FLAC__bool compact)
FLAC__bool	FLAC__metadata_object_vorbiscomment_set_vendor_string (FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy)
FLAC__bool	FLAC__metadata_object_vorbiscomment_resize_comments (FLAC__StreamMetadata *object, unsigned new_num_comments)
FLAC__bool	FLAC__metadata_object_vorbiscomment_set_comment (FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy)
FLAC__bool	FLAC__metadata_object_vorbiscomment_insert_comment (FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy)
FLAC__bool	FLAC__metadata_object_vorbiscomment_delete_comment (FLAC__StreamMetadata *object, unsigned comment_num)
FLAC__bool	FLAC__metadata_object_vorbiscomment_entry_matches (const FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, unsigned field_name_length)
int	FLAC__metadata_object_vorbiscomment_find_entry_from (const FLAC__StreamMetadata *object, unsigned offset, const char *field_name)
int	FLAC__metadata_object_vorbiscomment_remove_entry_matching (FLAC__StreamMetadata *object, const char *field_name)
int	FLAC__metadata_object_vorbiscomment_remove_entries_matching (FLAC__StreamMetadata *object, const char *field_name)
FLAC__StreamMetadata_CueSheet_Track *	FLAC__metadata_object_cuesheet_track_new ()
FLAC__StreamMetadata_CueSheet_Track *	FLAC__metadata_object_cuesheet_track_clone (const FLAC__StreamMetadata_CueSheet_Track *object)
void	FLAC__metadata_object_cuesheet_track_delete (FLAC__StreamMetadata_CueSheet_Track *object)
FLAC__bool	FLAC__metadata_object_cuesheet_track_resize_indices (FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices)
FLAC__bool	FLAC__metadata_object_cuesheet_track_insert_index (FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index)
FLAC__bool	FLAC__metadata_object_cuesheet_track_insert_blank_index (FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num)
FLAC__bool	FLAC__metadata_object_cuesheet_track_delete_index (FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num)
FLAC__bool	FLAC__metadata_object_cuesheet_resize_tracks (FLAC__StreamMetadata *object, unsigned new_num_tracks)
FLAC__bool	FLAC__metadata_object_cuesheet_insert_track (FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy)
FLAC__bool	FLAC__metadata_object_cuesheet_insert_blank_track (FLAC__StreamMetadata *object, unsigned track_num)
FLAC__bool	FLAC__metadata_object_cuesheet_delete_track (FLAC__StreamMetadata *object, unsigned track_num)
FLAC__bool	FLAC__metadata_object_cuesheet_is_legal (const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation)

---

Function Documentation

FLAC__StreamMetadata* FLAC__metadata_object_new (  FLAC__MetadataType  type  )

Create a new metadata object instance of the given type. The object will be "empty"; i.e. values and data pointers will be 0, with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have the vendor string set (but zero comments). Do not pass in a value greater than or equal to FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're doing. Parameters: type  Type of object to create Return values: FLAC__StreamMetadata*  NULL if there was an error allocating memory, else the new instance.

FLAC__StreamMetadata* FLAC__metadata_object_clone (  const FLAC__StreamMetadata *  object  )

Create a copy of an existing metadata object. The copy is a "deep" copy, i.e. dynamically allocated data within the object is also copied. The caller takes ownership of the new block and is responsible for freeing it with FLAC__metadata_object_delete(). Parameters: object  Pointer to object to copy. Assertions: object != NULL Return values: FLAC__StreamMetadata*  NULL if there was an error allocating memory, else the new instance.

void FLAC__metadata_object_delete (  FLAC__StreamMetadata *  object  )

Free a metadata object. Deletes the object pointed to by object. The delete is a "deep" delete, i.e. dynamically allocated data within the object is also deleted. Parameters: object  A pointer to an existing object. Assertions: object != NULL

FLAC__bool FLAC__metadata_object_is_equal (  const FLAC__StreamMetadata *  block1, const FLAC__StreamMetadata *  block2 )

Compares two metadata objects. The compare is "deep", i.e. dynamically allocated data within the object is also compared. Parameters: block1  A pointer to an existing object. block2  A pointer to an existing object. Assertions: block1 != NULL block2 != NULL Return values: FLAC__bool  true if objects are identical, else false.

FLAC__bool FLAC__metadata_object_application_set_data (  FLAC__StreamMetadata *  object, FLAC__byte *  data, unsigned  length, FLAC__bool  copy )

Sets the application data of an APPLICATION block. If copy is true, a copy of the data is stored; otherwise, the object takes ownership of the pointer. Returns false if copy == true and malloc fails. Parameters: object  A pointer to an existing APPLICATION object. data  A pointer to the data to set. length  The length of data in bytes. copy  See above. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_APPLICATION (data != NULL && length > 0) || (data == NULL && length == 0 && copy == false) Return values: FLAC__bool  false if copy is true and malloc fails, else true.

FLAC__bool FLAC__metadata_object_seektable_resize_points (  FLAC__StreamMetadata *  object, unsigned  new_num_points )

Resize the seekpoint array. If the size shrinks, elements will truncated; if it grows, new placeholder points will be added to the end. Parameters: object  A pointer to an existing SEEKTABLE object. new_num_points  The desired length of the array; may be 0. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) || (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) Return values: FLAC__bool  false if memory allocation error, else true.

void FLAC__metadata_object_seektable_set_point (  FLAC__StreamMetadata *  object, unsigned  point_num, FLAC__StreamMetadata_SeekPoint  point )

Set a seekpoint in a seektable. Parameters: object  A pointer to an existing SEEKTABLE object. point_num  Index into seekpoint array to set. point  The point to set. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE object->data.seek_table.num_points > point_num

FLAC__bool FLAC__metadata_object_seektable_insert_point (  FLAC__StreamMetadata *  object, unsigned  point_num, FLAC__StreamMetadata_SeekPoint  point )

Insert a seekpoint into a seektable. Parameters: object  A pointer to an existing SEEKTABLE object. point_num  Index into seekpoint array to set. point  The point to set. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE object->data.seek_table.num_points >= point_num Return values: FLAC__bool  false if memory allocation error, else true.

FLAC__bool FLAC__metadata_object_seektable_delete_point (  FLAC__StreamMetadata *  object, unsigned  point_num )

Delete a seekpoint from a seektable. Parameters: object  A pointer to an existing SEEKTABLE object. point_num  Index into seekpoint array to set. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE object->data.seek_table.num_points > point_num Return values: FLAC__bool  false if memory allocation error, else true.

FLAC__bool FLAC__metadata_object_seektable_is_legal (  const FLAC__StreamMetadata *  object  )

Check a seektable to see if it conforms to the FLAC specification. See the format specification for limits on the contents of the seektable. Parameters: object  A pointer to an existing SEEKTABLE object. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE Return values: FLAC__bool  false if seek table is illegal, else true.

FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders (  FLAC__StreamMetadata *  object, unsigned  num )

Append a number of placeholder points to the end of a seek table. Note: As with the other ..._seektable_template_... functions, you should call FLAC__metadata_object_seektable_template_sort() when finished to make the seek table legal. Parameters: object  A pointer to an existing SEEKTABLE object. num  The number of placeholder points to append. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE Return values: FLAC__bool  false if memory allocation fails, else true.

FLAC__bool FLAC__metadata_object_seektable_template_append_point (  FLAC__StreamMetadata *  object, FLAC__uint64  sample_number )

Append a specific seek point template to the end of a seek table. Note: As with the other ..._seektable_template_... functions, you should call FLAC__metadata_object_seektable_template_sort() when finished to make the seek table legal. Parameters: object  A pointer to an existing SEEKTABLE object. sample_number  The sample number of the seek point template. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE Return values: FLAC__bool  false if memory allocation fails, else true.

FLAC__bool FLAC__metadata_object_seektable_template_append_points (  FLAC__StreamMetadata *  object, FLAC__uint64  sample_numbers[], unsigned  num )

Append specific seek point templates to the end of a seek table. Note: As with the other ..._seektable_template_... functions, you should call FLAC__metadata_object_seektable_template_sort() when finished to make the seek table legal. Parameters: object  A pointer to an existing SEEKTABLE object. sample_numbers  An array of sample numbers for the seek points. num  The number of seek point templates to append. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE Return values: FLAC__bool  false if memory allocation fails, else true.

FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points (  FLAC__StreamMetadata *  object, unsigned  num, FLAC__uint64  total_samples )

Append a set of evenly-spaced seek point templates to the end of a seek table. Note: As with the other ..._seektable_template_... functions, you should call FLAC__metadata_object_seektable_template_sort() when finished to make the seek table legal. Parameters: object  A pointer to an existing SEEKTABLE object. num  The number of placeholder points to append. total_samples  The total number of samples to be encoded; the seekpoints will be spaced approximately total_samples / num samples apart. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE Return values: FLAC__bool  false if memory allocation fails, else true.

FLAC__bool FLAC__metadata_object_seektable_template_sort (  FLAC__StreamMetadata *  object, FLAC__bool  compact )

Sort a seek table's seek points according to the format specification, removing duplicates. Parameters: object  A pointer to a seek table to be sorted. compact  If false, behaves like FLAC__format_seektable_sort(). If true, duplicates are deleted and the seek table is shrunk appropriately; the number of placeholder points present in the seek table will be the same after the call as before. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_SEEKTABLE Return values: FLAC__bool  false if realloc fails, else true.

FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string (  FLAC__StreamMetadata *  object, FLAC__StreamMetadata_VorbisComment_Entry  entry, FLAC__bool  copy )

Sets the vendor string in a VORBIS_COMMENT block. If copy is true, a copy of the entry is stored; otherwise, the object takes ownership of the entry->entry pointer. Returns false if copy == true and malloc fails. Parameters: object  A pointer to an existing VORBIS_COMMENT object. entry  The entry to set the vendor string to. copy  See above. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT (entry->entry != NULL && entry->length > 0) || (entry->entry == NULL && entry->length == 0 && copy == false) Return values: FLAC__bool  false if copy is true and malloc fails, else true.

FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments (  FLAC__StreamMetadata *  object, unsigned  new_num_comments )

Resize the comment array. If the size shrinks, elements will truncated; if it grows, new empty fields will be added to the end. Parameters: object  A pointer to an existing VORBIS_COMMENT object. new_num_comments  The desired length of the array; may be 0. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) || (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) Return values: FLAC__bool  false if memory allocation error, else true.

FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment (  FLAC__StreamMetadata *  object, unsigned  comment_num, FLAC__StreamMetadata_VorbisComment_Entry  entry, FLAC__bool  copy )

Sets a comment in a VORBIS_COMMENT block. If copy is true, a copy of the entry is stored; otherwise, the object takes ownership of the entry->entry pointer. Returns false if copy == true and malloc fails. Parameters: object  A pointer to an existing VORBIS_COMMENT object. comment_num  Index into comment array to set. entry  The entry to set the comment to. copy  See above. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT comment_num < object->data.vorbis_comment.num_comments (entry->entry != NULL && entry->length > 0) || (entry->entry == NULL && entry->length == 0 && copy == false) Return values: FLAC__bool  false if copy is true and malloc fails, else true.

FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment (  FLAC__StreamMetadata *  object, unsigned  comment_num, FLAC__StreamMetadata_VorbisComment_Entry  entry, FLAC__bool  copy )

Insert a comment in a VORBIS_COMMENT block at the given index. If copy is true, a copy of the entry is stored; otherwise, the object takes ownership of the entry->entry pointer. Returns false if copy == true and malloc fails. Parameters: object  A pointer to an existing VORBIS_COMMENT object. comment_num  The index at which to insert the comment. The comments at and after comment_num move right one position. To append a comment to the end, set comment_num to object->data.vorbis_comment.num_comments . entry  The comment to insert. copy  See above. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT object->data.vorbis_comment.num_comments >= comment_num (entry->entry != NULL && entry->length > 0) || (entry->entry == NULL && entry->length == 0 && copy == false) Return values: FLAC__bool  false if copy is true and malloc fails, else true.

FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment (  FLAC__StreamMetadata *  object, unsigned  comment_num )

Delete a comment in a VORBIS_COMMENT block at the given index. Parameters: object  A pointer to an existing VORBIS_COMMENT object. comment_num  The index of the comment to delete. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT object->data.vorbis_comment.num_comments > comment_num (entry->entry != NULL && entry->length > 0) || (entry->entry == NULL && entry->length == 0 && copy == false) Return values: FLAC__bool  false if realloc fails, else true.

FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches (  const FLAC__StreamMetadata_VorbisComment_Entry *  entry, const char *  field_name, unsigned  field_name_length )

Check if the given Vorbis comment entry's field name matches the given field name. Parameters: entry  A pointer to an existing Vorbis comment entry. field_name  The field name to check. field_name_length  The length of field_name, not including the terminating NULL. Assertions: entry != NULL (entry->entry != NULL && entry->length > 0) Return values: FLAC__bool  true if the field names match, else false

int FLAC__metadata_object_vorbiscomment_find_entry_from (  const FLAC__StreamMetadata *  object, unsigned  offset, const char *  field_name )

Find a Vorbis comment with the given field name. The search begins at entry number offset; use and offset of 0 to search from the beginning of the comment array. Parameters: object  A pointer to an existing VORBIS_COMMENT object. offset  The offset into the comment array from where to start the search. field_name  The field name of the comment to find. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT Return values: int  The offset in the comment array of the first comment whose field name matches field_name, or -1 if no match was found.

int FLAC__metadata_object_vorbiscomment_remove_entry_matching (  FLAC__StreamMetadata *  object, const char *  field_name )

Remove first Vorbis comment matching the given field name. Parameters: object  A pointer to an existing VORBIS_COMMENT object. field_name  The field name of comment to delete. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT Return values: int  -1 for memory allocation error, 0 for no matching entries, 1 for one matching entry deleted.

int FLAC__metadata_object_vorbiscomment_remove_entries_matching (  FLAC__StreamMetadata *  object, const char *  field_name )

Remove all Vorbis comments matching the given field name. Parameters: object  A pointer to an existing VORBIS_COMMENT object. field_name  The field name of comments to delete. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT Return values: int  -1 for memory allocation error, 0 for no matching entries, else the number of matching entries deleted.

FLAC__StreamMetadata_CueSheet_Track* FLAC__metadata_object_cuesheet_track_new (   )

Create a new CUESHEET track instance. The object will be "empty"; i.e. values and data pointers will be 0. Return values: FLAC__StreamMetadata_CueSheet_Track*  NULL if there was an error allocating memory, else the new instance.

FLAC__StreamMetadata_CueSheet_Track* FLAC__metadata_object_cuesheet_track_clone (  const FLAC__StreamMetadata_CueSheet_Track *  object  )

Create a copy of an existing CUESHEET track object. The copy is a "deep" copy, i.e. dynamically allocated data within the object is also copied. The caller takes ownership of the new object and is responsible for freeing it with FLAC__metadata_object_cuesheet_track_delete(). Parameters: object  Pointer to object to copy. Assertions: object != NULL Return values: FLAC__StreamMetadata_CueSheet_Track*  NULL if there was an error allocating memory, else the new instance.

void FLAC__metadata_object_cuesheet_track_delete (  FLAC__StreamMetadata_CueSheet_Track *  object  )

Delete a CUESHEET track object Parameters: object  A pointer to an existing CUESHEET track object. Assertions: object != NULL

FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices (  FLAC__StreamMetadata *  object, unsigned  track_num, unsigned  new_num_indices )

Resize a track's index point array. If the size shrinks, elements will truncated; if it grows, new blank indices will be added to the end. Parameters: object  A pointer to an existing CUESHEET object. track_num  The index of the track to modify. NOTE: this is not necessarily the same as the track's number field. new_num_indices  The desired length of the array; may be 0. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks > track_num (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) || (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) Return values: FLAC__bool  false if memory allocation error, else true.

FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index (  FLAC__StreamMetadata *  object, unsigned  track_num, unsigned  index_num, FLAC__StreamMetadata_CueSheet_Index  index )

Insert an index point in a CUESHEET track at the given index. Parameters: object  A pointer to an existing CUESHEET object. track_num  The index of the track to modify. NOTE: this is not necessarily the same as the track's number field. index_num  The index into the track's index array at which to insert the index point. NOTE: this is not necessarily the same as the index point's number field. The indices at and after index_num move right one position. To append an index point to the end, set index_num to object->data.cue_sheet.tracks[track_num].num_indices . index  The index point to insert. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks > track_num object->data.cue_sheet.tracks[track_num].num_indices >= index_num Return values: FLAC__bool  false if realloc fails, else true.

FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index (  FLAC__StreamMetadata *  object, unsigned  track_num, unsigned  index_num )

Insert a blank index point in a CUESHEET track at the given index. A blank index point is one in which all field values are zero. Parameters: object  A pointer to an existing CUESHEET object. track_num  The index of the track to modify. NOTE: this is not necessarily the same as the track's number field. index_num  The index into the track's index array at which to insert the index point. NOTE: this is not necessarily the same as the index point's number field. The indices at and after index_num move right one position. To append an index point to the end, set index_num to object->data.cue_sheet.tracks[track_num].num_indices . Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks > track_num object->data.cue_sheet.tracks[track_num].num_indices >= index_num Return values: FLAC__bool  false if realloc fails, else true.

FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index (  FLAC__StreamMetadata *  object, unsigned  track_num, unsigned  index_num )

Delete an index point in a CUESHEET track at the given index. Parameters: object  A pointer to an existing CUESHEET object. track_num  The index into the track array of the track to modify. NOTE: this is not necessarily the same as the track's number field. index_num  The index into the track's index array of the index to delete. NOTE: this is not necessarily the same as the index's number field. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks > track_num object->data.cue_sheet.tracks[track_num].num_indices > index_num Return values: FLAC__bool  false if realloc fails, else true.

FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks (  FLAC__StreamMetadata *  object, unsigned  new_num_tracks )

Resize the track array. If the size shrinks, elements will truncated; if it grows, new blank tracks will be added to the end. Parameters: object  A pointer to an existing CUESHEET object. new_num_tracks  The desired length of the array; may be 0. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) || (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) Return values: FLAC__bool  false if memory allocation error, else true.

FLAC__bool FLAC__metadata_object_cuesheet_insert_track (  FLAC__StreamMetadata *  object, unsigned  track_num, FLAC__StreamMetadata_CueSheet_Track *  track, FLAC__bool  copy )

Sets a track in a CUESHEET block. If copy is true, a copy of the track is stored; otherwise, the object takes ownership of the track pointer. Returns false if copy == true and malloc fails. Parameters: object  A pointer to an existing CUESHEET object. track_num  Index into track array to set. NOTE: this is not necessarily the same as the track's number field. track  The track to set the track to. You may safely pass in a const pointer if copy is true. copy  See above. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET track_num < object->data.cue_sheet.num_tracks (track->indices != NULL && track->num_indices > 0) || (track->indices == NULL && track->num_indices == 0) \retval FLAC__bool \c false if \a copy is \c true and malloc fails, else \c true. */ FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks >= track_num Return values: FLAC__bool  false if copy is true and malloc fails, else true.

FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track (  FLAC__StreamMetadata *  object, unsigned  track_num )

Insert a blank track in a CUESHEET block at the given index. A blank track is one in which all field values are zero. Parameters: object  A pointer to an existing CUESHEET object. track_num  The index at which to insert the track. NOTE: this is not necessarily the same as the track's number field. The tracks at and after track_num move right one position. To append a track to the end, set track_num to object->data.cue_sheet.num_tracks . Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks >= track_num Return values: FLAC__bool  false if copy is true and malloc fails, else true.

FLAC__bool FLAC__metadata_object_cuesheet_delete_track (  FLAC__StreamMetadata *  object, unsigned  track_num )

Delete a track in a CUESHEET block at the given index. Parameters: object  A pointer to an existing CUESHEET object. track_num  The index into the track array of the track to delete. NOTE: this is not necessarily the same as the track's number field. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET object->data.cue_sheet.num_tracks > track_num Return values: FLAC__bool  false if realloc fails, else true.

FLAC__bool FLAC__metadata_object_cuesheet_is_legal (  const FLAC__StreamMetadata *  object, FLAC__bool  check_cd_da_subset, const char **  violation )

Check a cue sheet to see if it conforms to the FLAC specification. See the format specification for limits on the contents of the cue sheet. Parameters: object  A pointer to an existing CUESHEET object. check_cd_da_subset  If true, check CUESHEET against more stringent requirements for a CD-DA (audio) disc. violation  Address of a pointer to a string. If there is a violation, a pointer to a string explanation of the violation will be returned here. violation may be NULL if you don't need the returned string. Do not free the returned string; it will always point to static data. Assertions: object != NULL object->type == FLAC__METADATA_TYPE_CUESHEET Return values: FLAC__bool  false if cue sheet is illegal, else true.

---