fix doxygen comment of the init functions of all audio format handlers.

[paraslash.git] / afh.h

diff --git a/afh.h b/afh.h
index 0ead11e0e997879a6e4ed98cc05770871cb3917f..69c1188ed75d294ddfc417567b7bd50967692e85 100644 (file)
--- a/afh.h
+++ b/afh.h
@@ -41,6 +41,39 @@
 
 /** \endcond */
 
+/** size of the  audio_file info string */
+#define AUDIO_FILE_INFO_SIZE 16384
+
+struct audio_format_info {
+       /** the number of chunks this audio file contains */
+       long unsigned chunks_total;
+       /** the length of the audio file in seconds */
+       int seconds_total;
+       /** a string that gets filled in by the audio format handler */
+       char info_string[AUDIO_FILE_INFO_SIZE];
+       /**
+        * the table that specifies the offset of the individual pieces in
+        * the current audio file.
+        */
+       size_t *chunk_table;
+       /** period of time between sending data chunks */
+       struct timeval chunk_tv;
+       /** end of file timeout - do not load new audio file until this time */
+       struct timeval eof_tv;
+       /**
+        * optional audio file header
+        *
+        * This is read from a sender in case a new client connects in the
+        * middle of the stream.  The audio format handler does not need to set
+        * this if the audio format does not need any special header treatment.
+        * If non-NULL, it must point to a buffer holding the current audio
+        * file header.
+        */
+       char *header;
+       /* the length of the header, ignored if \a header is \p NULL */
+       unsigned header_len;
+};
+
 /**
  * structure for audio format handling
  *
@@ -64,54 +97,17 @@ struct audio_format_handler {
         * Must initialize all function pointers and is assumed to succeed.
         */
        void (*init)(struct audio_format_handler*);
-       /**
-        * period of time between sending data chunks
-       */
-       struct timeval chunk_tv; /* length of one chunk of data */
-       /**
-        * end of file timeout - do not load new audio file until this time
-        *
-       */
-       struct timeval eof_tv; /* timeout on eof */
-       /**
-        * Pointer to the optional get-header function.
-        *
-        * This is called from a sender in case a new client connects in the middle of
-        * the stream.  The audio format handler may set this to NULL to indicate that
-        * this audio format does not need any special header treatment.  If non-NULL,
-        * the function it points to must return a pointer to a buffer holding the
-        * current audio file header, together with the header length.
-       */
-       char *(*get_header_info)(int *header_len);
        /**
         * check if this audio format handler can handle the file
         *
-        * This is a  pointer to a function returning whether a given file is valid for
-        * this audio format. A negative return value indicates that this audio format
-        * handler did not recognize the given file. On success, the function is
-        * expected to return a positive value and to fill in \arg info_str, \arg
-        * chunks and \arg seconds appropriately.
-       */
-       int (*get_file_info)(FILE *audio_file, char *info_str,
-               long unsigned *chunks, int *seconds);
-       /**
-        * cleanup function of this audio format handler
+        * This is a  pointer to a function returning whether a given file is
+        * valid for this audio format. A negative return value indicates that
+        * this audio format handler did not recognize the given file. On
+        * success, the function must return a positive value and fill in the
+        * given struct audio_format_info.
         *
-        * This close function should deallocate any resources
-        * associated with the current audio file. In particular, it is responsible
-        * for closing the file handle. It is assumed to succeed.
+        * \sa struct audio_format_info
        */
-       void (*close_audio_file)(void);
-       /**
-        * function responsible for reading one data chunk.
-        *
-        * \a read_chunk() must return a pointer to the next chunk of data that should
-        * be sent out, or \p NULL on errors or if the end of the file was encountered.
-        *
-        * If it returns non-NULL, \a len must contain the length of the returned
-        * buffer (which may be zero if nothing has to be sent for some reason).
-        * Otherwise, \a len is used to distinguish between the eof and the error case:
-        * It must be zero in the eof case, or negative if an error occcured.
-       */
-       char * (*read_chunk)(long unsigned chunk_num, ssize_t *len);
+       int (*get_file_info)(FILE *audio_file, struct audio_format_info *afi);
 };
+