用于腳本語言的播放器對象模型

ActiveX 采用擁有編程功能的對象概念。Windows 媒體播放器使用一些對象來劃分控件提供的功能。 根對象為 Player 對象，其他對象都通過特定的屬性與 Player 對象關聯。

下圖展示了Windows媒體播放器ActiveX控件對象模型是怎樣與腳本語言一起工作的。

在C++中，有時在.NET語言中， 對象使用COM接口來表示。在 Windows 媒體播放器對象模型中，COM 接口的名稱與對象名稱相同，只是附加了“IWMP”前綴。例如，Network 對象對外公開為 IWMPNetwork 接口。

下面的小節提供每一個對象的概念說明：

• 關于 Cdrom 和 CdromCollection 對象
  
• 關于 ClosedCaption 對象
  
• 關于 Controls 對象
• 關于 DVD 對象
• 關于 Error 和 ErrorItem 對象
• 關于 MediaCollection 和 Media 對象
• 關于 MetadataPicture 對象
• 關于 MetadataText 對象
• 關于 Network 對象
• 關于 Player 對象
• 關于 PlayerApplication 對象
• 關于 Playlist, PlaylistCollection, 和 PlaylistArray 對象
• 關于 Query 對象
• 關于 Settings 對象
• 關于 StringCollection 對象

其他的功能可以通過特殊的COM接口來使用。您是否能夠存取這些接口取決于您使用的編程語言和其他一些因素，如用來創建Windows媒體播放器控件實例的模式。要學習Windows媒體播放器控件對外公開的完整的COM接口列表，請查看 用于C++的對象模型參考。

關于 Cdrom 和 CdromCollection 對象

Cdrom 和 CdromCollection 對象負責管理您的計算機的CD驅動器接口， 該接口可用來讀取并播放CD。

CdromCollection 對象僅可以通過 Player 對象的 cdromCollection 屬性進行訪問。cdromCollection 屬性會返回一個 CdromCollection 對象。 要存取 CdromCollection 對象的屬性，您必須首先創建這個對象。例如，要使用 count 屬性，您必須使用下面的代碼：

mycount = player.cdromCollection.count;

您僅可以通過 CdromCollection 對象來訪問 Cdrom 對象。例如，要使用 Eject 方法彈出CD驅動器，您必須首先創建 collection 對象，然后通過該對象的一個項目來引用 Cdrom 對象。 要彈出CD，使用如下代碼：

player.cdromCollection.item(0).eject();

在上面的兩種情況下，您首先創建了集合對象（CdromCollection）然后獲得該集合的一個特定對象。集合的第一個項目對象， Item(0)，對應于第一個CD驅動器。然后您調用了該項目的一個方法，Eject。

關于 ClosedCaption 對象

ClosedCaption 對象管理Windows媒體播放器的字幕接口。您可以通過 Player 對象的 closedCaption 屬性來得到 ClosedCaption 對象。例如，要取得字幕對象的 SAMIFileName 屬性值，使用下面代碼：

myfile = player.closedCaption.SAMIFileName;

關于 Controls 對象

Controls 對象管理數字媒體內容的傳輸，它使用像Play和Stop之類的方法來進行控制。僅可以使用Player對象的controls屬性來進行存取。Controls 屬性返回 Controls 對象。當創建了Controls對象后，您僅可以存取它的屬性。例如，要使用Play方法，您必須使用下面的代碼：

player.controls.play();

關于 DVD 對象

DVD 對象添加了專用于DVD媒體的功能。一般來說，Windows媒體播放器會像其他數字媒體一樣對待DVD媒體。比如，使用CdromCollection 對象來枚舉DVD驅動器列表，使用Playlist對象和Media對象來管理DVD標題和章節。然而，有些功能是DVD特有的，這時候就用到DVD對象 了。例如，DVD有一個概念叫做區域。要取得DVD媒體的當前區域，使用下面的代碼：

mydomain = player.dvd.domain;

關于 Error 和 ErrorItem 對象

Error 和 ErrorItem 對象負責管理Windows媒體播放器的錯誤處理。Error 對象可以通過 Player 對象的 error 屬性來得到。使用 Error 對象的 item 屬性，您可以創建 ErrorItem 對象，使用這個對象您可以得到一個特別的錯誤代碼。例如，要得到第一個錯誤項目的錯誤代碼，使用下面的代碼：

myerrorcode = player.error.item(0).errorCode;

您也可以使用下面的代碼來調用 Error 對象的在線參考：

player.error.webHelp();

關于 MediaCollection 和 Media 對象

MediaCollection 及 Media 對象管理媒體的集合，媒體集合定義了Windows媒體播放器可以存取的數字媒體文件的位置。通過Player對象的 mediaCollection 屬性來得到 MediaCollection 對象。mediaCollection 屬性返回 MediaCollection 對象。當您創建了 MediaCollection 對象，您僅可以存取它的屬性。例如，要添加一個媒體文件（一首歌），使用如下的代碼：

player.mediaCollection.add('laure.wma');

這樣您就把“laure.wma”這個文件添加到了媒體集合中了。

您可以使用 Player 的 currentMedia 屬性來取得當前的 Media 對象。例如，下面的代碼可以得到當前的 Media 對象的 duration 屬性：

myduration = player.currentMedia.duration;

要存取 Media 對象的屬性，有很多方法可以取得該對象。比如，如果你想要存取當前媒體的 duration 屬性，下面的每一行代碼都可以使用。

取得當前播放的媒體的持續時間：

player.currentMedia.duration;

取得播放列表的當前媒體的持續時間：

player.controls.currentItem.duration;

取得播放列表的第三個媒體項目的持續時間：

player.currentPlaylist.item(2).duration;

取得“Jazz” 流派類型的第三個媒體項目的持續時間：

player.mediaCollection.getByGenre("jazz").item(2).duration;

取得第十個播放列表的第三個媒體項目的持續時間：

player.playlistCollection.getAll.item(1).item(2).duration;

關于 MetadataPicture 對象

WM/Picture 元數據屬性提供元圖像的詳細信息，像唱片封面。MetadataPicture 對象提供了一種方法來獲得與該圖像有關的獨立數據。您可以把 WM/Picture 元數據屬性看作混合屬性的一部分。當你使用 Media.getItemInfoByType 取得元圖像的信息的時候，您就取得了一個 MetadataPicture 對象，該對象包含含有獨立數據的屬性。

關于 MetadataText 對象

某些元數據屬性，像 WM/Lyrics_Synchronised，提供了與描述文本相關的說明。MetadataText 對象提供了分別獲取該文本及描述信息的獨立方法。當你使用 Media.getItemInfoByType 來取得復合文本屬性信息的時候，您就得到了一個 MetadataText 對象，該對象包含含有獨立數據的屬性。

關于 Network 對象

Network 對象管理允許你確定內容流如何通過網絡來傳輸的屬性。比如，你可以發現媒體包是被丟失了還是正確傳輸了。 Network 對象通過 Player 對象的 network 屬性來訪問。network 屬性返回 Network 對象。當你創建了 Network 對象，您僅可以存取它的屬性。例如，要使用 Bandwidth 屬性，您必須使用如下代碼：

mybandwidth = player.network.bandwidth; 關于 Player 對象

Player 對象是Windows媒體播放器控件的核心對象。其他所有的相關對象都通過特定的屬性連接到這個對象，只有通過該對象的特性屬性才能返回其他對象。例如，Settings 對象要通過 settings 屬性才能訪問。Player 對象提供方法、屬性和事件與Windows媒體播放器的核心功能相關聯。

因為此參考也用于皮膚編程，為了方便舉例，Player 對象的 ID 一律用 "player" 表示。

在皮膚定義文件中給出了使用 player 全局屬性來存取 Player 對象的腳本。通過 Player 對象，Windows媒體播放器控件中的所有其他對象都可以使用腳本來存取了。Player 對象的事件以及 URL 屬性也可以在設計的時候使用 PLAYER 皮膚元素來指定。更多信息，請參考 Windows Media Player Skins.

關于 PlayerApplication 對象

PlayerApplication 對象用于遠端Windows媒體播放器。它提供了切換遠端Windows媒體播放器的控件模式和全模式的功能。

遠端功能使Windows媒體播放器控件可以嵌入C++應用程序中，而且該控件可以使用與本地播放器一樣的回放引擎。這意味著您可以在C++代碼中使用COM接口訪問 PlayerApplication 對象。然而，有一種特殊情形，這種情形下您可以使用某個Windows媒體播放器皮膚作為用戶接口來顯示嵌入的 Windows 媒體播放器控件。 在這種情形下，PlayerApplication 可以使用皮膚代碼中的JScript來編程。

關于 Playlist, PlaylistCollection, 和 PlaylistArray 對象

Playlist，PlaylistCollection 及 PlaylistArray 對象管理 Windows 媒體播放器可以用來指定內容播放順序的播放列表。您可以從 Player 對象的 playlistCollection 屬性來得到 PlaylistCollection 對象。playlistCollection 屬性返回 PlaylistCollection 對象。當您創建了 PlaylistCollection 對象，您僅可以存取它的屬性。例如，要創建一個新的播放列表，您必須首先得到 PlaylistCollection 對象，然后使用該對象的某個方法：

player.playlistCollection.newplaylist('myplaylist');

您可以使用 currentPlaylist 屬性來得到當前播放列表。例如，要得到當前播放列表的名稱，可以使用如下代碼：

myname = player.currentPlaylist.name; PlaylistCollection 對象的 getAll 或 getByName 方法可以返回 PlaylistArray 對象。比如，要得到播放列表的數目，使用如下代碼： howmany = player.playlistCollection.getAll().count;

要通過名稱來取得某已知播放列表，使用如下代碼：

if (player.playlistCollection.getbyname('myplaylist').count == 1) {
pl = player.playlistCollection.getbyname('myplaylist').item(0);
} 關于 Query 對象

Query 對象表示一個復合查詢。通過調用mediaCollection.createQuery，您可以創建一個新的空查詢對象。當你創建了一個Query 對象 ，你就可以調用 addCondition 給這個復合查詢添加一個條件。每一個對 addCondition 的調用都將使用AND邏輯給一個存在的查詢添加一個新的條件。

例如，假設你想要創建一個查詢，該查詢表示所有 WM/Genre 等于“Jazz” 并且 Author 包含“Jim”的數字媒體，你可以使用如下JScript代碼創建一個復合查詢來表示這些條件。

?

// Create the query object.
var Query = player.mediaCollection.createQuery();

// Add the conditions.
Query.addCondition("WM/Genre", "Equals", "Jazz");
Query.addCondition("Author", "Contains", "Jim");?

要添加一個使用OR邏輯的條件到復合查詢，你必須調用 Query.beginNextGroup。這個方法意味著前一組條件已經完成，而下一個對 addCondition 的調用表示新一組條件的開始。

例如，要創建一個查詢，該查詢表示所有的 WM/Genre 等于“Jazz”并且 Author 包含“Jim”或者 Author 包含“Dave”，您可以用如下的示例代碼：

// Create the query object.
var Query = player.mediaCollection.createQuery();

// Add the conditions.
Query.addCondition("WM/Genre", "Equals", "Jazz");
Query.addCondition("Author", "Contains", "Jim");

// Start the next condition group. This group will be
// combined with the previous group using a logical OR operation.
Query.beginNextGroup();

// Add the conditions.
Query.addCondition("WM/Genre", "Equals", "Jazz"); Query.addCondition("Author", "Contains", "Dave");

要執行你的復合查詢，調用 MediaCollection.getPlaylistByQuery。

關于 Settings 對象

Settings 對象管理控件的設置，像聲音大小、播放次數、靜音等等。它僅可以通過 Player 對象的 settings 屬性來存取。settings 屬性返回 Settings 對象。當您創建了Settings 對象，您僅可以存取它的屬性。例如，要得到 Volume 屬性的值，您必須使用如下代碼：

myvolume = player.settings.volume; 關于 StringCollection 對象

StringCollection 對象管理字符串集合，該集合提供了對 MediaCollection 對象進行字符串處理的能力。
StringCollection 對象可以通過 MediaCollection? 對象的 getAttributeStringCollection 方法來獲得。您可以將這個對象用于字符串集合，表示各種媒體項目屬性的值。

英文原文如下：

Player Object Model for Scripting Languages

ActiveX uses the concept of objects to contain programming functionality. Windows Media Player uses several objects to divide up the functionality the control provides. The root object is the Player object, and the other objects are attached to the Player object through specific properties.

The following diagram shows how the Windows Media Player 11 ActiveX control object model works for scripting languages.

In C++, and sometimes in .NET languages, objects are represented by COM interfaces. In the Windows Media Player object model, COM interface names are the same as the object name, but are prefixed with "IWMP". For example, the Network object is exposed through the IWMPNetwork interface.

The following sections provide conceptual overviews for each object:

• About the Cdrom and CdromCollection Objects
• About the ClosedCaption Object
• About the Controls Object
• About the DVD Object
• About the Error and ErrorItem Objects
• About the MediaCollection and Media Objects
• About the MetadataPicture Object
• About the MetadataText Object
• About the Network Object
• About the Player Object
• About the PlayerApplication Object
• About the Playlist, PlaylistCollection, and PlaylistArray Objects
• About the Query Object
• About the Settings Object
• About the StringCollection Object

Additional functionality is available through certain COM interfaces. Whether you can access these interfaces may depend on the language you use for programming and other factors, such as the mode used to create the instance of the Windows Media Player control. For a complete list of COM interfaces exposed by the Windows Media Player control, see the Object Model Reference for C++.

About the Cdrom and CdromCollection Objects

The Cdrom and CdromCollection objects govern the interface to the CD drives in your computer for purposes of reading and playing CDs.

The CdromCollection object is accessed only through the cdromCollection property of the Player object. The cdromCollection property returns the CdromCollection object. You can only access the properties of the CdromCollection object after you have created it. For example, to use the count property, you must use the following code:

mycount = player.cdromcollection.count;

You can only access the Cdrom object through the CdromCollection object. For example, to eject the CD by using the Eject method, you must first create the collection object and then an item in the object. To eject the CD, use the following code:

player.cdromcollection.item(0).eject();

In both cases, you are first creating the collection object (CdromCollection) and then getting a specific object of that collection. The object is the first item in the collection, Item(0), which corresponds to the first CD drive. You then call a method, Eject, on that item.

About the ClosedCaption Object

The ClosedCaption object governs the captioning interface for Windows Media Player. The ClosedCaption object is obtained through the closedCaption property of the Player object. For example, to get the SAMIFileName property value, type the following:

myfile = player.closedcaption.SAMIFileName;

About the Controls Object

The Controls object governs the transport of digital media content through the control by using methods such as Play and Stop. It is accessed only through the Controls property of the Player object. The Controls property returns the Controls object. You can only access the properties of the Controls object after you have created it. For example, to use the Play method, you must use the following code:

player.controls.play();

About the DVD Object

The DVD object adds functionality specific to DVD media. In a general sense, DVD media is treated just like other digital media in Windows Media Player. For instance, DVD drives are enumerated using the CdromCollection object and DVD titles and chapters are manipulated using Playlist objects and Media objects. Some functionality is DVD-specific, however, and the DVD object provides this. For example, DVD has a concept called domain. To retrieve the current domain for DVD media, type the following:

mydomain = player.dvd.domain;

About the Error and ErrorItem Objects

The Error and ErrorItem objects govern the error-handling capabilities of Windows Media Player. The Error object is obtained from the Player object through the error property. You can get a specific code from the Error object by using the item property of the Error object to create the ErrorItem object. For example, to get the error code of the first error item, type:

myerrorcode = player.error.item(0).errorCode;

You can also invoke Web Help with the Error object by using the following code:

player.error.webHelp();

About the MediaCollection and Media Objects

The MediaCollection and Media objects govern the media collection, which defines the locations of digital media files that Windows Media Player can access. You get the MediaCollection object from the mediaCollection property of the Player object. The mediaCollection property returns the MediaCollection object. You can only access the properties of the MediaCollection object after you have created it. For example, to add a Media object (a song), use the following code:

player.mediacollection.add('laure.wma');

You have added the file laure.wma to the media collection.

You can get the current Media object by using the currentMedia property of the Player. For example, this code gets the duration property of the current Media object:

myduration = player.currentmedia.duration;

There are many ways to get a Media object so that you can access its properties. For example, if you want to access the duration property of the current media, each of the following lines of code could be used.

To get the duration of the currently playing media:

player.currentMedia.duration;

To get the duration of the current media in a playlist:

player.controls.currentItem.duration;

To get the duration of the third media item in a playlist:

player.currentPlaylist.item(2).duration;

To get the duration of the third media item in a "Jazz" genre:

player.mediaCollection.getByGenre("jazz").item(2).duration;

To get the duration of the third media item in the second playlist:

player.playlistCollection.getAll.item(1).item(2).duration;

About the MetadataPicture Object

The WM/Picture metadata attribute provides detailed information about metadata images, such as album art. The MetadataPicture object provides a way to retrieve the individual data related to the image. You might think of the WM/Picture metadata attribute as a compound attribute. When you use Media.getItemInfoByType to retrieve information about a metadata image, you retrieve a MetadataPicture object that has properties which contain the individual data.

About the MetadataText Object

Some metadata attributes, such as WM/Lyrics_Synchronised, provide text accompanied by a description of the text. The MetadataText object provides a way to retrieve the text and the description separately. When you use Media.getItemInfoByType to retrieve information about complex textual attributes, you retrieve a MetadataText object that has properties, which contain the individual data.

About the Network Object

The Network object governs the properties that allow you to determine how well the content is streaming through the network. For example, you can find out whether packets are being lost and take appropriate action. The Network object is accessed only through the network property of the Player object. The network property returns the Network object. You can only access the properties of the Network object after you have created it. For example, to use the Bandwidth property, you must use the following code:

mybandwidth = player.network.bandwidth; About the Player Object

The Player object is the core object for the Windows Media Player control. All other related objects are connected to this object through specific properties that return the object. For example, the Settings object is accessed through the settings property. The Player object provides methods, properties, and events that relate to the core functionality of Windows Media Player.

Because this reference is also to be used for skins programming, the ID of the Player object will be "player" for syntax examples.

Using the player global attribute within a skin definition file gives access to the Player object for use in scripting. Through the Player object, all other objects in the Windows Media Player control become accessible to scripts as well. The events of the Player object and the URL property can also be specified at design time using the PLAYER skin element. For more information, see Windows Media Player Skins.

About the PlayerApplication Object

The PlayerApplication object is used for remoting Windows Media Player. It provides the functionality required to switch between a remoted Windows Media Player control and the full mode of the Player.

Remoting enables a Windows Media Player control embedded in a C++ application to use the same playback engine as the Player. This means that usually you will use the PlayerApplication object in C++ code using the COM interfaces. There is a special case, however, where you can embed the Windows Media Player control that displays a Windows Media Player skin as its user interface. In this case, PlayerApplication can be programmed using JScript in the skin code.

About the Playlist, PlaylistCollection, and PlaylistArray Objects

The Playlist, PlaylistCollection, and PlaylistArray objects govern the playlists that Windows Media Player can use to specify the order in which content will be played. You get the PlaylistCollection object from the playlistCollection property of the Player object. The playlistCollection property returns the PlaylistCollection object. You can only access the properties of the PlaylistCollection object after you have created it. For example, to create a new playlist, you must first get the PlaylistCollection object and then use a method on that object.

player.playlistcollection.newplaylist('myplaylist');

You can get the current playlist by using the currentPlaylist property. For example, to get the name of the current playlist, use the following code:

myname = player.currentplaylist.name;

The PlaylistArray object is returned by the getAll and getByName methods of the PlaylistCollection object. To get the number of playlists, for example, use the following code:

howmany = player.playlistcollection.getAll().count;

To retrieve a known playlist by name, use the following code:

if (player.playlistcollection.getbyname('myplaylist').count == 1) {
pl = player.playlistcollection.getbyname('myplaylist').item(0);
} About the Query Object

The Query object represents a compound query. You create a new, empty Query object by calling mediaCollection.createQuery. After you have created a Query object, you can call addCondition to add a condition to the compound query. Each subsequent call to addCondition appends a new condition to the existing query using AND logic.

For example, suppose you want to create a query that represents all digital media where WM/Genre equals "Jazz" and Author contains "Jim". You could create a compound query to represent these conditions by using the following JScript code:

// Create the query object. var Query = player.mediaCollection.createQuery(); // Add the conditions. Query.addCondition("WM/Genre", "Equals", "Jazz"); Query.addCondition("Author", "Contains", "Jim");

To add a condition to a compound query using OR logic, you must call Query.beginNextGroup. This method signals that the previous condition group is completed and that the next call to addCondition represents the start of a new condition group.

For example, to create a query that represents all digital media where WM/Genre equals "Jazz" and Author contains "Jim" or Author contains "Dave", you could use the following example code:

// Create the query object. var Query = player.mediaCollection.createQuery(); // Add the conditions. Query.addCondition("WM/Genre", "Equals", "Jazz"); Query.addCondition("Author", "Contains", "Jim"); // Start the next condition group. This group will be // combined with the previous group using a logical OR operation. Query.beginNextGroup(); // Add the conditions. Query.addCondition("WM/Genre", "Equals", "Jazz"); Query.addCondition("Author", "Contains", "Dave");

To execute your compound query, call MediaCollection.getPlaylistByQuery.

About the Settings Object

The Settings object governs the settings of the control such as volume, play count, mute, and so on. It is accessed only through the Settings property of the Player object. The Settings property returns the Settings object. You can only access the properties of the Settings object after you have created it. For example, to get the value of the Volume property, you must use the following code:

myvolume = player.settings.volume; About the StringCollection Object

The StringCollection object governs string collections, which are used to provide string handling capabilities for the MediaCollection object. The StringCollection object can be retrieved through the getAttributeStringCollection method of the MediaCollection object. You can use this to work with string collections representing the values of various media item attributes.

2007年8月10日

總結

以上是生活随笔為你收集整理的【翻】【英汉对照】【完整官方参考】Windows媒体播放器11 SDK 播放器对象模型（三）的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。