lavf: add AVFormatContext/AVStream fields for signaling to the user when events happen.

The only flags, for now, indicate if metadata was updated and are set after each call to
av_read_frame(). This comes with the caveat that, on stream start, it might not be set properly
as packets might be buffered in AVFormatContext.packet_buffer before being given to the user
in av_read_frame().

Signed-off-by: Anton Khirnov <anton@khirnov.net>

3 files changed, 27 insertions, 1 deletions

diff --git a/doc/APIchanges b/doc/APIchanges
index 6e5242e382..feb24cfdda 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -13,6 +13,10 @@ libavutil:     2014-08-09
 
 API changes, most recent first:
 
+2014-xx-xx - xxxxxxx - lavf 56.01.0 - avformat.h
+  Add AVFormatContext.event_flags and AVStream.event_flags for signaling to
+  the user when events happen in the file/stream.
+
 2014-04-xx - xxxxxxx - lavr 2.1.0 - avresample.h
   Add avresample_convert_frame() and avresample_config().
 
diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 61ae6fab5e..5b29145a01 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -296,6 +296,11 @@ struct AVFormatContext;
  *    -  sorting  -- a modified version of a tag that should be used for
  *       sorting will have '-sort' appended. E.g. artist="The Beatles",
  *       artist-sort="Beatles, The".
+ * - Some protocols and demuxers support metadata updates. After a successful
+ *   call to av_read_packet(), AVFormatContext.event_flags or AVStream.event_flags
+ *   will be updated to indicate if metadata changed. In order to detect metadata
+ *   changes on a stream, you need to loop through all streams in the AVFormatContext
+ *   and check their individual event_flags.
  *
  * -  Demuxers attempt to export metadata in a generic format, however tags
  *    with no generic equivalents are left as they are stored in the container.
@@ -798,6 +803,14 @@ typedef struct AVStream {
      */
     int            nb_side_data;
 
+    /**
+     * Flags for the user to detect events happening on the stream. Flags must
+     * be cleared by the user once the event has been handled.
+     * A combination of AVSTREAM_EVENT_FLAG_*.
+     */
+    int event_flags;
+#define AVSTREAM_EVENT_FLAG_METADATA_UPDATED 0x0001 ///< The call resulted in updated metadata.
+
     /*****************************************************************
      * All fields below this line are not part of the public API. They
      * may not be used outside of libavformat and can be changed and
@@ -1170,6 +1183,15 @@ typedef struct AVFormatContext {
      * @see AVCodecContext.strict_std_compliance
      */
     int strict_std_compliance;
+
+    /**
+     * Flags for the user to detect events happening on the file. Flags must
+     * be cleared by the user once the event has been handled.
+     * A combination of AVFMT_EVENT_FLAG_*.
+     */
+    int event_flags;
+#define AVFMT_EVENT_FLAG_METADATA_UPDATED 0x0001 ///< The call resulted in updated metadata.
+
     /*****************************************************************
      * All fields below this line are not part of the public API. They
      * may not be used outside of libavformat and can be changed and
diff --git a/libavformat/version.h b/libavformat/version.h
index 7258d4d0f2..181d2689b2 100644
--- a/libavformat/version.h
+++ b/libavformat/version.h
@@ -30,7 +30,7 @@
 #include "libavutil/version.h"
 
 #define LIBAVFORMAT_VERSION_MAJOR 56
-#define LIBAVFORMAT_VERSION_MINOR  0
+#define LIBAVFORMAT_VERSION_MINOR  1
 #define LIBAVFORMAT_VERSION_MICRO  0
 
 #define LIBAVFORMAT_VERSION_INT AV_VERSION_INT(LIBAVFORMAT_VERSION_MAJOR, \