[vlc-commits] stream: improve documentation

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Tue Jul 19 23:40:46 2016 +0300| [ad84a22236b078bf342a47c097142dc96820b6ce] | committer: Rémi Denis-Courmont

stream: improve documentation

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=ad84a22236b078bf342a47c097142dc96820b6ce
---

 include/vlc_stream.h |   70 +++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 6 deletions(-)

diff --git a/include/vlc_stream.h b/include/vlc_stream.h
index cb0afbc..e8c1bc6 100644
--- a/include/vlc_stream.h
+++ b/include/vlc_stream.h
@@ -55,14 +55,72 @@ struct stream_t
     /* Stream source for stream filter */
     stream_t *p_source;
 
-    /* */
-    ssize_t     (*pf_read)(stream_t *, void *, size_t);
-    block_t *   (*pf_block)(stream_t *, bool *eof);
-    int         (*pf_readdir)( stream_t *, input_item_node_t * );
+    /**
+     * Read data.
+     *
+     * Callback to read data from the stream into a caller-supplied buffer.
+     *
+     * This may be NULL if the stream is actually a directory rather than a
+     * byte stream, or if \ref stream_t.pf_block is non-NULL.
+     *
+     * \param buf buffer to read data into
+     * \param len buffer length (in bytes)
+     *
+     * \retval -1 no data available yet
+     * \retval 0 end of stream (incl. fatal error)
+     * \retval positive number of bytes read (no more than len)
+     */
+    ssize_t     (*pf_read)(stream_t *, void *buf, size_t len);
+
+    /**
+     * Read data block.
+     *
+     * Callback to read a block of data. The data is read into a block of
+     * memory allocated by the stream. For some streams, data can be read more
+     * efficiently in block of a certain size, and/or using a custom allocator
+     * for buffers. In such case, this callback should be provided instead of
+     * \ref stream_t.pf_read; otherwise, this should be NULL.
+     *
+     * \param eof storage space for end-of-stream flag [OUT]
+     * (*eof is always false when invoking pf_block(); pf_block() should set
+     *  *eof to true if it detects the end of the stream)
+     *
+     * \return a data block,
+     * NULL if no data available yet, on error and at end-of-stream
+     */
+    block_t    *(*pf_block)(stream_t *, bool *eof);
+
+    /**
+     * Read directory.
+     *
+     * Callback to fill an item node from a directory
+     * (see doc/browsing.txt for details).
+     *
+     * NULL if the stream is not a directory.
+     */
+    int         (*pf_readdir)(stream_t *, input_item_node_t *);
+
+    /**
+     * Seek.
+     *
+     * Callback to set the stream pointer (in bytes from start).
+     *
+     * May be NULL if seeking is not supported.
+     */
     int         (*pf_seek)(stream_t *, uint64_t);
-    int         (*pf_control)( stream_t *, int i_query, va_list );
 
-    /* Private data for module */
+    /**
+     * Stream control.
+     *
+     * Cannot be NULL.
+     *
+     * \see stream_query_e
+     */
+    int         (*pf_control)(stream_t *, int i_query, va_list);
+
+    /**
+     * Private data pointer
+     */
     void *p_sys;
 
     /* Weak link to parent input */