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日志处理，我们有三点未知：
- WHEN：播放器运行时，libvlc何时打出日志；
- WHERE：我们应该在应用代码的什么地方打日志；
- 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:用户提供的数据,由事件带回
其他
- 获取事件类型名
VLC_PUBLIC_API const char * libvlc_event_type_name (libvlc_event_type_t event_type);
param:
event_type:事件类型 - 获取播放器事件管理器
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关联的事件管理器 - 获取媒体描述符对象事件管理器
VLC_PUBLIC_API libvlc_event_manager_t *
libvlc_media_event_manager (libvlc_media_t * p_md); - 获取媒体服务discover对象事件管理器
VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_discoverer_event_manager (libvlc_media_discoverer_t * p_mdis); - 获取媒体列表实例的事件管理器
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()释放媒体播放器时就会调用该方法释放媒体播放器事件管理器．
