Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members File Members
This module contains methods for manipulating FLAC metadata objects.
More...
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) |
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
|
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:
-
|
|
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:
-
-
Return values:
-
|
|
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:
-
|
|
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:
-
-
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:
-
(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->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 . |
|
|
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->data.seek_table.num_points > point_num
|
|
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->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->data.seek_table.num_points > point_num
-
Return values:
-
FLAC__bool |
false if memory allocation error, else true . |
|
|
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:
-
-
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:
-
-
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:
-
-
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:
-
-
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:
-
-
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:
-
-
Return values:
-
FLAC__bool |
false if realloc fails, else true . |
|
|
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:
-
(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->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 . |
|
|
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:
-
(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 . |
|
|
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->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->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:54:30 2002 for FLAC by
1.2.14 written by Dimitri van Heesch,
© 1997-2002