viewpoint: add euler to 4x4 matrix conversion
[vlc.git] / 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.