Commit ad84a222 authored by Rémi Denis-Courmont's avatar Rémi Denis-Courmont

stream: improve documentation

parent f1ed338b
......@@ -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 */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment