ogg: Improve documentation of struct ogg_afh_callback_info.
authorAndre Noll <maan@systemlinux.org>
Wed, 25 Jun 2014 22:11:31 +0000 (00:11 +0200)
committerAndre Noll <maan@tuebingen.mpg.de>
Sun, 18 Jan 2015 14:40:47 +0000 (15:40 +0100)
Explain how the possible return values from the callback handler relate
to the header chunk. Also avoid to speak about vorbis and speex,
as the callbacks are also used by the opus audio format handler and
could in theory be used by any codec.

ogg_afh_common.h

index 09870a9..47e133b 100644 (file)
  */
 
 /**
- * Callback structure provided by vorbis/speex audio format handlers.
+ * Callback structure provided by audio format handlers.
  *
- * Both audio formats utilize the ogg container format. Meta info about
- * the audio file is contained in the first three ogg packets.
+ * All audio formats which utilize the ogg container format define a callback
+ * function whose purpose is to extract the meta information about the audio
+ * file from the first few ogg packets of the bitstream.
  */
 struct ogg_afh_callback_info {
        /**
-         * ogg_get_file_info() calls this function for each of the three
-         * header packets. If this callback returns a negative value, the
-         * audio file is considered invalid and the chunk table is not
-         * created. If it returns zero, the end of the header has been
-         * reached and no further ogg packets should be processed.
-         */
+        * ogg_get_file_info() calls this function for the first three ogg
+        * packets, or until the callback returns a non-positive value. If it
+        * returns negative, the audio file was not recognized by the audio
+        * format handler. If it returns zero, the audio file is considered
+        * valid, and no further processing by the callback is needed. In this
+        * case the header chunk, i.e. chunk number zero, is defined as the
+        * concatenation of all packets that have been processed by the
+        * callback.
+        */
        int (*packet_callback)(ogg_packet *packet, int packet_num,
                int serial, struct afh_info *afhi, void *private_data);
-       /** Vorbis/speex specific data. */
+       /** Data specific to the audio format handler. */
        void *private_data;
 };