ogg: Improve documentation of struct ogg_afh_callback_info.

[paraslash.git] / ogg_afh_common.h

diff --git a/ogg_afh_common.h b/ogg_afh_common.h
index 89c8268b1fa0335bf98675c89135a7d1531a9630..47e133bfcf61c15542c9133b61e113ebdce335f8 100644 (file)
--- a/ogg_afh_common.h
+++ b/ogg_afh_common.h
@@ -1,5 +1,5 @@
 /*
 /*

- * Copyright (C) 2010-2011 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2010 Andre Noll <maan@tuebingen.mpg.de>

  *
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
  *
  * Licensed under the GPL v2. For licencing details see COPYING.
  */


@@ -10,22 +10,26 @@
  */
 
 /**
  */
 
 /**

- * 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 {
        /**
  */
 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);
        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;
 };
 
        void *private_data;
 };