On Wed, Apr 8, 2015 at 8:15 PM, Michael Niedermayer <michae...@gmx.at>
wrote:
> On Wed, Apr 08, 2015 at 07:58:19PM +0200, Mariusz Szczepańczyk wrote:
> > On Wed, Apr 8, 2015 at 6:33 PM, Michael Niedermayer <michae...@gmx.at>
> > wrote:
> >
> > > Hi
> > >
> > > Some people on IRC asked about the uses of the AVIODir* API and it
> > > seems several developers do not know what the API is usefull for.
> > >
> > > I think this should be documented better
> > >
> > > also what can it be usefull for, random example:
> > > A "file open" dialog in a player. Without such API in a ffmpeg lib
> > > players would have to duplicate quite some code to list non local
> > > files.
> > >
> > >
> > Hi,
> >
> > where do you think such documentation should be added?
> >
> > Doxygen? doc/libavformat.texi?
>
> hmm, i dont know, you
> doc/libavformat.texi seems very short so it feels out of place but a
> link could maybe be added
>
> doxygen seems the better choice for the text itself
> but maybe someone has better idea(s)
>
Hey, I've written some docs. Sorry for the delay.
Mariusz
From 0386742856c87d83350f2c8d26c924c012b7da30 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mariusz=20Szczepa=C5=84czyk?= <mszczepanc...@gmail.com>
Date: Sat, 18 Apr 2015 04:31:14 +0200
Subject: [PATCH] lavf: add documentation on directory listing API
---
libavformat/avformat.h | 47 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 47 insertions(+)
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 4211a95..514e646 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -233,6 +233,53 @@
*
* @defgroup lavf_io I/O Read/Write
* @{
+ * @section lavf_io_dirlist Directory listing
+ * The directory listing API allows to list files on remote servers.
+ *
+ * Some of possible use cases:
+ * - an "open file" dialog to choose files from a remote location,
+ * - a recursive media finder providing a player with an ability to play all
+ * files from a given directory.
+ *
+ * @subsection lavf_io_dirlist_open Opening a directory
+ * At first, a directory needs to be opened by calling avio_open_dir()
+ * supplied with a URL and, optionally, ::AVDictionary containing
+ * protocol-specific parameters. The function returns zero or positive
+ * integer and allocates AVIODirContext on success.
+ *
+ * @code
+ * AVIODirContext *ctx = NULL;
+ * if (avio_open_dir(&ctx, "smb://example.com/some_dir", NULL) < 0) {
+ * fprintf(stderr, "Cannot open directory.\n");
+ * abort();
+ * }
+ * @endcode
+ *
+ * This code tries to open a sample directory using smb protocol without
+ * any additional parameters.
+ *
+ * @subsection lavf_io_dirlist_read Reading entries
+ * Each directory's entry (i.e. file, another directory, anything else
+ * within ::AVIODirEntryType) is represented by AVIODirEntry.
+ * Reading consecutive entries from an opened AVIODirContext is done by
+ * repeatedly calling avio_read_dir() on it. Each call returns zero or
+ * positive integer if successful. Reading can be stopped right after the
+ * NULL entry has been read -- it means there are no entries left to be
+ * read. The following code reads all entries from a directory associated
+ * with ctx and prints their names to standard output.
+ * @code
+ * AVIODirEntry *entry = NULL;
+ * for (;;) {
+ * if (avio_read_dir(ctx, &entry) < 0) {
+ * fprintf(stderr, "Cannot list directory.\n");
+ * abort();
+ * }
+ * if (!entry)
+ * break;
+ * printf("%s\n", entry->name);
+ * avio_free_directory_entry(&entry);
+ * }
+ * @endcode
* @}
*
* @defgroup lavf_codec Demuxers
--
2.3.3
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
http://ffmpeg.org/mailman/listinfo/ffmpeg-devel
