[vlc-devel] [PATCH 1/7] Add a pf_readdir callback to access_t modules

[Edward Wang]

Documentation nitpicks:

On 2014-06-21 09:55, Julien 'Lta' BALLET <elthariel at gmail.com> wrote:
> += 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 with 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 you calling pf_readdir on.

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 you must provide and you are
> +  responsible for.

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 successfull

successful

> completion of this function, the
> +  node SHOULD contains

contain

> all the items present in the directory-like object

object that*

> +  the access has been created for (psz_location field).
> +
> +=== pf_readdir return values and behavior
> +
> +A call to pf_readdir can result in 3 behavior :

A call to pf_readdir has 3 possible results:

> +
> +* The call was successfull

successful

>   and the node has been filled with all the
> +  input_item_t possible depending on system state and module options. In that
> +  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

A recoverable error has occurred. The callback MUST return an error code

> +  different from VLC_SUCCESS or VLC_ENOITEM (eg. VLC_EGENERIC, VLC_ENOMEM, ...).
> +  Some input_item_t might have been added to the node, they are owned by the

Some input_item_t objects might have been added to the node; they are 
owned by the

> +  node which is owned by the node. This callback CAN be called again.