From: Jean-Paul Saman Date: Mon, 25 Aug 2008 13:48:34 +0000 (+0200) Subject: Document more VLM API's and expand define. X-Git-Tag: 1.0.0-pre1~3404 X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=5c76c07d36d75a1c185a8708149e933a67ed3f6d;p=vlc Document more VLM API's and expand define. --- diff --git a/include/vlc/libvlc_vlm.h b/include/vlc/libvlc_vlm.h index de314e4095..36a445a464 100644 --- a/include/vlc/libvlc_vlm.h +++ b/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 ); /** @} */ diff --git a/include/vlc_vlm.h b/include/vlc_vlm.h index 665cf2db9f..4abe29aa27 100644 --- a/include/vlc_vlm.h +++ b/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 ); diff --git a/src/control/vlm.c b/src/control/vlm.c index 8e0f5fa7f8..f08d5fe115 100644 --- a/src/control/vlm.c +++ b/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 }