Libvlc API 简单说明 [转]

Libvlc API 简单说明

原文来自http://www.xuebuyuan.com/1519616.html

libvlc_instance_t* libvlc_new(int  argc,  const char* const*  argv)

创建并初始化一个LIBVLC实例
这个函数接受一个命令行参数列表，这个参数列表影响LIBVLC INSTANCE的缺省配置.

Version:
参数意味着被从命令行传递到LIBVLC,就像VLC媒体播放器做的那样。有效的参数列表依赖于LIBVLC的版本、操作系统、平台以及LIBVLC的插件集。无效或不支持的参数将会导致该API的失败（return NULL）。此外，某些参数可能会改变LIBVLC的行为或以其它方式干扰LIBVLC的其它功能。

param:
argc : 命令行参数个数
argv : 命令行类型参数

return:
成功返回LIBVLC实例，失败返回NULL。

　　

VLC_PUBLIC_API void libvlc_release( libvlc_instance_t *p_instance );

减少LIBVLC INSTANCE的引用计数，并且如果计数为零的话就摧毁它。
（Decrement the reference count of a libvlc instance, and destroy it if it reaches zero）

param：
要摧毁的LIBVLC INSTANCE

VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );

创建一个空的媒体播放器对象

Parameters:
p_libvlc_instance：被创建的媒体播放器所属的实例

return:
一个新的媒体播放器对象，出错返回NULL.

VLC_PUBLIC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi );

使用后释放媒体播放器对象，减少媒体播放器对象的引用次数。如果计数已经为零，该方法将释放掉媒体播放器对象，如果媒体播放器对象已经被释放了，这个方法不应该再被调用（Release a media_player after use Decrement the reference count of a media player object. If the reference count is 0, then libvlc_media_player_release() will release the media player object. If the media player object has been released, then it should not be used again.）

param：
p_mi：要释放的媒体播放器对象

VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi );

从发送事件的媒体播放器对象那里获取一个事件管理器
（Get the Event Manager from which the media player send event）

param：
p_mi: 媒体播放器对象

return:
返回关联到给定媒体播放器对象的事件管理器

VLC_PUBLIC_API int libvlc_event_attach( libvlc_event_manager_t *p_event_manager,
                                        libvlc_event_type_t i_event_type,
                                        libvlc_callback_t f_callback,
                                        void *user_data );

事件通知注册器（Register for an event notification），设置事件处理器

param：
p_event_manager：你想关联的事件管理器
i_event_type：我们所要关注事件的类型
f_callback：事件发生时的回调函数
user_data：user provided data to carry with the event( 还没理解这个参数)

return:
成功：0；失败：ENOMEM

VLC_PUBLIC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );

设置给予媒体播放器媒体输出的win32/win64窗口句柄。如果构建LIBVLC时没有Win32/Win64 API输出的内置支持，该方法将不起作用（If LibVLC was built without Win32/Win64 API output support, then this has no effects）

param：
p_mi: 媒体播放器
drawable：绘制媒体（媒体输出）的窗口句柄

libvlc_log_* 函数提供对LibVLC消息日志的访问，用于调试或用于高级用户
VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );

返回LIBVLC的日志级别
param：
p_instance：libvlc 实例
return：
日志级别

VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_instance );

设置LIBVLC的日志级别
param：
p_instance：libvlc 实例
level：日志级别

VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *p_instance );

打开一个VLC消息日志句柄
param:
p_instance:libvlc实例
return:
成功：返回日志消息实例；失败：出错返回NULL；

VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *p_log );

关闭一个VLC消息日志实例
param:
p_log:libvlc日志实例或NULL

VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *p_log );

返回一个日志实例内的消息数目
param:
p_log:LIBVLC日志实例或NULL;
return:
返回日志消息的数目，如果p_log为空则返回0；

VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *p_log );

清空一个日志实例
日志实例内所有的消息都将被清空。日志应定期清除以避免堵塞。
param:
p_log:LIBVLC日志实例或NULL;

VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *p_log );

分配或返回一个指向日志消息的新迭代器
param:
p_log:LIBVLC日志实例
return:
日志迭代器对象或出错返回NULL

VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter );

释放之前分配的日志消息迭代器
param:
p_iter:LIBVLC日志迭代器或NULL

VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter );

迭代器返回日志是否有更多消息
param:
p_iter:LIBVLC日志迭代器或NULL；
return:
有：返回TRUE；没有：返回FALSE;

VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterator_t *p_iter,
                                                               libvlc_log_message_t *p_buffer );

返回下一条日志消息
消息内容一定不能被释放了
param：
p_iter:LIBVLC日志迭代器或NULL；
p_buffer:日志缓冲区；
return:
日志消息对象或NULL；

例程

之前说了，呆龙在做一个简易播放器时需要做日志播放器处理。上面讲了一些，下面给出个简单例子：

背景：对于简易LIBVLC日志处理，我们有三点未知：

1. WHEN：播放器运行时，libvlc何时打出日志；
2. WHERE：我们应该在应用代码的什么地方打日志；
3. HOW：如何利用LIBVLC给出的以上日志API打日志；

基于以上三点，我的想法是单独开一个线程，每隔一秒检查是否有日志，有则打出，没有继续

正文

说明:一些libvlc对象,如libvlc实例,libvlc播放器会产生异步信号,每一个对象都提供有事件管理器.可以将相应对象事件关联到对应libvlc对象的事件管理器处理或取消关联事件管理器.
相关结构

事件管理器:事件管理器属于一个libvlc对象,管理器可以从对象处接收事件信号
typedef struce libvlc_event_manager_t libvlc_event_manager_t;############事件管理器结构
<p>struct libvlc_event_t;################################################################事件结构

typedef int libvlc_event_type_t;################################################--事件类型结构
typedef void(*libvlc_callback_t)(const struct libvlc_event_t*,void*)--事件回调函数

注册事件管理器

VLC_PUBLIC_API int libvlc_event_attach (  
	libvlc_event_manager_t *p_event_manager,  
	libvlc_event_type_t i_event_type,  
	libvlc_callback_t f_callback,  
	void *user_data);  

param:
p_event_manager:要绑定的事件管理器
i_event_type: 事件类型
f_callback:回调函数指针
user_data:用户提供的数据,由事件带回

其他

1. 获取事件类型名
   VLC_PUBLIC_API const char * libvlc_event_type_name (libvlc_event_type_t event_type);
   param:
   event_type:事件类型
2. 获取播放器事件管理器
   VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager (libvlc_media_player_t *p_mi);
   Param:
   p_mi : Media Player
   return:
   返回p_mi关联的事件管理器
3. 获取媒体描述符对象事件管理器
   VLC_PUBLIC_API libvlc_event_manager_t *
   libvlc_media_event_manager (libvlc_media_t * p_md);
4. 获取媒体服务discover对象事件管理器
   VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_discoverer_event_manager (libvlc_media_discoverer_t * p_mdis);
5. 获取媒体列表实例的事件管理器
   VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_list_event_manager (libvlc_media_list_t *p_ml); param: p_ml : 媒体列表实例 6.获取VLM媒体事件管理器 VLC_PUBLIC_API libvlc_event_manager_t * libvlc_vlm_get_event_manager (libvlc_instance_t *p_instance);`
   Param:
   P_instance : libvlc实例

注意

通常,我们在"Get"之 后要"Release",比如Windows API之GetDC(),相应的ReleaseDC等,在这里对于事件管理器的获取也有一个相应的"Release".

void libvlc_event_manager_release(libvlc_event_manager_t * p_em );

但是,我们并不需要显示的调用该方法,因为"对于一些LIBVLC对象,其结构里就有'事件管理器'####-

libvlc_event_manager_t * p_event_manager;

在释放或销毁对象的时候，该方法会被调用以同时销毁相应对象的＇事件管理器＇＂，例如：在调用libvlc_media_player_release()释放媒体播放器时就会调用该方法释放媒体播放器事件管理器．