windows 下VLC播放器應用之二——LIBVLC API解析

 

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；  

　　

常式

之前說了，呆龍在做一個簡易播放器時需要做日誌播放器處理。上面講了一些，下面給出個簡單例子：

背景：對於簡易LIBVLCTlog，我們有三點未知：

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()釋放媒體播放器時就會調用該方法釋放媒體播放器事件管理器．