Chapter 2: RealOne Player Methods

This chapter provides a alphabetized reference to the methods you can use in the RealOne Player environment. For an overview of the methods, see "Using Javascript and ActiveX in the RealOne Player Environment".

AddToNowPlaying

Opens the "Now Playing" list and adds a URL to the clip list after the current clip. Optionally, it displays an associated URL in the related info pane with the specified height and width when the added clip plays, and a URL to the media browser pane. Available as a Javascript extension and an ActiveX control.

AddToNowPlaying(url, clipinfo, related_info_url, width, height, media_browser_url, target)

url

String containing the URL to add to the the RealOne Player clip list. This parameter is required.

clipinfo

String of extra clip information, such as title, author, and so on. This parameter contains a string of name-value pairs, <keyword=value>, separated by pipes. This parameter is optional. Valid keywords for clipinfo are:

Album name

Artist name

CDNum

Comments

Genre

Language

Mood

Preference

Situation

Title

Year

Example:

"Title=XXX|Artist name=XXX|Album name=XXX|Genre=XXX;"

Note: Each keyword/value pair is separated by the pipe symbol ( | ). For each entry to work correctly, you must ensure there are no spaces before or after each pipe symbol.

related_info_url

String containing the URL to display in the related info pane when the added clip plays. This parameter is optional.

width

Integer that specifies the width of the related info pane in pixels. This parameter is not required, but its use is recommended. If no width is specified, the width defaults to 320 pixels

height

Integer that specifies the height of the related info pane in pixels. This parameter is not required, but its use is recommended. If no height is specified, RealOne Player uses the height of the media presentation.

media_browser_url

String containing a URL to display in the URL designated by the target parameter. This parameter is optional.

target

Optional string indicating the pane in which to open the URL given in the media_browser_url parameter. If this string is set to _rpbrowser, the URL is opened in the media browser pane. Any other target name displays the URL in a secondary browsing window.

ClearNowPlaying

Clears the RealOne Player's current playlist and stops any clips currently playing. You should call this method before using any of the other methods to synchronize playback. Available as a Javascript extension and an ActiveX control.

ClearNowPlaying()

Returns void.

Note: Currently, this method must be used without parentheses at the end of the method name.

ComponentVersion

Returns the version of an updated component in packed form. Available as a Javascript extension and an ActiveX control.

ComponentVersion( name )

name

The name of the component to be examined. This parameter must be specified in the following format:

[name]:[major version].[minor version]

The following table identifies the possible values for component names. The values are case-sensitive and must be entered exactly as they appear below.

Component Names
Name	Component
`audp`	Extra audio plugin
`DBCMpg1`	MPEG video plugin
`Flash`	Macromedia Flash plugin
`GF`	GIF plugin (for backwards compatibility)
`GFJP`	JPG plugin (for backwards compatibility)
`imgp`	All image plugin (gif, jpg, png)
`MP3PL`	MP3 Playlist plugin
`MPGA`	MP3 Audio plugin
`PNG`	PNG plugin (for backwards compatibility)
`RA`	RealAudio
`RealTxt`	RealText
`RichFX`	RichFX plugin
`RPix`	RealPix
`RV`	RealVideo
`sdp`	Scalable Multi-cast plugin
`vidp`	Extra video plugin

Note: This list is not exhaustive because components are being added to RealOne Player all the time. This list will be updated as available, but you should contact RealNetworks if you have a special need.

For example, use the following to check the version of the Flash 6.0 plugin:

window.parent.external.ComponentVersion(`Flash:6.0')

Returns a string that contains the version of the component in packed form. This information could then be used to determine if the plugin meets the minimum requirements to play a requested presentation. If not, an upgrade request could be initiated.

To unpack this number into a more readable form, use the UnpackVersionNumber function, described in "Unpacking Version Information", as follows:

UnpackVersionNumber(window.parent.external.ComponentVersion('RA:6.0'))

GetClipInfo

Retrieves the specified value of the clip information as authored by the media provider in a string format. This method only works for clips launched from HTML in the related info pane. Available as a Javascript extension.

GetClipInfo( property )

property

Specifies the requested information. One of the following:

Album name

Artist name

CDNum

Comments

Genre

Language

Mood

Preference

Situation

Title

Year

Returns a string suitable for insertion as part of the HTML in the related info pane.

GetPlayerState

Gets the player's current state. Available as a Javascript extension.

GetPlayerState( )

Returns an integer that describes the player's current state. One of the following:


Value	Description
`0`	Indicates the player is currently stopped.
`1`	Indicates the player is currently contacting.
`2`	Indicates the player is currently buffering.
`3`	Indicates the player is currently playing.
`4`	Indicates the player is currently paused.
`5`	Indicates the player is currently seeking.
`6`	Indicates the player is busy showing a modal dialog box.

HandleAction

Performs a specified action. Available as a Javascript extension and an ActiveX control.

HandleAction( action )

action

The specific action to perform. One of the following:


Action	Performs the Following
`CD`	Opens the CD tab in the player.
`MyDevices`	Opens the Devices tab in the player.
`MyLibrary`	Opens the My Library tab in the player.
`NavigateToURL( url, target )`	Opens the specified URL in the specified target pane. The target pane can be defined as either `_rpbrowser` or `_rpexternal`.
`NowPlaying`	Opens the "Now Playing" list.
`Radio`	Opens the Radio tab in the player.
`ShowArtistInfo ( show )`	Shows or hides the artist information for the current clip. If show is set to `0`, the artist information is hidden. If `show` is set to `1`, the artist information is shown.
`ShowEqualizer`	Brings up the player's Equalizer dialog box.
`ShowPreferences( category, page )`	Brings up the player's Preferences dialog box to the selected category and page. Category and page combinations are described below.
`Web`	Opens the Web tab in the player.

The ShowPreferences action can take one of the following category and page pairs:


Category, Page	Performs the Following
`General,General`	Opens the Preferences dialog box to the General category.
`Connection,Connection`	Opens the Preferences dialog box to the main Connection category.
`Connection,Playback Settings`	Opens the Preferences dialog box to the Playback Settings page of the Connection category.
`Connection,Internet Settings`	Opens the Preferences dialog box to the Internet Settings page of the Connection category.
`Connection,Proxy`	Opens the Preferences dialog box to the Proxy page of the Connection category.
`Connection,Network Transports`	Opens the Preferences dialog box to the Network Transports page of the Connection category.
`My Library,My Library`	Opens the Preferences dialog box to the My Library category.
`My Library,Advanced My Library`	Opens the Preferences dialog box to the Advanced My Library page of the My Library category.
`CD,CD`	Opens the Preferences dialog box to the CD category.
`CD,Advanced CD`	Opens the Preferences dialog box to the Advanced CD page of the CD category.
`Devices,Devices`	Opens the Preferences dialog box to the Devices category.
`Accessories,Accessories`	Opens the Preferences dialog box to the Accessories category.
`Media Types,Media Types`	Opens the Preferences dialog box to the Media Types category.
`Content,Content`	Opens the Preferences dialog box to the Content category.
`Hardware,Hardware`	Opens the Preferences dialog box to the Hardware category.
`AutoUpdate,AutoUpdate`	Opens the Preferences dialog box to the AutoUpdate category.

Note: Each of the category and page pairs must be capitalized as shown. In addition, there cannot be a space between the category and the comma, nor between the comma and the page.

InstalledComponents

Returns a list of the DLLs and their associated version numbers installed by RealOne Player. Available as a Javascript extension and an ActiveX control.

InstalledComponents()

Note: Currently, this method must be used without parenthesis at the end of the method name.

Returns a string containing the all of the DLLs installed by RealOne Player and their associated version numbers. The component type and version number are separated by a colon ( : ). Each DLL is separated by a pipe symbol ( | ). The following example demonstrates a possible return value:

athdb:7.0.0.231|Update:7.0.0.960|ath:7.0.0.231|RNAdmin:0.1.0.548|MSG:7.0.0.552|PNCRT:6.0.0.0|RMACore:6.0.9.138|vsrc:6.0.7.2119|DRMLite:6.0.8.1860|Player:6.0.10.319|Free:6.0.10.319|RA:6.0.9.145|RV:6.0.9.145|Flash:6.0.8.2144|Embed:6.0.8.1413|RealTxt:6.0.7.2232|imgp:6.0.7.2225|PNG:6.0.7.2061|GF:6.0.7.2236|RPix:6.0.7.2217|GFJP:6.0.7.2236

OpenURLInPlayerBrowser

Opens the specified URL in the media browser pane. Available as a Javascript extension and an ActiveX control.

OpenURLInPlayerBrowser( url )

url

Specifies the URL to open in the media browser pane.

PlayClip

Plays a clip from the specified URL in the media playback pane. Optionally sends a URL to the related info pane with the specified height and width. In addition, a URL can be displayed in the media browser pane or a secondary window. Available as a Javascript extension and an ActiveX control.

PlayClip(url, clipinfo, related_info_url, width, height, media_browser_url, target, bnow_playing)

url

String containing the URL to play in the media playback pane. This parameter is required.

clipinfo

String of extra clip information, such as title, author, and so on. This parameter is entered as a string of name-value pairs, <keyword, value>, separated by pipes. This parameter is optional. Valid keywords for this parameter are:

Album name

Artist name

CDNum

Comments

Genre

Language

Mood

Preference

Situation

Title

Year

The following example demonstrates a possible entry for the clipinfo parameter:

"Title=XXX|Artist name=XXX|Album name=XXX|Genre=XXX;"

Note: Each keyword/value pair is separated by the pipe symbol ( | ). For each entry to work correctly, you must ensure there are no spaces before or after each pipe symbol.

related_info_url

String containing the URL to display in the related info pane. Use the reserved value "_keep" to keep the last web page loaded in the related info pane. This parameter is optional.

Note: RealOne Player caches related info pane URLs associated with a presentation. This cache is flushed when a new presentation begins.

width

Integer that specifies the width of the related info pane in pixels. This parameter is not required, but its use is recommended. If no width is specified, the width defaults to 320 pixels.

height

media_browser_url

String containing the URL to display in the pane designated by the target parameter.

target

String indicating the pane in which to open the URL given in the media_browser_url parameter. If this string is set to _rpbrowser, the URL is opened in the media browser pane. Any other target name displays the URL in a secondary browsing window.

bnow_playing

Boolean that specifies if a clip is added to the Now Playing list. If set to true (default), the clip is added to the Now Playing list. If set to false, the clip is not added.

Although you can use an <A HREF> in your HTML to link to a .ram file, you should use the PlayClip method instead. If you use <A HREF>, a browser is first invoked, which in turn invokes RealOne Player. If you use the PlayClip method, RealOne Player is invoked directly, which avoids intermediate dialogs being displayed.

PlayerProperty

Retrieves the value of the specified property. Available as a Javascript extension and an ActiveX control.

PlayerPropery( property )

property

A string that specifies the appropriate player property. One of the following:


Property	Performs the Following
`APIVERSION`	Gets the version of the player's Javascript extensions.
`BANDWIDTH`	Gets the user's bandwidth setting.
`COUNTRYID`	Gets the country name.
`DISTRIBUTION CODE`	Gets the OEM distribution code.
`INSTALLPATH`	Gets the full path to the player's installation directory.
`LANGUAGEID`	Gets the language of the installed player.
`LANGUAGEPREFERENCE`	Gets the user's preferred language.
`OSNAME`	Gets the computer's operating system name, such as Win98.
`PRODUCTNAME`	Gets the name of the installed player, such as RealOne Player.
`PRODUCTVERSION`	Gets the version of the installed player, for example, 6.0.10.448.
`REGIONDATE`	Gets the Zip or postal code.

Returns the value of the specified property as either a string or int32 (as appropriate).

PreloadURL

Caches URLs to be used later during playback. Caching these URLs enables a quicker display time during media playback without reducing bandwidth during streaming. Available as a Javascript extension.

PreloadURL( url )

url

Specifies the URL to cache.

The following example shows how you might cache two different URLs (www.example1.com and www.example2.com) before playback. These URLs could be referenced later using PROnPositionChange or other events.

<head>
<script language=Javascript>
    function RPOnPreload(){
        PreloadURL(http://www.example1.com)
        PreloadURL(http://www.example2.com)
        }
</script>
...

RealPlayerVersion

Retrieves the version number of the installed RealOne Player in packed format. This number indicates the major and minor version information of RealOne Player. Available as a Javascript extension and an ActiveX control.

RealPlayerVersion()

Note: Currently, this method must be used without parenthesis at the end of the method name.

Returns an integer containing the packed form of the RealOne Player version information. This information can then be compared against the minimum version number required to view your presentation.

Use the UnpackVersionNumber function described in "Unpacking Version Information" to display the number as a string. The string returned by UnpackVersionNumber is the same as that displayed in the Help>About RealOne Player dialog.

SetVideoBackgroundColor

Sets the video background color to the specified value. Available as a Javascript extension.

SetVideoBackgroundColor( color )

color

The color value specified in either RGB format, for example "RGB(r,g,b)", or as a hexidecimal value in the format "#RRGGBB", such as "#FFFFFF".

Returns void.