remove window profiling field
[flac.git] / include / FLAC / format.h
index 4b4a68d..de9f6ea 100644 (file)
@@ -1,20 +1,32 @@
 /* libFLAC - Free Lossless Audio Codec library
- * Copyright (C) 2000,2001,2002  Josh Coalson
+ * Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
  *
- * This library is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Library General Public
- * License as published by the Free Software Foundation; either
- * version 2 of the License, or (at your option) any later version.
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
  *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Library General Public License for more details.
+ * - Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
  *
- * You should have received a copy of the GNU Library General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA  02111-1307, USA.
+ * - Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * - Neither the name of the Xiph.org Foundation nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef FLAC__FORMAT_H
@@ -76,6 +88,9 @@ extern "C" {
        format specification.  There is nothing to tune here.
 */
 
+/** The largest legal metadata type code. */
+#define FLAC__MAX_METADATA_TYPE_CODE (126u)
+
 /** The minimum block size, in samples, permitted by the format. */
 #define FLAC__MIN_BLOCK_SIZE (16u)
 
@@ -138,7 +153,7 @@ extern "C" {
 extern FLAC_API const char *FLAC__VERSION_STRING;
 
 /** The vendor string inserted by the encoder into the VORBIS_COMMENT block.
- *  This is a nulL-terminated ASCII string; when inserted into the
+ *  This is a NUL-terminated ASCII string; when inserted into the
  *  VORBIS_COMMENT the trailing null is stripped.
  */
 extern FLAC_API const char *FLAC__VENDOR_STRING;
@@ -458,16 +473,13 @@ typedef enum {
        /**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */
 
        FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
-       /**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block */
+       /**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */
 
        FLAC__METADATA_TYPE_CUESHEET = 5,
        /**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */
 
        FLAC__METADATA_TYPE_UNDEFINED = 6
-       /**< <A HREF="../format.html#metadata_block_cuesheet">marker to denote
-        * beginning of undefined type range; this number will increase as new
-        * metadata types are added</A> block
-        */
+       /**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
 
 } FLAC__MetadataType;
 
@@ -571,6 +583,10 @@ typedef struct {
 
 
 /** Vorbis comment entry structure used in VORBIS_COMMENT blocks.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
+ *
+ *  For convenience, the APIs maintain a trailing NUL character at the end of
+ *  \a entry which is not counted toward \a length, i.e.
+ *  \code strlen(entry) == length \endcode
  */
 typedef struct {
        FLAC__uint32 length;
@@ -591,56 +607,51 @@ typedef struct {
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */
 
 
-/** XXX.  (c.f. <A HREF="../format.html#XXX">format specification</A>)
+/** FLAC CUESHEET track index structure.  (See the
+ * <A HREF="../format.html#cuesheet_track_index">format specification</A> for
+ * the full description of each field.)
  */
 typedef struct {
        FLAC__uint64 offset;
-       /**< The index offset from the beginning of the track, in samples.
-        * For CD-DA, the offset must be evenly divisible by 588 samples (588
-        * samples = 44100 samples/sec * 1/75th of a sec)
+       /**< Offset in samples, relative to the track offset, of the index
+        * point.
         */
 
        FLAC__byte number;
-       /**< The index number.  For CD-DA, an index number of 0 corresponds
-        * to the track pregap.  There must be at least one index in a track.
-        * The first index in a track must be 0 or 1 and subsequently index
-        * numbers must increase by 1.
-        */
+       /**< The index point number. */
 } FLAC__StreamMetadata_CueSheet_Index;
 
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */
-extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == @@@@3*8 (bits) */
+extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */
 
 
-/** XXX.  (c.f. <A HREF="../format.html#XXX">format specification</A>)
+/** FLAC CUESHEET track structure.  (See the
+ * <A HREF="../format.html#cuesheet_track">format specification</A> for
+ * the full description of each field.)
  */
 typedef struct {
        FLAC__uint64 offset;
-       /**< The track offset from the beginning of the audio data, in samples.
-        * This track offset is the offset to the first index point of the
-        * track.  Note that for CD-DA, the track's offset in the TOC is that
-        * of the track's INDEX 01 even if there is an INDEX 00.
-        *
-        * For CD-DA, the offset must be evenly divisible by 588 samples (588
-        * samples = 44100 samples/sec * 1/75th of a sec)
-        */
+       /**< Track offset in samples, relative to the beginning of the FLAC audio stream. */
 
        FLAC__byte number;
-       /**< The track number.  A track number of 0 is not allowed to avoid
-        * conflicting with the CD-DA spec, which reserves this for the
-        * lead-in. For CD-DA the number must be 1-99, or 170 for the lead-out.
-        * It is not required but encouraged to start with track 1 and increase
-        * sequentially.  A CUESHEET block is required to have a lead-out
-        * track; it is always the last track in the cuesheet and the number
-        * must be 170 for CD-DA.
-        */
+       /**< The track number. */
+
+       char isrc[13];
+       /**< Track ISRC.  This is a 12-digit alphanumeric code plus a trailing '\0' */
+
+       unsigned type:1;
+       /**< The track type: 0 for audio, 1 for non-audio. */
+
+       unsigned pre_emphasis:1;
+       /**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */
 
-       char isrc[13]; /*@@@@ 12 ascii characters plus trailing '\0' */
-       unsigned type:1;                        /*@@@@q-channel control bit 3: 0=>audio, 1=>data (undefined for CD-DA, defined for CDROM) */
-       unsigned pre_emphasis:1;        /*@@@@q-channel control bit 5: 0=>no pre-em, 1=>pre-em */
        FLAC__byte num_indices;
+       /**< The number of track index points. */
+
        FLAC__StreamMetadata_CueSheet_Index *indices;
+       /**< NULL if num_indices == 0, else pointer to array of index points. */
+
 } FLAC__StreamMetadata_CueSheet_Track;
 
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */
@@ -648,30 +659,58 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN;
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */
-extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+@@@@12*8 (bits) */
+extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */
 
 
-/** FLAC CUESHEET structure.  (c.f. <A HREF="../format.html#metadata_block_cuesheet">format specification</A>)
+/** FLAC CUESHEET structure.  (See the
+ * <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
+ * for the full description of each field.)
  */
 typedef struct {
-       char media_catalog_number[129]; /*@@@@ in the stream, the media_catalog_number will be 128 alphanumberic ascii characters; unused digits are padded out to the right with null characters.  in memory, the 129th character will be guaranteed to be a null character so that the whole string is always a valid C string.  CD-DA: 13 ascii digits ('0'-'9') plus 116 trailing '\0' characters */
-       FLAC__uint64 lead_in;   /*@@@@ length of lead-in in samples; required to compute some versions of CD TOC hashes; CD-DA says the lead-in must be digital silence and rippers don't save it by convention, so TRACK 00 is disallowed and instead we store only the length.  The lead-in is the number of samples up to the first index point of the first track, \b not INDEX 01 of the first track.  This is so applications can correctly compute a CD-DA TOC equivalent even when there is TRACK 01 INDEX 00 data. */
+       char media_catalog_number[129];
+       /**< Media catalog number, in ASCII printable characters 0x20-0x7e.  In
+        * general, the media catalog number may be 0 to 128 bytes long; any
+        * unused characters should be right-padded with NUL characters.
+        */
+
+       FLAC__uint64 lead_in;
+       /**< The number of lead-in samples. */
+
+       FLAC__bool is_cd;
+       /**< \c true if CUESHEET corresponds to a Compact Disc, else \c false */
+
        unsigned num_tracks;
+       /**< The number of tracks. */
+
        FLAC__StreamMetadata_CueSheet_Track *tracks;
+       /**< NULL if num_tracks == 0, else pointer to array of tracks. */
+
 } FLAC__StreamMetadata_CueSheet;
 
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */
+extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */
+extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */
 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */
 
 
+/** Structure that is used when a metadata block of unknown type is loaded.
+ *  The contents are opaque.  The structure is used only internally to
+ *  correctly handle unknown metadata.
+ */
+typedef struct {
+       FLAC__byte *data;
+} FLAC__StreamMetadata_Unknown;
+
+
 /** FLAC metadata block structure.  (c.f. <A HREF="../format.html#metadata_block">format specification</A>)
  */
 typedef struct {
        FLAC__MetadataType type;
        /**< The type of the metadata block; used determine which member of the
-        * \a data union to dereference. */
+        * \a data union to dereference.  If type >= FLAC__METADATA_TYPE_UNDEFINED
+        * then \a data.unknown must be used. */
 
        FLAC__bool is_last;
        /**< \c true if this metadata block is the last, else \a false */
@@ -686,6 +725,7 @@ typedef struct {
                FLAC__StreamMetadata_SeekTable seek_table;
                FLAC__StreamMetadata_VorbisComment vorbis_comment;
                FLAC__StreamMetadata_CueSheet cue_sheet;
+               FLAC__StreamMetadata_Unknown unknown;
        } data;
        /**< Polymorphic block data; use the \a type value to determine which
         * to use. */
@@ -717,6 +757,53 @@ 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
  *  seek table.
@@ -729,6 +816,7 @@ FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
  */
 FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
 
+/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
 /** Sort a seek table's seek points according to the format specification.
  *  This includes a "unique-ification" step to remove duplicates, i.e.
  *  seek points with identical \a sample_number values.  Duplicate seek
@@ -743,7 +831,7 @@ FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_S
  */
 FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
 
-/*@@@@ add to unit tests */
+/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
 /** 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.