VLC播放器应用------LIBVLC API解析

转自：http://www.cnblogs.com/qq78292959/archive/2011/08/21/2147956.html

API

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

　　

libvlc_instance_t* libvlc_new(int  argc,  const char* const*  argv)  创建并初始化一个LIBVLC实例  这个函数接受一个命令行参数列表，这个参数列表影响LIBVLC INSTANCE的缺省配置.    Version:  参数意味着被从命令行传递到LIBVLC,就像VLC媒体播放器做的那样。有效的参数列表依赖于LIBVLC的版本、操作系统、平台以及LIBVLC的插件集。无效或不支持的参数将会导致该API的失败（return NULL）。此外，某些参数可能会改变LIBVLC的行为或以其它方式干扰LIBVLC的其它功能。    Parameters:  argc : 命令行参数个数  argv : 命令行类型参数    Returns:  成功返回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;------------------------------------------------事件结构</p>  typedef int libvlc_event_type_t;--------------------------------------事件类型结构  typedef void(*libvlc_callback_t)(const struct libvlc_event_t*,void*)--事件回调函数  

　　

API

• 注册事件管理器
  

  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 void libvlc_event_detach (  libvlc_event_manager_t *p_event_manager,  libvlc_event_type_t i_event_type,  libvlc_callback_t f_callback,  void *p_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()释放媒体播放器时就会调用该方法释放媒体播放器事件管理器．