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

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

This module contains methods for manipulating FLAC metadata objects. More...

Functions

FLAC__StreamMetadataFLAC__metadata_object_new (FLAC__MetadataType type)
FLAC__StreamMetadataFLAC__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)

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.


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.

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 
(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->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->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->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->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 
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 
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 
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 
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 
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 
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 
(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->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 
(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->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.

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 of the comment to delete.
Assertions:
object != NULL 
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.


Generated on Tue Sep 24 21:17:44 2002 for FLAC by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002