Improve Doxygen documentation, deobfuscate event types

[vlc] / include / vlc / libvlc_media.h

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index 261df7e1cfb9dd3a706d3910647ef8dbd40fd34a..075a1c670f32db3c7bcd16080a1f0b7a37eb1cb5 100644 (file)
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -35,24 +35,21 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * media
- *****************************************************************************/
-/** \defgroup libvlc_media libvlc_media
+/** \defgroup libvlc_media LibVLC media
  * \ingroup libvlc
- * LibVLC Media
+ * @ref libvlc_media_t is an abstract representation of a playable media.
+ * It consists of a media location and various optional meta data.
  * @{
  */
 
 typedef struct libvlc_media_t libvlc_media_t;
 
-/* Meta Handling */
-/** defgroup libvlc_meta libvlc_meta
+/** defgroup libvlc_meta LibVLC meta data
  * \ingroup libvlc_media
- * LibVLC Media Meta
  * @{
  */
 
+/** Meta data types */
 typedef enum libvlc_meta_t {
     libvlc_meta_Title,
     libvlc_meta_Artist,
@@ -97,11 +94,11 @@ typedef enum libvlc_state_t
     libvlc_Error
 } libvlc_state_t;
 
-typedef enum libvlc_media_option_t
+enum
 {
     libvlc_media_option_trusted = 0x2,
     libvlc_media_option_unique = 0x100
-} libvlc_media_option_t;
+};
 
 typedef enum libvlc_es_type_t
 {
@@ -111,9 +108,8 @@ typedef enum libvlc_es_type_t
     libvlc_es_text      = 2,
 } libvlc_es_type_t;
 
-/** defgroup libvlc_media_stats_t libvlc_media_stats_t
+/** defgroup libvlc_media_stats_t LibVLC media statistics
  * \ingroup libvlc_media
- * LibVLC Media statistics
  * @{
  */
 typedef struct libvlc_media_stats_t
@@ -151,6 +147,7 @@ typedef struct libvlc_media_es_t
 {
     /* Codec fourcc */
     uint32_t    i_codec;
+    int         i_id;
     libvlc_es_type_t i_type;
 
     /* Codec specific */
@@ -169,30 +166,37 @@ typedef struct libvlc_media_es_t
 
 
 /**
- * Create a media with the given MRL.
+ * Create a media with a certain given media resource location.
  *
  * \param p_instance the instance
  * \param psz_mrl the MRL to read
- * \param p_e an initialized exception pointer
- * \return the newly created media
+ * \return the newly created media or NULL on error
+ */
+VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location(
+                                   libvlc_instance_t *p_instance,
+                                   const char * psz_mrl );
+
+/**
+ * Create a media with a certain file path.
+ *
+ * \param p_instance the instance
+ * \param path local filesystem path
+ * \return the newly created media or NULL on error
  */
-VLC_PUBLIC_API libvlc_media_t * libvlc_media_new(
+VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path(
                                    libvlc_instance_t *p_instance,
-                                   const char * psz_mrl,
-                                   libvlc_exception_t *p_e );
+                                   const char *path );
 
 /**
- * Create a media as an empty node with the passed name.
+ * Create a media as an empty node with a given name.
  *
  * \param p_instance the instance
  * \param psz_name the name of the node
- * \param p_e an initialized exception pointer
- * \return the new empty media
+ * \return the new empty media or NULL on error
  */
 VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node(
                                    libvlc_instance_t *p_instance,
-                                   const char * psz_name,
-                                   libvlc_exception_t *p_e );
+                                   const char * psz_name );
 
 /**
  * Add an option to the media.
@@ -226,7 +230,7 @@ VLC_PUBLIC_API void libvlc_media_add_option(
 VLC_PUBLIC_API void libvlc_media_add_option_flag(
                                    libvlc_media_t * p_md,
                                    const char * ppsz_options,
-                                   libvlc_media_option_t i_flags );
+                                   unsigned i_flags );
 
 
 /**
@@ -261,7 +265,7 @@ VLC_PUBLIC_API char * libvlc_media_get_mrl( libvlc_media_t * p_md );
 /**
  * Duplicate a media descriptor object.
  *
- * \param p_meta_desc a media descriptor object.
+ * \param p_md a media descriptor object.
  */
 VLC_PUBLIC_API libvlc_media_t * libvlc_media_duplicate( libvlc_media_t *p_md );
 
@@ -281,7 +285,7 @@ VLC_PUBLIC_API char * libvlc_media_get_meta( libvlc_media_t *p_md,
  *
  * \param p_md the media descriptor
  * \param e_meta the meta to write
- * \param the media's meta
+ * \param psz_value the media's meta
  */
 VLC_PUBLIC_API void libvlc_media_set_meta( libvlc_media_t *p_md,
                                            libvlc_meta_t e_meta,
@@ -352,12 +356,10 @@ VLC_PUBLIC_API libvlc_event_manager_t *
  * Get duration (in ms) of media descriptor object item.
  *
  * \param p_md media descriptor object
- * \param p_e an initialized exception object
- * \return duration of media item
+ * \return duration of media item or -1 on error
  */
 VLC_PUBLIC_API libvlc_time_t
-   libvlc_media_get_duration( libvlc_media_t * p_md,
-                                         libvlc_exception_t * p_e );
+   libvlc_media_get_duration( libvlc_media_t * p_md );
 
 /**
  * Get preparsed status for media descriptor object.
@@ -398,7 +400,7 @@ VLC_PUBLIC_API void *
  * will duplicate the entries in the array each time.
  *
  * \param p_md media descriptor object
- * \param pp_es adress to store an allocated array of Elementary Streams descriptions (must be freed by the caller)
+ * \param pp_es address to store an allocated array of Elementary Streams descriptions (must be freed by the caller)
  *
  * return the number of Elementary Streams
  */