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__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

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