Document more VLM API's and expand define.

include/vlc/libvlc_vlm.h

@@ -215,7 +215,7 @@ VLC_PUBLIC_API void libvlc_vlm_seek_media( libvlc_instance_t *, char *,
 
 /**
  * Return information about the named broadcast.
- *
+ * \bug will always return NULL
  * \param p_instance the instance
  * \param psz_name the name of the broadcast
  * \param p_e an initialized exception pointer
@@ -224,26 +224,88 @@ VLC_PUBLIC_API void libvlc_vlm_seek_media( libvlc_instance_t *, char *,
 VLC_PUBLIC_API char* libvlc_vlm_show_media( libvlc_instance_t *, char *, libvlc_exception_t * );
 
 /**
- * Get information about media attribute from vlm.
+ * Get vlm_media instance position by name or instance id
  *
- * \param libvlc instance
- * \param type of information
- * \param default value
- * \return value of media attribute
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return position as float
+ */
+VLC_PUBLIC_API float libvlc_vlm_get_media_instance_position( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
+
+/**
+ * Get vlm_media instance time by name or instance id
+ *
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return time as integer
  */
-#define LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( attr, returnType, getType, default)\
-returnType libvlc_vlm_get_media_instance_## attr( libvlc_instance_t *, \
-                        char *, int , libvlc_exception_t * );
+VLC_PUBLIC_API int libvlc_vlm_get_media_instance_time( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
 
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( position, float, Float, -1);
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( time, int, Integer, -1);
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( length, int, Integer, -1);
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( rate, int, Integer, -1);
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( title, int, Integer, 0);
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( chapter, int, Integer, 0);
-VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( seekable, int, Bool, 0);
+/**
+ * Get vlm_media instance length by name or instance id
+ *
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return length of media item
+ */
+VLC_PUBLIC_API int libvlc_vlm_get_media_instance_length( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
 
-#undef LIBVLC_VLM_GET_MEDIA_ATTRIBUTE
+/**
+ * Get vlm_media instance playback rate by name or instance id
+ *
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return playback rate
+ */
+VLC_PUBLIC_API int libvlc_vlm_get_media_instance_rate( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
+
+/**
+ * Get vlm_media instance title number by name or instance id
+ * \bug will always return 0
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return title as number
+ */
+VLC_PUBLIC_API int libvlc_vlm_get_media_instance_title( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
+
+/**
+ * Get vlm_media instance chapter number by name or instance id
+ * \bug will always return 0
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return chapter as number
+ */
+VLC_PUBLIC_API int libvlc_vlm_get_media_instance_chapter( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
+
+/**
+ * Is libvlc instance seekable ?
+ * \bug will always return 0
+ * \param p_instance a libvlc instance
+ * \param psz_name name of vlm media instance
+ * \param i_instance instance id
+ * \param p_e an initialized exception pointer
+ * \return 1 if seekable, 0 if not
+ */
+VLC_PUBLIC_API int libvlc_vlm_get_media_instance_seekable( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_e );
 
 /** @} */
 

include/vlc_vlm.h

@@ -40,46 +40,43 @@
  * @{
  */
 
-/* VLM media */
+/** VLM media */
 typedef struct
 {
-    int64_t     id;
-    bool  b_enabled;
+    int64_t     id;     /*< numeric id for vlm_media_t item */
+    bool  b_enabled;    /*< vlm_media_t is enabled */
 
-    /* */
-    char *psz_name;
+    char *psz_name;     /*< descriptive name of vlm_media_t item */
 
-    /* */
-    int  i_input;
-    char **ppsz_input;
+    int  i_input;       /*< number of input options */
+    char **ppsz_input;  /*< array of input options */
 
-    int  i_option;
-    char **ppsz_option;
+    int  i_option;      /*< number of output options */
+    char **ppsz_option; /*< array of output options */
 
-    char *psz_output;
+    char *psz_output;   /*< */
 
-    /* */
-    bool b_vod;
+    bool b_vod;         /*< vlm_media_t is of type VOD */
     struct
     {
-        bool b_loop;
-    } broadcast;
+        bool b_loop;    /*< this vlc_media_t broadcast item should loop */
+    } broadcast;        /*< Broadcast specific information */
     struct
     {
-        char *psz_mux;
-    } vod;
+        char *psz_mux;  /*< name of muxer to use */
+    } vod;              /*< VOD specific information */
 
 } vlm_media_t;
 
-/* VLM media instance */
+/** VLM media instance */
 typedef struct
 {
-    char *psz_name;
+    char *psz_name;         /*< vlm media instance descriptive name */
 
-    int64_t     i_time;
-    int64_t     i_length;
-    double      d_position;
-    bool  b_paused;
+    int64_t     i_time;     /*< vlm media instance vlm media current time */
+    int64_t     i_length;   /*< vlm media instance vlm media item length */
+    double      d_position; /*< vlm media instance position in stream */
+    bool        b_paused;   /*< vlm media instance is paused */
     int         i_rate;     // normal is INPUT_RATE_DEFAULT
 } vlm_media_instance_t;
 
@@ -90,7 +87,7 @@ typedef struct
 } vlm_schedule_t
 #endif
 
-/* VLM control query */
+/** VLM control query */
 enum vlm_query_e
 {
     /* --- Media control */
@@ -148,11 +145,11 @@ enum vlm_query_e
    If a node has children, it should not have a value (=NULL).*/
 struct vlm_message_t
 {
-    char *psz_name;
-    char *psz_value;
+    char *psz_name;         /*< message name */
+    char *psz_value;        /*< message value */
 
-    int           i_child;
-    vlm_message_t **child;
+    int           i_child;  /*< number of child messages */
+    vlm_message_t **child;  /*< array of vlm_message_t */
 };
 
 
@@ -171,6 +168,11 @@ VLC_EXPORT( vlm_message_t *, vlm_MessageAdd, ( vlm_message_t *, vlm_message_t *
 VLC_EXPORT( void,            vlm_MessageDelete, ( vlm_message_t * ) );
 
 /* media helpers */
+
+/**
+ * Initialize a vlm_media_t instance
+ * \param p_media vlm_media_t instance to initialize
+ */
 static inline void vlm_media_Init( vlm_media_t *p_media )
 {
     memset( p_media, 0, sizeof(vlm_media_t) );
@@ -185,6 +187,11 @@ static inline void vlm_media_Init( vlm_media_t *p_media )
     p_media->broadcast.b_loop = false;
 }
 
+/**
+ * Copy a vlm_media_t instance into another vlm_media_t instance
+ * \param p_dst vlm_media_t instance to copy to
+ * \param p_src vlm_media_t instance to copy from
+ */
 static inline void vlm_media_Copy( vlm_media_t *p_dst, vlm_media_t *p_src )
 {
     int i;
@@ -214,6 +221,12 @@ static inline void vlm_media_Copy( vlm_media_t *p_dst, vlm_media_t *p_src )
         p_dst->broadcast.b_loop = p_src->broadcast.b_loop;
     }
 }
+
+/**
+ * Cleanup and release memory associated with this vlm_media_t instance.
+ * You still need to release p_media itself with vlm_media_Delete().
+ * \param p_media vlm_media_t to cleanup
+ */
 static inline void vlm_media_Clean( vlm_media_t *p_media )
 {
     int i;
@@ -231,6 +244,11 @@ static inline void vlm_media_Clean( vlm_media_t *p_media )
     if( p_media->b_vod )
         free( p_media->vod.psz_mux );
 }
+
+/**
+ * Allocate a new vlm_media_t instance
+ * \return vlm_media_t instance
+ */
 static inline vlm_media_t *vlm_media_New(void)
 {
     vlm_media_t *p_media = (vlm_media_t *)malloc( sizeof(vlm_media_t) );
@@ -238,11 +256,22 @@ static inline vlm_media_t *vlm_media_New(void)
         vlm_media_Init( p_media );
     return p_media;
 }
+
+/**
+ * Delete a vlm_media_t instance
+ * \param p_media vlm_media_t instance to delete
+ */
 static inline void vlm_media_Delete( vlm_media_t *p_media )
 {
     vlm_media_Clean( p_media );
     free( p_media );
 }
+
+/**
+ * Copy a vlm_media_t instance
+ * \param p_src vlm_media_t instance to copy
+ * \return vlm_media_t duplicate of p_src
+ */
 static inline vlm_media_t *vlm_media_Duplicate( vlm_media_t *p_src )
 {
     vlm_media_t *p_dst = vlm_media_New();
@@ -252,6 +281,10 @@ static inline vlm_media_t *vlm_media_Duplicate( vlm_media_t *p_src )
 }
 
 /* media instance helpers */
+/**
+ * Initialize vlm_media_instance_t
+ * \param p_instance vlm_media_instance_t to initialize
+ */
 static inline void vlm_media_instance_Init( vlm_media_instance_t *p_instance )
 {
     memset( p_instance, 0, sizeof(vlm_media_instance_t) );
@@ -262,10 +295,20 @@ static inline void vlm_media_instance_Init( vlm_media_instance_t *p_instance )
     p_instance->b_paused = false;
     p_instance->i_rate = INPUT_RATE_DEFAULT;
 }
+
+/**
+ * Cleanup vlm_media_instance_t
+ * \param p_instance vlm_media_instance_t to cleanup
+ */
 static inline void vlm_media_instance_Clean( vlm_media_instance_t *p_instance )
 {
     free( p_instance->psz_name );
 }
+
+/**
+ * Allocate a new vlm_media_instance_t
+ * \return a new vlm_media_instance_t
+ */
 static inline vlm_media_instance_t *vlm_media_instance_New(void)
 {
     vlm_media_instance_t *p_instance = (vlm_media_instance_t *) malloc( sizeof(vlm_media_instance_t) );
@@ -273,6 +316,11 @@ static inline vlm_media_instance_t *vlm_media_instance_New(void)
         vlm_media_instance_Init( p_instance );
     return p_instance;
 }
+
+/**
+ * Delete a vlm_media_instance_t
+ * \param p_instance vlm_media_instance_t to delete
+ */
 static inline void vlm_media_instance_Delete( vlm_media_instance_t *p_instance )
 {
     vlm_media_instance_Clean( p_instance );

src/control/vlm.c

@@ -96,6 +96,22 @@ char* libvlc_vlm_show_media( libvlc_instance_t *p_instance, char *psz_name,
     return NULL;
 #endif
 }
+#else
+
+char* libvlc_vlm_show_media( libvlc_instance_t *p_instance, char *psz_name,
+                             libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    (void)p_instance;
+    /* FIXME is it needed ? */
+    libvlc_exception_raise( p_exception, "Unable to call show %s", psz_name );
+    return NULL;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
+}
+
 #endif /* 0 */
 
 static int libvlc_vlm_init( libvlc_instance_t *p_instance,
@@ -173,7 +189,6 @@ void libvlc_vlm_release( libvlc_instance_t *p_instance, libvlc_exception_t *p_ex
 #endif
 }
 
-
 void libvlc_vlm_add_broadcast( libvlc_instance_t *p_instance, char *psz_name,
                                char *psz_input, char *psz_output,
                                int i_options, char **ppsz_options,
@@ -477,38 +492,146 @@ void libvlc_vlm_seek_media( libvlc_instance_t *p_instance, char *psz_name,
 #endif
 }
 
-#define LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( attr, returnType, getType, ret, code )\
-returnType libvlc_vlm_get_media_instance_## attr( libvlc_instance_t *p_instance, \
-                        char *psz_name, int i_instance, libvlc_exception_t *p_exception ) \
-{ \
-    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name, i_instance, \
-                                                                p_exception );  \
-    if( p_mi ) {                            \
-        returnType ret_value;               \
-        code;                               \
-        vlm_media_instance_Delete( p_mi );  \
-        return ret_value;                   \
-    }                                       \
-    libvlc_exception_raise( p_exception, "Unable to get %s "#attr "attribute" ); \
-    return ret; \
+float libvlc_vlm_get_media_instance_position( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    float result = -1;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        result = p_mi->d_position;
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get position attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
+}
+
+int libvlc_vlm_get_media_instance_time( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    int result = -1;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        result = p_mi->i_time;
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get time attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
+}
+
+int libvlc_vlm_get_media_instance_length( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    int result = -1;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        result = p_mi->i_length;
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get length attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
+}
+
+int libvlc_vlm_get_media_instance_rate( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    int result = -1;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        result = p_mi->i_rate;
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get rate attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
 }
 
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( position, float, Float, -1, ret_value = p_mi->d_position; );
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( time,     int, Integer, -1, ret_value = p_mi->i_time );
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( length,   int, Integer, -1, ret_value = p_mi->i_length );
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( rate,     int, Integer, -1, ret_value = p_mi->i_rate );
-/* FIXME extend vlm_media_instance_t to be able to implement them */
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( title,    int, Integer,  0, ret_value = 0 );
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( chapter,  int, Integer,  0, ret_value = 0 );
-LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( seekable, int, Bool,     0, ret_value = false );
+int libvlc_vlm_get_media_instance_title( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    int result = 0;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get title attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
+}
 
-#undef LIBVLC_VLM_GET_MEDIA_ATTRIBUTE
+int libvlc_vlm_get_media_instance_chapter( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
+{
+#ifdef ENABLE_VLM
+    int result = 0;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get chapter attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
+}
 
-char* libvlc_vlm_show_media( libvlc_instance_t *p_instance, char *psz_name,
-                             libvlc_exception_t *p_exception )
+int libvlc_vlm_get_media_instance_seekable( libvlc_instance_t *p_instance,
+    char *psz_name, int i_instance, libvlc_exception_t *p_exception )
 {
-    (void)p_instance;
-    /* FIXME is it needed ? */
-    libvlc_exception_raise( p_exception, "Unable to call show %s", psz_name );
-    return NULL;
+#ifdef ENABLE_VLM
+    bool result = 0;
+    vlm_media_instance_t *p_mi = libvlc_vlm_get_media_instance( p_instance, psz_name,
+                                        i_instance, p_exception );
+    if( p_mi )
+    {
+        vlm_media_instance_Delete( p_mi );
+        return result;
+    }
+    libvlc_exception_raise( p_exception, "Unable to get seekable attribute" );
+    return result;
+#else
+    libvlc_exception_raise( p_exception, "VLM has been disabled in this libvlc." );
+    return VLC_EGENERIC;
+#endif
 }