doc/browsing.txt

   1 = Directory-like browsing modules
   2
   3 == Access modules
   4
   5 Directory-like browsing is done in access modules providing a pf_readdir
   6 callback. The pf_readdir callback has a specified prototype and must
   7 match a specific expected behavior:
   8
   9 === pf_readdir prototype
  10
  11 int (*pf_readdir)( stream_t *p_access, input_item_node_t *p_node );
  12
  13 * p_access: This is a pointer to the stream_t object that you are
  14   calling pf_readdir on. It CANNOT be NULL.
  15 * p_node: A pointer on an input_item_node_t that you must provide and be
  16   responsible for. In particular, you have the responsibility to free it
  17   in case of error. Upon successful completion of this function, the
  18   node SHOULD contain all the items present in the directory-like object
  19   that the access was created for (psz_location field). It CANNOT be
  20   NULL.
  21
  22 === pf_readdir return values and behavior
  23
  24 A call to pf_readdir has 3 possible results:
  25
  26 * The call was successful and the node has been filled with all the
  27   input_item_t possible depending on system state and module options. In this
  28   case, pf_readdir MUST return VLC_SUCCESS and info.b_eof MUST be set to true.
  29   This callback must NOT be called again.
  30 * An unrecoverable error has occurred and no input_item_t was added to the node.
  31   The callback returns a VLC_ENOITEM error code, and sets info.b_eof to true.
  32   This error SHOULD be propagated by the calling code (stream/demux/...)
  33   This callback must NOT be called again.
  34 * A recoverable error has occurred. The callback MUST return an error code
  35   that is not VLC_SUCCESS or VLC_ENOITEM (e.g. VLC_EGENERIC, VLC_ENOMEM, ...).
  36   Some input_item_t objects might have been added to the node; they are
  37   owned by the node which is owned by the access. This callback CAN be
  38   called again.