diff avio.h @ 1874:3328f652d741 libavformat

Move aviobuf.c comments to avio.h. By moving the aviobuf.c comments to avio.h, these comments can be extracted by Doxygen by only accessing the installed headers.

--- a/avio.h	Mon Mar 05 13:54:15 2007 +0000
+++ b/avio.h	Mon Mar 05 13:55:45 2007 +0000
@@ -146,18 +146,27 @@
 int url_ferror(ByteIOContext *s);
 
 #define URL_EOF (-1)
+/* NOTE: return URL_EOF (-1) if EOF */
 int url_fgetc(ByteIOContext *s);
+
+/* XXX: currently size is limited */
 #ifdef __GNUC__
 int url_fprintf(ByteIOContext *s, const char *fmt, ...) __attribute__ ((__format__ (__printf__, 2, 3)));
 #else
 int url_fprintf(ByteIOContext *s, const char *fmt, ...);
 #endif
+
+/* note: unlike fgets, the EOL character is not returned and a whole
+   line is parsed. return NULL if first char read was EOF */
 char *url_fgets(ByteIOContext *s, char *buf, int buf_size);
 
 void put_flush_packet(ByteIOContext *s);
 
 int get_buffer(ByteIOContext *s, unsigned char *buf, int size);
 int get_partial_buffer(ByteIOContext *s, unsigned char *buf, int size);
+
+/* NOTE: return 0 if EOF, so you cannot use it if EOF handling is
+   necessary */
 int get_byte(ByteIOContext *s);
 unsigned int get_le24(ByteIOContext *s);
 unsigned int get_le32(ByteIOContext *s);
@@ -176,17 +185,57 @@
 }
 
 int url_fdopen(ByteIOContext *s, URLContext *h);
+
+/* XXX: must be called before any I/O */
 int url_setbufsize(ByteIOContext *s, int buf_size);
+
+/* NOTE: when opened as read/write, the buffers are only used for
+   reading */
 int url_fopen(ByteIOContext *s, const char *filename, int flags);
 int url_fclose(ByteIOContext *s);
 URLContext *url_fileno(ByteIOContext *s);
+
+/*
+ * Return the maximum packet size associated to packetized buffered file
+ * handle. If the file is not packetized (stream like http or file on
+ * disk), then 0 is returned.
+ *
+ * @param h buffered file handle
+ * @return maximum packet size in bytes
+ */
 int url_fget_max_packet_size(ByteIOContext *s);
 
 int url_open_buf(ByteIOContext *s, uint8_t *buf, int buf_size, int flags);
+
+/* return the written or read size */
 int url_close_buf(ByteIOContext *s);
 
+/*
+ * Open a write only memory stream.
+ *
+ * @param s new IO context
+ * @return zero if no error.
+ */
 int url_open_dyn_buf(ByteIOContext *s);
+
+/*
+ * Open a write only packetized memory stream with a maximum packet
+ * size of 'max_packet_size'.  The stream is stored in a memory buffer
+ * with a big endian 4 byte header giving the packet size in bytes.
+ *
+ * @param s new IO context
+ * @param max_packet_size maximum packet size (must be > 0)
+ * @return zero if no error.
+ */
 int url_open_dyn_packet_buf(ByteIOContext *s, int max_packet_size);
+
+/*
+ * Return the written size and a pointer to the buffer. The buffer
+ *  must be freed with av_free().
+ * @param s IO context
+ * @param pointer to a byte buffer
+ * @return the length of the byte buffer
+ */
 int url_close_dyn_buf(ByteIOContext *s, uint8_t **pbuffer);
 
 unsigned long get_checksum(ByteIOContext *s);