[cvs-annodex] commit (libfishsound):
trunk/include/fishsound/fishsound.h
+trunk/include/fishsound/comments.h
conrad
nobody at lists.annodex.net
Wed May 5 21:55:58 EST 2004
Update of /annodex/libfishsound (new revision 69)
Added files:
trunk/include/fishsound/comments.h
Modified files:
trunk/include/fishsound/fishsound.h
Log Message:
Added <fishsound/comments.h>, updated fishsound.h to reference it.
Added: trunk/include/fishsound/comments.h
===================================================================
--- trunk/include/fishsound/comments.h 2004-05-05 10:17:08 UTC (rev 68)
+++ trunk/include/fishsound/comments.h 2004-05-05 11:55:58 UTC (rev 69)
@@ -0,0 +1,212 @@
+
+/*
+ Copyright (C) 2003 Commonwealth Scientific and Industrial Research
+ Organisation (CSIRO) Australia
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ - Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ - 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 CSIRO Australia 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 ORGANISATION 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 __FISH_SOUND_COMMENT_H__
+#define __FISH_SOUND_COMMENT_H__
+
+/** \file
+ * Encoding and decoding of comments.
+ *
+ * Vorbis and Speex bitstreams
+ * use a comment format called "Vorbiscomment", defined
+ * <a href="http://www.xiph.org/ogg/vorbis/doc/v-comment.html">here</a>.
+ * Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are
+ * defined in that document.
+ *
+ * The following general features of Vorbiscomment are relevant to this API:
+ * - Each stream has one comment packet, which occurs before any encoded
+ * audio data in the stream.
+ * - When encoding, FishSound will generate the comment block and pass it
+ * to the encoded() callback in sequence, just like any other packet.
+ * Hence, all comments must be set before any call to fish_sound_encode().
+ * - When decoding, FishSound will decode the comment block before calling
+ * the first decoded() callback. Hence, retrieving comment data is possible
+ * from as soon as the decoded() callback is first called.
+ *
+ * Each comment block contains one Vendor string, which can be retrieved
+ * with fish_sound_comment_get_vendor(). When encoding, this string is
+ * effectively fixed by the codec libraries; it cannot be set by the
+ * application.
+ *
+ * The rest of a comment block consists of \a name = \a value pairs, with
+ * the following restrictions:
+ * - Both the \a name and \a value must be non-empty
+ * - The \a name is case-insensitive and must consist of ASCII within the
+ * range 0x20 to 0x7D inclusive, 0x3D ('=') excluded.
+ * - The \a name is not unique; multiple entries may exist with equivalent
+ * \a name within a Vorbiscomment block.
+ * - The \a value may be any UTF-8 string.
+ *
+ * \section comments_get Retrieving comments
+ *
+ * FishSound contains API methods to iterate through all comments associated
+ * with a FishSound* handle (fish_sound_comment_first() and
+ * fish_sound_comment_next(), and to iterate through comments matching a
+ * particular name (fish_sound_comment_first_byname() and
+ * fish_sound_comment_next_byname()). Given that multiple comments may exist
+ * with the same \a name, you should not use
+ * fish_sound_comment_first_byname() as a simple "get" function.
+ *
+ * \section comments_set Encoding comments
+ *
+ * For encoding, FishSound contains API methods for adding comments
+ * (fish_sound_comment_add() and fish_sound_comment_add_byname()
+ * and for removing comments
+ * (fish_sound_comment_remove() and fish_sound_comment_remove_byname()).
+ */
+
+#include <fishsound/fishsound.h>
+
+/**
+ * A comment.
+ */
+typedef struct {
+ /** The name of the comment, eg. "AUTHOR" */
+ char * name;
+
+ /** The value of the comment, as UTF-8 */
+ char * value;
+} FishSoundComment;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Retrieve the vendor string.
+ * \param fsound A FishSound* handle
+ * \returns A read-only copy of the vendor string
+ * \retval NULL No vendor string is associated with \a fsound,
+ * or \a fsound is NULL.
+ */
+const char *
+fish_sound_comment_get_vendor (FishSound * fsound);
+
+
+/**
+ * Retrieve the first comment.
+ * \param fsound A FishSound* handle
+ * \returns A read-only copy of the first comment, or NULL if no comments
+ * exist for this FishSound* object.
+ */
+const FishSoundComment *
+fish_sound_comment_first (FishSound * fsound);
+
+/**
+ * Retrieve the next comment.
+ * \param fsound A FishSound* handle
+ * \param comment The previous comment.
+ * \returns A read-only copy of the comment immediately following the given
+ * comment.
+ */
+const FishSoundComment *
+fish_sound_comment_next (FishSound * fsound, const FishSoundComment * comment);
+
+/**
+ * Retrieve the first comment with a given name.
+ * \param fsound A FishSound* handle
+ * \param name the name of the comment to retrieve.
+ * \returns A read-only copy of the first comment matching the given \a name.
+ * \retval NULL no match was found.
+ * \note If \a name is NULL, the behaviour is the same as for
+ * fish_sound_comment_first()
+ */
+const FishSoundComment *
+fish_sound_comment_first_byname (FishSound * fsound, char * name);
+
+/**
+ * Retrieve the next comment following and with the same name as a given
+ * comment.
+ * \param fsound A FishSound* handle
+ * \param comment A comment
+ * \returns A read-only copy of the next comment with the same name as
+ * \a comment.
+ * \retval NULL no further comments with the same name exist for
+ * this FishSound* object.
+ */
+const FishSoundComment *
+fish_sound_comment_next_byname (FishSound * fsound,
+ const FishSoundComment * comment);
+
+/**
+ * Add a comment
+ * \param fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
+ * \param comment The comment to add
+ * \retval 0 Success
+ * \retval FISH_SOUND_ERR_BAD \a fsound is not a valid FishSound* handle
+ * \retval FISH_SOUND_ERR_INVALID Operation not suitable for this FishSound
+ */
+int
+fish_sound_comment_add (FishSound * fsound, FishSoundComment * comment);
+
+/**
+ * Add a comment by name and value.
+ * \param fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
+ * \param name The name of the comment to add
+ * \param value The contents of the comment to add
+ * \retval 0 Success
+ * \retval FISH_SOUND_ERR_BAD \a fsound is not a valid FishSound* handle
+ * \retval FISH_SOUND_ERR_INVALID Operation not suitable for this FishSound
+ */
+int
+fish_sound_comment_add_byname (FishSound * fsound, const char * name,
+ const char * value);
+
+/**
+ * Remove a comment
+ * \param fsound A FishSound* handle (created with FISH_SOUND_ENCODE)
+ * \param comment The comment to remove.
+ * \retval 1 Success: comment removed
+ * \retval 0 No-op: comment not found, nothing to remove
+ * \retval FISH_SOUND_ERR_BAD \a fsound is not a valid FishSound* handle
+ * \retval FISH_SOUND_ERR_INVALID Operation not suitable for this FishSound
+ */
+int
+fish_sound_comment_remove (FishSound * fsound, FishSoundComment * comment);
+
+/**
+ * Remove all comments with a given name.
+ * \param fsound A FishSound* handle (created with FISH_SOUND_ENCODE)
+ * \param name The name of the comments to remove
+ * \retval ">= 0" The number of comments removed
+ * \retval FISH_SOUND_ERR_BAD \a fsound is not a valid FishSound* handle
+ * \retval FISH_SOUND_ERR_INVALID Operation not suitable for this FishSound
+ */
+int
+fish_sound_comment_remove_byname (FishSound * fsound, char * name);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __FISH_SOUND_COMMENTS_H__ */
Modified: trunk/include/fishsound/fishsound.h
===================================================================
--- trunk/include/fishsound/fishsound.h 2004-05-05 10:17:08 UTC (rev 68)
+++ trunk/include/fishsound/fishsound.h 2004-05-05 11:55:58 UTC (rev 69)
@@ -62,6 +62,10 @@
* - \link fishsound.h fishsound.h \endlink:
* Documentation of the FishSound API.
*
+ * - \link comments.h Handling comments \endlink:
+ * How to add and retrieve \a name = \a value metadata in Vorbis and Speex
+ * streams.
+ *
* - \link decode Decoding audio data \endlink:
* How to decode audio data with FishSound, including source for a fully
* working Ogg Vorbis and Ogg Speex decoder.
--
conrad
More information about the cvs-annodex
mailing list