[vlc-devel] [PATCH 5/5] libvlc: add a function to release strings allocated by libvlc functions

[Steve Lhomme]

---
 include/vlc/libvlc.h              | 8 ++++++++
 include/vlc/libvlc_media.h        | 2 ++
 include/vlc/libvlc_media_player.h | 7 +++++--
 lib/core.c                        | 5 +++++
 lib/libvlc.sym                    | 1 +
 5 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h
index 0ec0045c96..789b881f55 100644
--- a/include/vlc/libvlc.h
+++ b/include/vlc/libvlc.h
@@ -277,6 +277,14 @@ LIBVLC_API const char * libvlc_get_compiler(void);
  */
 LIBVLC_API const char * libvlc_get_changeset(void);
 
+/**
+ * Frees a string returned by a LibVLC function.
+ *
+ * \param ptr the string pointer
+ * \version LibVLC 4.0.0 and later
+ */
+LIBVLC_API void libvlc_free_string( char *ptr );
+
 /** \defgroup libvlc_event LibVLC asynchronous events
  * LibVLC emits asynchronous events.
  *
diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index cd335a6e08..c72e026106 100644
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -548,6 +548,7 @@ LIBVLC_API void libvlc_media_release( libvlc_media_t *p_md );
  *
  * \param p_md a media descriptor object
  * \return string with mrl of media descriptor object
+ *         (it result must be released \ref with libvlc_free_string()).
  */
 LIBVLC_API char *libvlc_media_get_mrl( libvlc_media_t *p_md );
 
@@ -572,6 +573,7 @@ LIBVLC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md );
  * \param p_md the media descriptor
  * \param e_meta the meta to read
  * \return the media's meta
+ *         (it result must be released \ref with libvlc_free_string()).
  */
 LIBVLC_API char *libvlc_media_get_meta( libvlc_media_t *p_md,
                                              libvlc_meta_t e_meta );
diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h
index f4981cecbc..5f46cb3048 100644
--- a/include/vlc/libvlc_media_player.h
+++ b/include/vlc/libvlc_media_player.h
@@ -1491,7 +1491,7 @@ LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_fac
  *
  * \param p_mi the media player
  * \return the video aspect ratio or NULL if unspecified
- * (the result must be released with free()).
+ *         (it result must be released \ref with libvlc_free_string()).
  */
 LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );
 
@@ -1661,6 +1661,7 @@ void libvlc_chapter_descriptions_release( libvlc_chapter_description_t **p_chapt
  *
  * \param p_mi the media player
  * \return the crop filter geometry or NULL if unset
+ *         (it result must be released \ref with libvlc_free_string()).
  */
 LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi );
 
@@ -1776,6 +1777,8 @@ LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi,
  *
  * \param p_mi libvlc media player
  * \param option marq option to get \see libvlc_video_marquee_option_t
+ * \return the string corresponding to the marquee option
+ *         (it result must be released with libvlc_free_string()).
  */
 LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi,
                                                       unsigned option );
@@ -2086,7 +2089,7 @@ LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *mp,
  * \param mp media player
  * \return the current audio output device identifier
  *         NULL if no device is selected or in case of error
- *         (the result must be released with free()).
+ *         (the result must be released \ref with libvlc_free_string()).
  * \version LibVLC 3.0.0 or later.
  */
 LIBVLC_API char *libvlc_audio_output_device_get( libvlc_media_player_t *mp );
diff --git a/lib/core.c b/lib/core.c
index 6edf14b154..f5af61e459 100644
--- a/lib/core.c
+++ b/lib/core.c
@@ -151,6 +151,11 @@ const char * libvlc_get_changeset(void)
     return psz_vlc_changeset;
 }
 
+void libvlc_free_string( void *ptr )
+{
+    free( ptr );
+}
+
 static libvlc_module_description_t *module_description_list_get(
                 libvlc_instance_t *p_instance, const char *capability )
 {
diff --git a/lib/libvlc.sym b/lib/libvlc.sym
index 436681a4c3..15c777b00a 100644
--- a/lib/libvlc.sym
+++ b/lib/libvlc.sym
@@ -49,6 +49,7 @@ libvlc_dialog_set_callbacks
 libvlc_dialog_set_context
 libvlc_event_attach
 libvlc_event_detach
+libvlc_free_string
 libvlc_get_changeset
 libvlc_get_compiler
 libvlc_get_fullscreen
-- 
2.17.1