Chapter 3: Methods

An application, applet, or control can use the following methods to communicate with RealPlayer G2. For method data types, refer to RAPlayer.java, included in the rpcl3260.zip file installed in the RealPlayer folder. RealPlayer 5.0 supports a limited set of these methods as described in "RealPlayer 5.0 Compatibility".

Playback Commands

DoPlay()

Plays the current clip. Equivalent to clicking the Play button.

CanPlay()

Returns TRUE or FALSE. Returns TRUE if the player is currently paused or stopped, and current source file is valid.

DoStop()

Stops the clip. Equivalent to clicking the Stop button. This method is backwards-compatible with RealPlayer 5.0.

CanStop()

Returns TRUE if RealPlayer is currently playing a clip or is paused. This method is backwards-compatible with RealPlayer 5.0.

DoPause()

Pauses the current clip. Equivalent to clicking the Pause button.

CanPause()

Returns TRUE if the player is currently playing a clip.

CanPlayPause()

Returns TRUE if the player is currently playing, paused, or stopped, and current source file is valid. Backwards-compatible with RealPlayer 5.0. If supporting only RealPlayer G2, use CanPause() and CanPlay() instead.

DoPlayPause()

Plays or pauses the current clip. Backwards-compatible with RealPlayer 5.0. If supporting only RealPlayer G2, use DoPause() and DoPlay() instead.

PlayState Information

GetPlayState()

Returns the current state of the RealPlayer. Values are numerical, with the following meanings:

0 Stopped
1 Contacting
2 Buffering
3 Playing
4 Paused
5 Seeking

GetBufferingTimeElapsed()

Returns number of milliseconds of elapsed buffering time.

	Note
	The GetBufferingtimeElapsed() method is not currently supported. It will be supported in an upcoming release.

GetBufferingTimeRemaining()

Returns estimated remaining buffering time in milliseconds.

Attributes

GetPreFetch()

Returns whether or not PreFetch is enabled.

SetPreFetch()

Enables/disables PreFetch playback mode. Valid values are TRUE and FALSE with FALSE as the default.

	Additional Information
	See "Using PREFETCH with <EMBED>" or "Using PREFETCH with <OBJECT>".

GetControls()

Returns the visible components of the control.

	Additional Information
	For valid control names, see the chapter on Web page playback in RealSystem G2 Production Guide at http:// service.real.com/help/library/index.html.

SetControls()

Sets the visible components of the control. Compatible only with RealPlayer G2.

SetControlString()

Sets the visible components of the control. Method is identical to SetControls(), but is compatible with RealPlayer 5.0 Netscape Plug-in (though not the 5.0 ActiveX control). If supporting only RealPlayer G2, use SetControls() instead.

GetConsole()

Returns a console name used to link multiple control instances. Call this function once for each instance of a control you want to link.

SetConsole()

Sets a console name used to link multiple control instances. Call this once for each instance of a control you want to link. All controls with the same console name work together. For example, if you have multiple Play and Stop buttons on the same page, a shared console name enables them to control the same clip. The console name _master links to all instances. The console name _unique links to no other instances.

SetConsoleName()

Functionally identical to SetConsole(), but backwards-compatible with RealPlayer 5.0 Netscape plug-in (though not the 5.0 ActiveX control). If supporting only RealPlayer G2, use SetConsole() instead.

SetAutoStart(boolean autoStart)

Sets whether or not the control automatically starts playing once the source data is available. Valid values are TRUE and FALSE. This method is compatible with the RealPlayer 5.0 Netscape Plug-in but not its ActiveX control.

GetAutoStart()

Returns whether or not playback will start automatically.

SetAutoGoToURL()

Specifies how a URL will be handled. This method is backwards-compatible with RealPlayer 5.0. Valid values are:

• TRUE

  RealPlayer plug-in automatically forwards URL event to browser.

• FALSE

  onGoToURL() event handled by Java applet or VBScript instead.

  	Additional Information
  	With RealPlayer G2, this can also be set with the AUTOGOTOURL parameter in the <EMBED> or <OBJECT> tag. See "Handling URLs through <EMBED>" or "Handling URLs through <OBJECT>".

GetAutoGotoURL()

Returns whether or not AutoGotoURL property is enabled.

DoGoToURL(url, target)

For the RealPlayer 5.0 and G2 ActiveX control only, this method causes the control to attempt a navigation to the specified URL in the specified frame target. The container must support URL browsing. Parameters are:

string URL

string target

SetLoop()

Specifies whether the clip will loop or not. Valid values are TRUE (loops until play is interrupted) and FALSE (default).

GetLoop()

Returns whether the clip has been set to loop.

SetNumLoop()

Sets number of times to loop the clip. Takes an integer as its parameter.

GetNumLoop()

Returns number of loops set in SetNumLoop().

SetCenter()

Sets whether or not the visual datatype should be centered at its natural size within the image window. Valid values are TRUE and FALSE (default).

GetCenter()

Returns whether or not the visual datatype will be centered within the image window. Valid values are TRUE and FALSE.

SetMaintainAspect()

Maintains correct aspect ratio of source within image window when stretched. Valid values are TRUE and FALSE (default).

GetMaintainAspect()

Returns whether or not the aspect ratio of the visual datatype will be maintained.

SetBackgroundColor()

Specifies the desired background color for the image window control. Valid values are a RGB hexadecimal color value in the format #RRGGBB, or the following color names, shown here with their corresponding RGB values:

GetBackgroundColor()

Returns hexadecimal value for current background color.

SetNoLogo()

Determines whether to suppress the display of RealLogo in image window control. Image window defaults to black unless a background color has been specified. Valid values are TRUE and FALSE (default).

GetNoLogo()

Returns whether or not the RealLogo will be displayed in the image window.

SetNoLabels()

Suppresses the Title, Author, and Copyright label text in the controls window of RealPlayer 5.0. The content text strings are still displayed. This method does not affect RealPlayer G2 but is compatible with it.

GetNoLabels()

Returns whether or not Title, Author, and Copyright labels will be suppressed.

SetShuffle()

Randomizes playback of all clips, excluding clips that have already played. Works for multiclip RAM files (.ram or .rpm) or SMIL files that contain only a sequence of clips. Valid values are TRUE and FALSE.

GetShuffle()

Returns whether shuffle play is enabled.

SetSource(String Source)

Specifies the URL of the clip to play. The source URL can begin with rtsp://, http://, pnm://, or file://. This method is backwards-compatible with the RealPlayer 5.0 Netscape plug-in, though not the 5.0 ActiveX control.

GetSource()

Returns the URL of the playing clip.

SetCanSeek()

Sets whether the user can seek within the clip through the user interface. Valid values are TRUE (default) and FALSE. Live or simulated live clips are always FALSE.

GetCanSeek()

Live or simulated live clips return FALSE.

Clip Position

GetPosition()

Returns the current position in the clip in milliseconds. Valid values will be >=0 and <=total clip length.

SetPosition()

Seeks into the clip the specified point in milliseconds. Valid values are =0 and <total clip length.

If an attempt is made to set the position >total length, then SetPosition() will equal total length.

GetLength()

Returns the total length of the clip in milliseconds. Valid values are >=0.

Clip/TAC Information

GetTitle()

Returns the current clip's title string.

SetTitle()

Sets the current clip's title string, overriding any existing title information. GetTitle() subsequently returns this new value.

GetAuthor()

Returns the current clip's author string.

SetAuthor()

Sets the current clip's author string, overriding any existing author information. GetAuthor() subsequently returns this new value.

GetCopyright()

Returns the current clip's copyright string.

SetCopyright()

Sets the current clip's copyright string, overriding any existing copyright information. GetCopyright() subsequently returns this new value.

GetClipWidth()

Returns the width of the clip window in pixels.

GetClipHeight()

Returns the height of the clip window in pixels.

Playlist/Multiclip

HasNextEntry()

Tests if the next clip function is available. The next clip function is available when the connected source is a RAM (.ram or .rpm) or SMIL file that contains multiple clips and the current clip is not the last clip in the RAM or SMIL file. In a SMIL file, a <par> group is treated as a single clip. Returns TRUE or FALSE.

HasNextItem()

Tests if the next clip function is available. The next clip function is available when the connected source is a RAM (.ram or .rpm) or SMIL file that contains multiple clips and the current clip is not the last clip in the RAM or SMIL file. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use HasNextEntry() instead.

DoNextEntry()

Skips to the next clip in the RAM (.ram or .rpm) or SMIL file that contains multiple clips. In a SMIL file, a <par> group is treated as a single clip.

DoNextItem()

Skips to the next clip in the RAM (.ram or .rpm) or SMIL file that contains multiple clips. In a SMIL file, a <par> group is treated as a single clip. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use DoNextEntry() instead.

HasPrevEntry()

Tests if the previous clip function is available. The previous clip function is available when the connected source is a RAM (.ram or .rpm) or SMIL file that contains multiple clips and the current clip is not the first clip in the RAM file. In a SMIL file, a <par> group is treated as a single clip. Returns TRUE or FALSE.

HasPrevItem()

Tests if the previous clip function is available. The previous clip function is available when the connected source is a RAM (.ram or .rpm) or SMIL file that contains multiple clips and the current clip is not the first clip in the RAM file. In a SMIL file, a <par> group is treated as a single clip. Returns TRUE or FALSE. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use HasPrevEntry() instead.

DoPrevEntry()

Skips to the previous clip in a RAM (.ram or .rpm) or SMIL file that contains multiple clips. In a SMIL file, a <par> group is treated as a single clip.

DoPrevItem()

Skips to the previous clip in a RAM (.ram or .rpm) or SMIL file that contains multiple clips. In a SMIL file, a <par> group is treated as a single clip. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use DoPrevEntry() instead.

GetCurrentEntry()

Returns the number of the entry currently playing.

GetNumEntries()

Returns the total number of entries in the playlist.

GetEntryTitle()

Returns the Title for the specified playlist entry.

GetEntryAuthor()

Returns the Author for the specified playlist entry.

GetEntryCopyright()

Returns the Copyright for the specified playlist entry.

GetEntryAbstract()

Returns the Abstract for the specified playlist entry.

Live Playback

GetLiveState()

Returns whether the current clip is live. Valid values are TRUE or FALSE.

User Interface Components

SetShowStatistics()

Sets the RealPlayer Statistics dialog box to visible. Valid values are TRUE or FALSE.

GetShowStatistics()

Returns whether or not the RealPlayer Statistics dialog box is visible.

HideShowStatistics()

Sets the RealPlayer Statistics dialog box to visible. Valid values are TRUE (hidden) or FALSE. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use SetShowStatistics() instead.

IsStatisticsVisible()

Returns whether or not the RealPlayer Statistics dialog box is visible. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use GetShowStatistics() instead.

SetShowPreferences()

Displays the RealPlayer Preferences dialog box.

GetShowPreferences()

Returns whether or not the Preferences dialog box is visible.

EditPreferences()

Displays the RealPlayer Preferences dialog box. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use SetShowPreferences() instead.

SetShowAbout()

Displays the RealPlayer About dialog box. Use with RealPlayer G2 only.

AboutBox()

Displays the RealPlayer About dialog box. Use with RealPlayer G2 and 5.0. If supporting only RealPlayer G2, use SetShowAbout() instead.

GetShowAbout()

Returns whether or not the About box is open.

Error Handling

SetWantErrors()

Sets error sink. Valid values are TRUE (errors trapped, no error dialogs in player) and FALSE (error dialogs in player).

GetWantErrors()

Returns whether error dialogs will be displayed.

GetLastErrorMoreInfoURL()

Returns the "more info" URL from the last error. May return nothing.

GetLastErrorRMACode()

Returns RMA error code from the last error. RMA error codes are described in the header file pnresult.h in the RealSystem G2 SDK available at http://www.real.com/devzone/. In normal operation, all RealSystem components need to be able to handle the following basic codes that may be returned by the RealSystem system:

• PNR_FAIL-Operation failed.

• PNR_OK-Operation succeeded.

• PNR_UNEXPECTED-Call was unexpected or method is not implemented.

GetLastErrorSeverity()

Returns error level for last error.

GetLastErrorUserCode()

Returns user error code from last error.

GetLastErrorUserString()

Returns error string from last error dialog. May return nothing.

GetLastStatus()

Returns text of last status message.

Display State

SetOriginalSize()

Sets the image window to its original size.

GetOriginalSize()

Returns whether the image is currently in its original size. TRUE indicates original size.

SetDoubleSize()

Sets the image window to double size.

GetDoubleSize()

Returns whether or not image is currently in double-size mode. TRUE indicates double size.

SetFullScreen()

Sets the image to full-screen mode.

GetFullScreen()

Returns whether or not image is currently in full-screen mode. TRUE indicates full-screen mode.

Volume/Mute Control

SetVolume()

Sets the volume level. Valid values are 0-100.

GetVolume()

Returns current volume level.

SetMute()

Sets the mute state. Valid values are TRUE and FALSE.

GetMute()

Returns whether or not the volume has been muted.

GetStereoState()

Returns whether the current clip is in stereo. Returns TRUE for stereo or FALSE for mono.

Context Menu

SetEnableContextMenu()

Specifies whether the control will display the default context menu when the right mouse button is clicked. Valid values are TRUE (enabled, default) and FALSE (disabled).

GetEnableContextMenu()

Returns whether or not contextual menu is currently enabled. Returns TRUE (enabled, default) or FALSE (disabled).

SetEnableOriginalSize()

Enables the original size option on contextual menu. Valid values are TRUE (default) and FALSE.

GetEnableOriginalSize()

Returns whether the original size option is enabled on the contextual menu.

SetEnableDoubleSize()

Enables the double size option on contextual menu. Valid values are TRUE and FALSE (default).

GetEnableDoubleSize()

Returns whether or not the double size option is enabled on the contextual menu.

SetEnableFullScreen()

Enables the full screen option on contextual menu. Valid values are TRUE (default) and FALSE.

GetEnableFullScreen()

Returns whether or not the full screen option is enabled on the contextual menu.

SetImageStatus()

Sets whether Status text should be written to the image window.

GetImageStatus()

Returns whether Status text is written to the image window.

Network Information

GetSourceTransport()

Returns a string with the source protocol used for playback. Takes as value an integer from 1 to n, where n is the number of sources returned by GetNumSources().

GetNumSources()

Returns number of sources in the presentation.

GetPacketsTotal()

Returns total number of packets in the presentation.

GetPacketsReceived()

Returns the total packets received from the server.

GetPacketsOutofOrder()

Returns the total packets received from the server out of order.

GetPacketsMissing()

Returns the total packets not received from the server in time to play.

GetPacketsEarly()

Returns the total packets received from the server before they are ready to play.

GetPacketsLate()

Returns the total packets received from the server that are too late to play.

GetBandwidthAverage()

Returns the average amount of bandwidth available.

GetBandwidthCurrent()

Returns the current amount of bandwidth available.

Version Information

GetVersionInfo()

Returns major and minor version information for the embedded RealPlayer (not the parent RealPlayer), such as 6.0.0.128.

GetIsPlus()

Returns whether the client is RealPlayer Plus.

Event Flags

SetWantKeyboardEvents()

Sets whether keyboard events will be sent. Valid values are TRUE and FALSE (default).

GetWantKeyboardEvents()

Returns whether keyboard events will be sent.

SetWantMouseEvents()

Sets whether mouse events will be sent. Valid values are TRUE and FALSE (default).

GetWantMouseEvents()

Returns whether mouse events will be sent.

User Preference Settings

GetConnectionBandwidth()

Returns the normal, maximum bandwidths settings as set by the user in the RealPlayer preferences.

GetPreferedLanguageString()

Returns the preferred language for content as set by the user in the RealPlayer preferences.

GetPreferedLanguageID()

Returns the preferred language ID. For a list of language codes, see the SMIL language codes appendix in RealSystem G2 Production Guide.

GetUserCountryID()

Returns the country that the user selected during electronic registration.

RealPlayer 5.0 Compatibility

The following methods are used with RealPlayer G2 and RealPlayer 5.0. To support both versions of RealPlayer, your application can issue only this set of commands:

• DoStop()

• CanStop()

• CanPlayPause()

• DoPlayPause()

• DoGoToURL(url, target) (ActiveX control only)

• SetControlString() (Netscape Plug-in only)

• SetConsoleName() (Netscape Plug-in only)

• SetAutoStart(boolean autoStart) (Netscape Plug-in only)

• SetAutoGoToURL()

• SetNoLabels() (Netscape Plug-in only)

• SetSource(String Source) (Netscape Plug-in only)

• HasNextItem()

• DoPrevItem()

• HasPrevItem()

• DoPrevItem()

• AboutBox()

• EditPreferences()

• HideShowStatistics()

• IsStatisticsVisible()

Copyright © 1998 RealNetworks
For information on RealNetworks' technical support, click here.
Comments on this document? Click here.
This file last updated on 12/18/98 at 17:51:30.