【翻】【英汉对照】【完整官方参考】Windows媒体播放器11 SDK 播放器对象模型（三）

用于脚本语言的播放器对象模型

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日