claunia/flac
1
0
Fork 0
mirror of https://github.com/claunia/flac.git synced 2025-12-16 18:54:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

add vorbiscomment validation functions to format.c and test code; validate name part of vorbiscomment in metadata and metadata++ interfaces

Browse Source
This commit is contained in:
Josh Coalson
2004-12-30 03:41:19 +00:00
parent e40480d300
commit 2de1124e36
14 changed files with 466 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
include/FLAC++/metadata.h
View File

@@ -493,36 +493,37 @@ namespace FLAC {
*
* A \a field as used in the methods refers to an
* entire 'NAME=VALUE' string; for convenience the
* string is null-terminated. A length field is
* string is NUL-terminated. A length field is
* required in the unlikely event that the value
* contains contain embedded nulls.
* contains contain embedded NULs.
*
* A \a field_name is what is on the left side of the
* first '=' in the \a field. By definition it is ASCII
* and so is null-terminated and does not require a
* and so is NUL-terminated and does not require a
* length to describe it. \a field_name is undefined
* for a vendor string entry.
*
* A \a field_value is what is on the right side of the
* first '=' in the \a field. By definition, this may
* contain embedded nulls and so a \a field_value_length
* contain embedded NULs and so a \a field_value_length
* is required to describe it. However in practice,
* embedded nulls are not known to be used, so it is
* generally safe to treat field values as null-
* embedded NULs are not known to be used, so it is
* generally safe to treat field values as NUL-
* terminated UTF-8 strings.
*
* Always check is_valid() after the constructor or operator=
* to make sure memory was properly allocated.
* to make sure memory was properly allocated and that the
* Entry conforms to the Vorbis comment specification.
*/
class FLACPP_API Entry {
public:
Entry();
Entry(const char *field, unsigned field_length);
Entry(const char *field); // assumes \a field is null-terminated
Entry(const char *field); // assumes \a field is NUL-terminated
Entry(const char *field_name, const char *field_value, unsigned field_value_length);
Entry(const char *field_name, const char *field_value); // assumes \a field_value is null-terminated
Entry(const char *field_name, const char *field_value); // assumes \a field_value is NUL-terminated
Entry(const Entry &entry);
@@ -542,10 +543,10 @@ namespace FLAC {
const char *get_field_value() const;
bool set_field(const char *field, unsigned field_length);
bool set_field(const char *field); // assumes \a field is null-terminated
bool set_field(const char *field); // assumes \a field is NUL-terminated
bool set_field_name(const char *field_name);
bool set_field_value(const char *field_value, unsigned field_value_length);
bool set_field_value(const char *field_value); // assumes \a field_value is null-terminated
bool set_field_value(const char *field_value); // assumes \a field_value is NUL-terminated
protected:
bool is_valid_;
::FLAC__StreamMetadata_VorbisComment_Entry entry_;
@@ -560,9 +561,9 @@ namespace FLAC {
void clear_field_name();
void clear_field_value();
void construct(const char *field, unsigned field_length);
void construct(const char *field); // assumes \a field is null-terminated
void construct(const char *field); // assumes \a field is NUL-terminated
void construct(const char *field_name, const char *field_value, unsigned field_value_length);
void construct(const char *field_name, const char *field_value); // assumes \a field_value is null-terminated
void construct(const char *field_name, const char *field_value); // assumes \a field_value is NUL-terminated
void compose_field();
void parse_field();
};
@@ -607,12 +608,11 @@ namespace FLAC {
//@}
unsigned get_num_comments() const;
Entry get_vendor_string() const; // only the Entry's field name should be used
const FLAC__byte *get_vendor_string() const; // NUL-terminated UTF-8 string
Entry get_comment(unsigned index) const;
//! See FLAC__metadata_object_vorbiscomment_set_vendor_string()
//! \note Only the Entry's field name will be used.
bool set_vendor_string(const Entry &entry);
bool set_vendor_string(const FLAC__byte *string); // NUL-terminated UTF-8 string
//! See FLAC__metadata_object_vorbiscomment_set_comment()
bool set_comment(unsigned index, const Entry &entry);

47
include/FLAC/format.h
View File

@@ -747,7 +747,6 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bit
*
*****************************************************************************/
/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
/** Tests that a sample rate is valid for FLAC. Since the rules for valid
* sample rates are slightly complex, they are encapsulated in this function.
*
@@ -758,6 +757,52 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bit
*/
FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
/** Check a Vorbis comment entry name to see if it conforms to the Vorbis
* comment specification.
*
* Vorbis comment names must be composed only of characters from
* [0x20-0x3C,0x3E-0x7D].
*
* \param name A NUL-terminated string to be checked.
* \assert
* \code name != NULL \endcode
* \retval FLAC__bool
* \c false if entry name is illegal, else \c true.
*/
FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name);
/** Check a Vorbis comment entry value to see if it conforms to the Vorbis
* comment specification.
*
* Vorbis comment values must be valid UTF-8 sequences.
*
* \param value A string to be checked.
* \param length A the length of \a value in bytes. May be
* \c (unsigned)(-1) to indicate that \a value is a plain
* UTF-8 NUL-terminated string.
* \assert
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if entry name is illegal, else \c true.
*/
FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length);
/** Check a Vorbis comment entry to see if it conforms to the Vorbis
* comment specification.
*
* Vorbis comment entries must be of the form 'name=value', and 'name' and
* 'value' must be legal according to
* FLAC__format_vorbiscomment_entry_name_is_legal() and
* FLAC__format_vorbiscomment_entry_value_is_legal() respectively.
*
* \param value A string to be checked.
* \assert
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if entry name is illegal, else \c true.
*/
FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length);
/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
/** Check a seek table to see if it conforms to the FLAC specification.
* See the format specification for limits on the contents of the

39
include/FLAC/metadata.h
View File

@@ -1087,13 +1087,17 @@ FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_It
* FLAC__metadata_object_application_set_data(), you will get an assertion
* failure.
*
* The FLAC__metadata_object_vorbiscomment_*() functions for convenience
* For convenience the FLAC__metadata_object_vorbiscomment_*() functions
* maintain a trailing NUL on each Vorbis comment entry. This is not counted
* toward the length or stored in the stream, but it can make working with plain
* comments (those that don't contain embedded-NULs in the value) easier.
* Entries passed into these functions have trailing NULs added if missing, and
* returned entries are guaranteed to have a trailing NUL.
*
* The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis
* comment entry/name/value will first validate that it complies with the Vorbis
* comment specification and return false if it does not.
*
* 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.
@@ -1357,7 +1361,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMe
* \code (entry.entry != NULL && entry.length > 0) ||
* (entry.entry == NULL && entry.length == 0) \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
* \c false if memory allocation fails or \a entry does not comply with the
* Vorbis comment specification, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
@@ -1374,7 +1379,7 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__
* \code (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) \endcode
* \retval FLAC__bool
* \c false if memory allocation error, else \c true.
* \c false if memory allocation fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
@@ -1400,7 +1405,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__St
* \code (entry.entry != NULL && entry.length > 0) ||
* (entry.entry == NULL && entry.length == 0) \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
* \c false if memory allocation fails or \a entry does not comply with the
* Vorbis comment specification, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
@@ -1429,7 +1435,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__Stream
* \code (entry.entry != NULL && entry.length > 0) ||
* (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
* \c false if memory allocation fails or \a entry does not comply with the
* Vorbis comment specification, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
@@ -1453,7 +1460,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__Str
* \code (entry.entry != NULL && entry.length > 0) ||
* (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
* \c false if memory allocation fails or \a entry does not comply with the
* Vorbis comment specification, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
@@ -1487,7 +1495,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__Str
* \code (entry.entry != NULL && entry.length > 0) ||
* (entry.entry == NULL && entry.length == 0 && copy == false) \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
* \c false if memory allocation fails or \a entry does not comply with the
* Vorbis comment specification, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy);
@@ -1513,14 +1522,15 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__Str
* \param entry A pointer to a Vorbis comment entry. The entry's
* \c entry pointer should not point to allocated
* memory as it will be overwritten.
* \param field_name The field name in ASCII, \c NULL terminated.
* \param field_value The field value in UTF-8, \c NULL terminated.
* \param field_name The field name in ASCII, \c NUL terminated.
* \param field_value The field value in UTF-8, \c NUL terminated.
* \assert
* \code entry != NULL \endcode
* \code field_name != NULL \endcode
* \code field_value != NULL \endcode
* \retval FLAC__bool
* \c false if malloc() fails, else \c true.
* \c false if malloc() fails, or if \a field_name or \a field_value does
* not comply with the Vorbis comment specification, else \c true.
*/
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);
@@ -1529,7 +1539,7 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pa
* The returned pointers to name and value will be allocated by malloc()
* and shall be owned by the caller.
*
* \param entry A pointer to an existing Vorbis comment entry.
* \param entry An existing Vorbis comment entry.
* \param field_name The address of where the returned pointer to the
* field name will be stored.
* \param field_value The address of where the returned pointer to the
@@ -1540,17 +1550,18 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pa
* \code field_name != NULL \endcode
* \code field_value != NULL \endcode
* \retval FLAC__bool
* \c false if malloc() fails, else \c true.
* \c false if memory allocation fails or \a entry does not comply with the
* Vorbis comment specification, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value);
/** Check if the given Vorbis comment entry's field name matches the given
* field name.
*
* \param entry A pointer to an existing Vorbis comment entry.
* \param entry An existing Vorbis comment entry.
* \param field_name The field name to check.
* \param field_name_length The length of \a field_name, not including the
* terminating \c NULL.
* terminating \c NUL.
* \assert
* \code (entry.entry != NULL && entry.length > 0) \endcode
* \retval FLAC__bool