discoverer: Annotate `DiscovererInfo::get_audio_streams()` and others with the concre...

[platform/upstream/gstreamer.git] / subprojects / gst-plugins-base / gst-libs / gst / pbutils / gstdiscoverer-types.c

diff --git a/subprojects/gst-plugins-base/gst-libs/gst/pbutils/gstdiscoverer-types.c b/subprojects/gst-plugins-base/gst-libs/gst/pbutils/gstdiscoverer-types.c
index d679803..c0e2e10 100644 (file)
--- a/subprojects/gst-plugins-base/gst-libs/gst/pbutils/gstdiscoverer-types.c
+++ b/subprojects/gst-plugins-base/gst-libs/gst/pbutils/gstdiscoverer-types.c
@@ -50,7 +50,7 @@ G_DEFINE_TYPE (GstDiscovererStreamInfo, gst_discoverer_stream_info,
 static void
 gst_discoverer_stream_info_init (GstDiscovererStreamInfo * info)
 {
-  /* Nothing needs initialization */
+  info->stream_number = -1;
 }
 
 static void
@@ -74,6 +74,8 @@ gst_discoverer_stream_info_finalize (GObject * object)
 
   if (info->misc)
     gst_structure_free (info->misc);
+
+  G_OBJECT_CLASS (gst_discoverer_stream_info_parent_class)->finalize (object);
 }
 
 static void
@@ -143,6 +145,8 @@ gst_discoverer_info_copy_int (GstDiscovererStreamInfo * info,
   if (stream_map)
     g_hash_table_insert (stream_map, info, ret);
 
+  ret->stream_number = info->stream_number;
+
   return ret;
 }
 
@@ -175,7 +179,11 @@ gst_discoverer_container_info_finalize (GObject * object)
 
   gst_discoverer_stream_info_list_free (info->streams);
 
-  gst_discoverer_stream_info_finalize ((GObject *) info);
+  if (info->tags)
+    gst_tag_list_unref (info->tags);
+
+  G_OBJECT_CLASS (gst_discoverer_container_info_parent_class)->finalize
+      (object);
 }
 
 static void
@@ -204,6 +212,9 @@ gst_stream_container_info_copy_int (GstDiscovererContainerInfo * ptr,
       g_hash_table_insert (stream_map, tmp->data, subtop);
   }
 
+  if (ptr->tags)
+    ret->tags = gst_tag_list_copy (ptr->tags);
+
   return ret;
 }
 
@@ -380,6 +391,8 @@ gst_discoverer_info_finalize (GObject * object)
   g_free (info->cachefile);
 
   g_ptr_array_unref (info->missing_elements_details);
+
+  G_OBJECT_CLASS (gst_discoverer_info_parent_class)->finalize (object);
 }
 
 static GstDiscovererInfo *
@@ -497,7 +510,7 @@ gst_discoverer_info_get_streams (GstDiscovererInfo * info, GType streamtype)
  *
  * Finds all the #GstDiscovererAudioInfo contained in @info
  *
- * Returns: (transfer full) (element-type GstPbutils.DiscovererStreamInfo): A #GList of
+ * Returns: (transfer full) (element-type GstPbutils.DiscovererAudioInfo): A #GList of
  * matching #GstDiscovererStreamInfo. The caller should free it with
  * gst_discoverer_stream_info_list_free().
  */
@@ -513,7 +526,7 @@ gst_discoverer_info_get_audio_streams (GstDiscovererInfo * info)
  *
  * Finds all the #GstDiscovererVideoInfo contained in @info
  *
- * Returns: (transfer full) (element-type GstPbutils.DiscovererStreamInfo): A #GList of
+ * Returns: (transfer full) (element-type GstPbutils.DiscovererVideoInfo): A #GList of
  * matching #GstDiscovererStreamInfo. The caller should free it with
  * gst_discoverer_stream_info_list_free().
  */
@@ -529,7 +542,7 @@ gst_discoverer_info_get_video_streams (GstDiscovererInfo * info)
  *
  * Finds all the #GstDiscovererSubtitleInfo contained in @info
  *
- * Returns: (transfer full) (element-type GstPbutils.DiscovererStreamInfo): A #GList of
+ * Returns: (transfer full) (element-type GstPbutils.DiscovererSubtitleInfo): A #GList of
  * matching #GstDiscovererStreamInfo. The caller should free it with
  * gst_discoverer_stream_info_list_free().
  */
@@ -546,7 +559,7 @@ gst_discoverer_info_get_subtitle_streams (GstDiscovererInfo * info)
  *
  * Finds all the #GstDiscovererContainerInfo contained in @info
  *
- * Returns: (transfer full) (element-type GstPbutils.DiscovererStreamInfo): A #GList of
+ * Returns: (transfer full) (element-type GstPbutils.DiscovererContainerInfo): A #GList of
  * matching #GstDiscovererStreamInfo. The caller should free it with
  * gst_discoverer_stream_info_list_free().
  */
@@ -596,7 +609,7 @@ gst_discoverer_stream_info_get_stream_type_nick (GstDiscovererStreamInfo * info)
  * gst_discoverer_stream_info_get_previous:
  * @info: a #GstDiscovererStreamInfo
  *
- * Returns: (transfer full): the previous #GstDiscovererStreamInfo in a chain.
+ * Returns: (transfer full) (nullable): the previous #GstDiscovererStreamInfo in a chain.
  * %NULL for starting points. Unref with #gst_discoverer_stream_info_unref
  * after usage.
  */
@@ -614,7 +627,7 @@ gst_discoverer_stream_info_get_previous (GstDiscovererStreamInfo * info)
  * gst_discoverer_stream_info_get_next:
  * @info: a #GstDiscovererStreamInfo
  *
- * Returns: (transfer full): the next #GstDiscovererStreamInfo in a chain. %NULL
+ * Returns: (transfer full) (nullable): the next #GstDiscovererStreamInfo in a chain. %NULL
  * for final streams.
  * Unref with #gst_discoverer_stream_info_unref after usage.
  */
@@ -633,7 +646,7 @@ gst_discoverer_stream_info_get_next (GstDiscovererStreamInfo * info)
  * gst_discoverer_stream_info_get_caps:
  * @info: a #GstDiscovererStreamInfo
  *
- * Returns: (transfer full): the #GstCaps of the stream. Unref with
+ * Returns: (transfer full) (nullable): the #GstCaps of the stream. Unref with
  * #gst_caps_unref after usage.
  */
 GstCaps *
@@ -650,7 +663,7 @@ gst_discoverer_stream_info_get_caps (GstDiscovererStreamInfo * info)
  * gst_discoverer_stream_info_get_tags:
  * @info: a #GstDiscovererStreamInfo
  *
- * Returns: (transfer none): the tags contained in this stream. If you wish to
+ * Returns: (transfer none) (nullable): the tags contained in this stream. If you wish to
  * use the tags after the life-time of @info you will need to copy them.
  */
 const GstTagList *
@@ -665,7 +678,7 @@ gst_discoverer_stream_info_get_tags (GstDiscovererStreamInfo * info)
  * gst_discoverer_stream_info_get_toc:
  * @info: a #GstDiscovererStreamInfo
  *
- * Returns: (transfer none): the TOC contained in this stream. If you wish to
+ * Returns: (transfer none) (nullable): the TOC contained in this stream. If you wish to
  * use the TOC after the life-time of @info you will need to copy it.
  */
 const GstToc *
@@ -699,7 +712,7 @@ gst_discoverer_stream_info_get_stream_id (GstDiscovererStreamInfo * info)
  * Deprecated: This functions is deprecated since version 1.4, use
  * #gst_discoverer_info_get_missing_elements_installer_details
  *
- * Returns: (transfer none): additional information regarding the stream (for
+ * Returns: (transfer none) (nullable): additional information regarding the stream (for
  * example codec version, profile, etc..). If you wish to use the #GstStructure
  * after the life-time of @info you will need to copy it.
  */
@@ -712,6 +725,23 @@ gst_discoverer_stream_info_get_misc (GstDiscovererStreamInfo * info)
 }
 #endif
 
+/**
+ * gst_discoverer_stream_info_get_stream_number:
+ * @info: a #GstDiscovererStreamInfo
+ *
+ * Returns: the stream number, -1 if no index could be determined. This property
+ * acts as a unique identifier as a 'int' for the stream.
+ *
+ * Since: 1.20
+ */
+gint
+gst_discoverer_stream_info_get_stream_number (GstDiscovererStreamInfo * info)
+{
+  g_return_val_if_fail (GST_IS_DISCOVERER_STREAM_INFO (info), -1);
+
+  return info->stream_number;
+}
+
 /* GstDiscovererContainerInfo */
 
 /**
@@ -738,6 +768,23 @@ gst_discoverer_container_info_get_streams (GstDiscovererContainerInfo * info)
   return res;
 }
 
+/**
+ * gst_discoverer_container_info_get_tags:
+ * @info: a #GstDiscovererStreamInfo
+ *
+ * Returns: (transfer none) (nullable): tags specific to the given container. If you wish to use
+ * the tags after the life-time of @info, you will need to copy them.
+ *
+ * Since: 1.20
+ */
+const GstTagList *
+gst_discoverer_container_info_get_tags (const GstDiscovererContainerInfo * info)
+{
+  g_return_val_if_fail (GST_IS_DISCOVERER_CONTAINER_INFO (info), NULL);
+
+  return info->tags;
+}
+
 /* GstDiscovererAudioInfo */
 
 #define AUDIO_INFO_ACCESSOR_CODE(fieldname, type, failval)             \
@@ -807,7 +854,7 @@ AUDIO_INFO_ACCESSOR_CODE (max_bitrate, guint, 0);
  * gst_discoverer_audio_info_get_language:
  * @info: a #GstDiscovererAudioInfo
  *
- * Returns: the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or NULL if unknown.
  */
 
 AUDIO_INFO_ACCESSOR_CODE (language, const gchar *, NULL);
@@ -940,7 +987,7 @@ gst_discoverer_video_info_is_image (const GstDiscovererVideoInfo * info)
  * gst_discoverer_subtitle_info_get_language:
  * @info: a #GstDiscovererSubtitleInfo
  *
- * Returns: the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or NULL if unknown.
  */
 
 SUBTITLE_INFO_ACCESSOR_CODE (language, const gchar *, NULL);
@@ -975,7 +1022,7 @@ DISCOVERER_INFO_ACCESSOR_CODE (result, GstDiscovererResult, GST_DISCOVERER_OK);
  * gst_discoverer_info_get_stream_info:
  * @info: a #GstDiscovererInfo
  *
- * Returns: (transfer full): the structure (or topology) of the URI as a
+ * Returns: (transfer full) (nullable): the structure (or topology) of the URI as a
  * #GstDiscovererStreamInfo.
  * This structure can be traversed to see the original hierarchy. Unref with
  * gst_discoverer_stream_info_unref() after usage.
@@ -1051,29 +1098,31 @@ DISCOVERER_INFO_ACCESSOR_CODE (live, gboolean, FALSE);
  * Deprecated: This functions is deprecated since version 1.4, use
  * #gst_discoverer_info_get_missing_elements_installer_details
  *
- * Returns: (transfer none): Miscellaneous information stored as a #GstStructure
+ * Returns: (transfer none) (nullable): Miscellaneous information stored as a #GstStructure
  * (for example: information about missing plugins). If you wish to use the
  * #GstStructure after the life-time of @info, you will need to copy it.
  */
 
 DISCOVERER_INFO_ACCESSOR_CODE (misc, const GstStructure *, NULL);
-#endif
 
 /**
  * gst_discoverer_info_get_tags:
  * @info: a #GstDiscovererInfo
  *
- * Returns: (transfer none): all tags contained in the URI. If you wish to use
+ * Returns: (transfer none) (nullable): all tags contained in the URI. If you wish to use
  * the tags after the life-time of @info, you will need to copy them.
+ *
+ * Deprecated: 1.20: Use gst_discoverer_{container,stream}_info_get_tags() instead.
  */
 
 DISCOVERER_INFO_ACCESSOR_CODE (tags, const GstTagList *, NULL);
+#endif
 
 /**
  * gst_discoverer_info_get_toc:
  * @info: a #GstDiscovererInfo
  *
- * Returns: (transfer none): TOC contained in the URI. If you wish to use
+ * Returns: (transfer none) (nullable): TOC contained in the URI. If you wish to use
  * the TOC after the life-time of @info, you will need to copy it.
  */