--- /dev/null
+= Directory-like browsing modules
+
+== Access modules
+
+Directory-like browsing is done in access modules providing a pf_readdir
+callback. The pf_readdir callback has a specified prototype and must
+match a specific expected behavior:
+
+=== pf_readdir prototype
+
+int (*pf_readdir)( access_t *p_access, input_item_node_t *p_node );
+
+* p_access: This is a pointer to the access_t object that you are
+ calling pf_readdir on. It CANNOT be NULL.
+* p_node: A pointer on an input_item_node_t that you must provide and be
+ responsible for. In particular, you have the responsibility to free it
+ in case of error. Upon successful completion of this function, the
+ node SHOULD contain all the items present in the directory-like object
+ that the access was created for (psz_location field). It CANNOT be
+ NULL.
+
+=== pf_readdir return values and behavior
+
+A call to pf_readdir has 3 possible results:
+
+* The call was successful and the node has been filled with all the
+ input_item_t possible depending on system state and module options. In this
+ case, pf_readdir MUST return VLC_SUCCESS and info.b_eof MUST be set to true.
+ This callback must NOT be called again.
+* An unrecoverable error has occured and no input_item_t was added to the node.
+ The callback returns a VLC_ENOITEM error code, and sets info.b_eof to true.
+ This error SHOULD be propagated by the calling code (stream/demux/...)
+ This callback must NOT be called again.
+* A recoverable error has occured. The callback MUST return an error code
+ that is not VLC_SUCCESS or VLC_ENOITEM (e.g. VLC_EGENERIC, VLC_ENOMEM, ...).
+ Some input_item_t objects might have been added to the node; they are
+ owned by the node which is owned by the access. This callback CAN be
+ called again.
* (if you fail, this value won't be reseted */
char *psz_demux;
- /* pf_read/pf_block is used to read data.
+ /* pf_read/pf_block/pf_readdir is used to read data.
* XXX A access should set one and only one of them */
- ssize_t (*pf_read) ( access_t *, uint8_t *, size_t ); /* Return -1 if no data yet, 0 if no more data, else real data read */
- block_t *(*pf_block)( access_t * ); /* return a block of data in his 'natural' size, NULL if not yet data or eof */
+ ssize_t (*pf_read) ( access_t *, uint8_t *, size_t ); /* Return -1 if no data yet, 0 if no more data, else real data read */
+ block_t *(*pf_block) ( access_t * ); /* Return a block of data in his 'natural' size, NULL if not yet data or eof */
+ int (*pf_readdir)( access_t *, input_item_node_t * );/* Fills the provided item_node, see doc/browsing.txt for details */
/* Called for each seek.
* XXX can be null */