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

[Julien 'Lta' BALLET]

From: Julien 'Lta' BALLET <contact at lta.io>

This commit also adds a related documentation file (doc/browsing.txt) describing
the expected behavior of pf_readdir callback implementations
---
 doc/browsing.txt     | 36 ++++++++++++++++++++++++++++++++++++
 include/vlc_access.h |  7 ++++---
 src/input/access.c   |  1 +
 3 files changed, 41 insertions(+), 3 deletions(-)
 create mode 100644 doc/browsing.txt

diff --git a/doc/browsing.txt b/doc/browsing.txt
new file mode 100644
index 0000000..ace8b4c
--- /dev/null
+++ b/doc/browsing.txt
@@ -0,0 +1,36 @@
+= 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 are calling pf_readdir
+  on. It CANNOT be NULL.
+* p_node: A pointer on an input_item_node_t that you must provide and you are
+  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 has been created for (psz_location field). It CANNOT be NULL.
+
+=== pf_readdir return values and behavior
+
+A call to pf_readdir can result in 3 behavior :
+
+* 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 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
+  different from VLC_SUCCESS or VLC_ENOITEM (eg. 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.
diff --git a/include/vlc_access.h b/include/vlc_access.h
index 511278a..e83d53f 100644
--- a/include/vlc_access.h
+++ b/include/vlc_access.h
@@ -88,10 +88,11 @@ struct access_t
      * (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 */
diff --git a/src/input/access.c b/src/input/access.c
index 850fccd..a9b2804 100644
--- a/src/input/access.c
+++ b/src/input/access.c
@@ -78,6 +78,7 @@ access_t *access_New( vlc_object_t *p_obj, input_thread_t *p_parent_input,
 
     p_access->pf_read    = NULL;
     p_access->pf_block   = NULL;
+    p_access->pf_readdir = NULL;
     p_access->pf_seek    = NULL;
     p_access->pf_control = NULL;
     p_access->p_sys      = NULL;
-- 
2.0.0