Chapter 2: Using Methods and Callbacks

The Embedded RealPlayer controls have methods that can be called to control the playback of your embedded presentations and callback methods that can be used to handle events sent from the RealPlayer. This chapter provides a brief introduction to the methods and callbacks and describes how groups of related methods can be used together to enhance your embedded presentations.

Categories of Methods

The methods listed in Appendix A "Methods" are described here according to the usage category to which they belong. For example, all of the methods related to enabling application authors to determine the current playback status and to control playback of their presentation, are grouped together and described in the following section, "Controlling Playback".

Note: Obsolete methods are included in these categories, but are colored gray. Read the obsolete method's description to determine which method to use instead.

Controlling Playback

Play, pause, and stop the clip using your own controls or determine the clip playback status.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the playback.htm or playbac1.htm sample application.

If you want to supply your own play, pause, and stop controls for your embedded player instead of using the built-in controls, use the DoPlay, DoPause, and DoStop playback methods. The following example shows one simple way to add your own controls:

<INPUT TYPE="button" VALUE="Play" onClick="document.javademo.DoPlay()">
<INPUT TYPE="button" VALUE="Pause" onClick="document.javademo.DoPause()">
<INPUT TYPE="button" VALUE="Stop" onClick="document.javademo.DoStop()">

This category of methods can also be used to determine the playback status of the clip. The CanPlay, CanPause, and CanStop playback methods indicate whether the clip can be played, paused, or stopped. For example, if CanPlay returns true, it means the clip is either paused or stopped and the clip is ready to play. If CanPlay returns false, it means the clip is already playing and is not yet ready to begin playing again.

Obtaining Play State Information

Get the current play state of a presentation or determine the elapsed and remaining buffering times of a presentation.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the state.htm sample application.

RealPlayer provides a method for obtaining the current play state of a presentation on your Web page. In addition, you can determine the elapsed buffering time and remaining buffering time of a presentation.

GetPlayState returns an integer that indicates the current state of the RealPlayer. The possible play states denoted by the returned integer include:

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

Knowledge of the current presentation state can be very useful. For example, you could disable the image status text written along the bottom of the image window, and replace it with the current presentation state in a custom display panel.

Note: The image status text only appears along the bottom of the image window when no other control, such as a status panel or status field, is available to display the status text.

Like the information returned from GetPlayState, the information displayed along the bottom of the image window indicates whether the playback is contacting, buffering, and so on. To disable this text, set the SetImageStatus method's parameter to false. To determine whether the status text is currently enabled or disabled, use the GetImageStatus method. In addition,

Another example is to determine the amount of time that has elapsed since buffering began for a requested presentation. After the embedded player has contacted the host for the requested presentation, the player buffers the content to provide smooth playback of the presentation. You can obtain the elapsed time using the GetBufferingTimeElapsed method or determine the amount of buffering time remaining, using the GetBufferingTimeRemaining method.

Specifying Control Attributes

Get or set the current state of the embedded controls on your Web page.

Note: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the prefetch.htm, controls.htm, or console.htm sample application.

The attribute methods supply information about the current state of the embedded controls on your Web page, along with a means of dynamically changing the state of these controls. (These methods can also be used in programming languages, such as C++, to set the control's parameters.)

RealPlayer provides a series of "set" methods with which you can change the attributes of the player embedded on your Web page. Many of these "set" methods mirror the parameters used with the <EMBED> or <OBJECT> tag, and dynamically change the state of an embedded control. For example, SetBackgroundColor is the equivalent of the BACKGROUNDCOLOR parameter of the <EMBED> or <OBJECT> tag. You can use SetBackgroundColor to dynamically change the background color of an ImageWindow at any time.

The following methods are associated with the parameters used with the <EMBED> or <OBJECT> tag:

Other methods let you "get" the current state of the attributes of the player embedded on your Web page. For example, GetBackgroundColor returns a hexadecimal value for the current background color.

Seeking Through a Clip

Get the current clip position, total clip length, and determine if you can seek through the presentation.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the position.htm sample application.

The Embedded RealPlayer provides several methods that can be used to obtain information about the currently-playing clip, including determining the present clip position, total length, and whether you can seek through the presentation.

During playback, you can use the GetCanSeek method to verify whether you can seek through the clip. When the method returns true, you can then use the and GetPosition methods to obtain the clip length and current position in the clip. The actual length is returned as the total number of milliseconds in the clip. The position is returned as the number of milliseconds already played. You can also use the information returned from the GetLength method to ensure that the postion entered in the SetPosition method does not exceed the total length of the clip.

Another method that can be used when the GetCanSeek method returns true is SetCanSeek. This method allows you to specify whether a clip can be seeked. However, if you use the SetCanSeek method to allow seeking through an inherently unseekable clip, such as a live broadcast, the set method will have no effect.

Accessing Clip Title, Author, and Copyright Information

Get or set the title, author, and copyright statement for a clip.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the cliptac.htm sample application.

When a title, author, and copyright statement have been encoded in a clip, this information can be retrieved using the GetTitle, GetAuthor, and GetCopyright methods. In multi-clip presentations, these methods return the information associated with the currently-playing clip.

The SetTitle, Netscape OnlyNetscape OnlySetAuthor, and SetCopyright methods can be used to dynamically change whether the title, author, and copyright information for a clip is displayed. This information is normally displayed in the clip information control (the www.real.com Home Button control) for each clip. In multi-clip presentations, these methods override the clip information for the entire presentation, not just the currently-playing clip. These methods are useful if you are presenting a multi-clip presentation and want to supply your own title, author, and copyright information for the entire presentation.

Directing a Playlist in a Multi-clip Presentation

Get the playlist information about each clip in a presentation and use it to move from clip to clip in the playlist, or acquire information about any clip.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the playlist.htm sample application.

Multi-clip presentations are made up of playlists that contain useful information about each of the clips in the presentation. You can use this data to move from clip to clip in the playlist, or acquire content information about any clip in the presentation.

To get the number of entries in the playlist, use the GetNumEntries method. In this method, a single entry is always returned as the number 1. You can also retrieve the entry number of the clip that is currently playing using the GetCurrentEntry method. Note, however, that this method begins counting at zero, therefore the third entry in a playlist would return the number 2. While playing a multi-clip presentation, use the HasNextEntry method to determine if there is another entry in the playlist. You can then use the DoNextEntry method to jump to the next clip. Use the HasPrevEntry method to determine if a previous entry exists in the playlist. If so, you can then use the DoPrevEntry method to jump back to the beginning of the previous clip.

After you have determined the number of entries in a playlist, you can use the GetEntryAbstract, GetEntryAuthor, GetEntryCopyright, and GetEntryTitle methods to retrieve the abstract, author, copyright, and title information for any clip in the presentation. Simply supply the number of the playlist entry for which you want information as the parameter for these methods. These methods return a string that contains the information for the specified entry.

Determining Live Broadcast

Determine if the currently playing clip is a live presentation.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the liveplay.htm sample application.

The GetLiveState method indicates whether or not the current clip is a live presentation. This information could be useful, for instance, if you wanted to know whether to use the clip positioning methods. In this case, if GetLiveState returns true, that means the current clip is part of a live presentation, and you cannot use the clip positioning methods.

Display User Interface Dialogs

Use RealPlayer menus to set RealPlayer preferences, view playback statistics, or view information about the RealPlayer.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the playlist.htm sample application.

RealPlayer contains several menus that can be used to set various player preferences, view the playback statistics, and view information about the player.

You can access the player preferences using the SetShowPreferences method. Setting this method's parameter to true brings up an abbreviated version of the standard RealPlayer Preferences dialog box. To determine if the Preferences dialog box is already being displayed, use the GetShowPreferences method. If this method returns true, the Preferences dialog box is already being displayed.

To view the playback statistics, use the SetShowStatistics method. Setting this methods's parameter to true brings up the standard RealPlayer Statistics dialog box. To determine if the Statistics dialog box is already being displayed, use the GetShowStatistics method. If this method returns true, the Statistics dialog box is already being displayed.

RealPlayer's About dialog box contains information about the version of RealPlayer and its individual components being used in your embedded Web Page. To view the About dialog box, use the ActiveX OnlySetShowAbout method. Setting this method's parameter to true brings up the RealPlayer About dialog box. To determine if the About dialog box is already being displayed, use the ActiveX OnlyGetShowAbout method. If this method returns true, the About dialog box is already being displayed.

Error Handling

Specify whether errors detected by the RealPlayer should be trapped and displayed.

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the errors.htm sample application.

You can designate whether or not the RealPlayer embedded in your Web page displays error dialogs. If the SetWantErrors method is set to true, error messages from the player are trapped, and not displayed in an error dialog box. If SetWantErrors is set to false, error messages are displayed in an error dialog box. You can use the GetWantErrors method to determine if error messages are being trapped. If GetWantErrors returns true, error messages are being trapped. If GetWantErrors returns true, error message will be displayed when they occur.

When a player error occurs, the GetLastErrorMoreInfoURL method supplies a URL that can be used to provide more information than is provided by the standard error string.

If no URL is available to supply more information, this method returns nothing.

The GetLastErrorRMACode method returns a value that represents the error code returned by RealPlayer. The values of the error codes and their descriptions can be found in the RealSystem SDK rmaerror.h file and in the RealSystem SDK Developer's Guide.

Other RealPlayer error methods include GetLastErrorSeverity, which responds with the severity of the error, and GetLastStatus, which responds with the text of the last status message returned by the OnShowStatus callback.

Also included are two user-defined error methods: GetLastErrorUserCode and GetLastErrorUserString. The GetLastErrorUserCode returns a user-defined error code, and GetLastErrorUserString returns a user-defined string that describes the last error that occurred. If you have designed a custom plug-in for RealPlayer, you can use both of these methods to return your own error codes and error strings for your plug-in. If you are not providing a custom plug-in for RealPlayer, both of these methods return nothing.

Setting the Display Size

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the display.htm or context.htm sample application.

You can change the size of the image window on your Web page to either the original size you specified in the <EMBED> or <OBJECT> tag, or to full screen.

To set the image window to full screen, use the SetFullScreen method with its parameter set to true. To determine if the image window is set to full screen, use the GetFullScreen method. If this method returns true, the image window is set to full screen.

To set an image window to the original size specified in the <EMBED> or <OBJECT> tag on your Web page, use the SetOriginalSize method with its parameter set to true. To determine if the image window is currently set to its original size, use the GetOriginalSize method. If this method returns true, the image window is set to its original size.

The SetDoubleSize and GetDoubleSize methods are intended for advanced applications only. They have no effect within a Web page.

Controlling Audio

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the display.htm or context.htm sample application.

You can embed various audio controls in your Web page to get and set the volume of the presentation, mute the presentation, and determine if the presentation is being played in stereo or monaural.

To set the volume of the presentation, use the Netscape OnlySetVolume method. The parameter you enter for this method is a percentage of the total volume, that is, if you want the volume to be set to 50%, use the number 50 as this method's parameter. To determine the current volume of the presentation, use the Netscape OnlyGetVolume method. This method returns the current volume setting as a percentage of the total volume.

To mute the presentation, use the SetMute method. Set this method's parameter to true to mute the presentation, and false to return the sound volume to its previous level. To determine if the presentation is currently muted, use the GetMute method. This method returns true if the presentation is muted and false if it is not.

To determine if the current presentation is stereo or monaural, use the GetStereoState method. This method returns true if the presentation is stereo, and false if the presentation is monaural.

Controlling the Pop-up Context Menu

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the display.htm, state.htm, or context.htm sample application.

Every embedded control you include on your Web page contains a context menu that can be accessed by placing the mouse cursor over the control, then clicking the right button, or equivalent. This context menu contains selections to play, stop, or mute the presentation in the image window, along with selections that contain clip information in the presentation, zoom controls, access to the Preference and Statistics dialog boxes, and information about the player and presentation.

In some cases, you may have more than one set of <EMBED> or <OBJECT> tags on your Web page. For example, you could have two ImageWindow controls, each of which has its own unique play, pause, and stop button. Each set of controls would then have a unique CONSOLE parameter, one for the first ImageWindow and another for the second ImageWindow. All controls linked by the first CONSOLE name interact with each other, but not with the other set of controls on the Web page, which has a different CONSOLE name. Therefore, when you right-click on one of these controls to bring up the context menu, that menu only relates to the set linked by the CONSOLE name for the control on which you clicked.

The context menu is normally enabled. To disable the context menu so that it does not appear when the right mouse button is pressed, use the SetEnableContextMenu method. By setting this method's parameter to false, the context menu is disabled. To reenable the context menu, set this method's parameter to true. To determine whether the context menu is currently enabled or disabled, use the GetEnableContextMenu method.

You can also seperately enable or disable the zoom selections in the context menu. This may be useful if you want to prevent someone from using these menu selections on your presentation. You can disable each of the zoom selections using the SetEnableOriginalSize, SetEnableDoubleSize, and SetEnableFullScreen methods. If you set these method's parameters to false, the corresponding menu selection in the context menu is disabled and the selection is grayed. To reenable these menu selections, set the method's parameter to true. To determine the current setting of these menu selections, use the GetEnableOriginalSize, GetEnableDoubleSize, and GetEnableFullScreen methods.

Getting Network Information

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the network.htm sample application.

You can obtain information from a user's RealPlayer to determine how your Web page reacts to the user's network capabilities.

Two methods provide playback bandwidth information from the user's RealPlayer. The first, GetBandwidthAverage, returns the average playback bandwidth of the user's RealPlayer, in bits per second, from the beginning of playback to the time when this method is called. The second, GetBandwidthCurrent, returns the current playback bandwidth in bits per second.

The GetNumSources method returns the number of sources in the presentation, where a source is a piece of media or an entry in a playlist or .rpm file.

Several methods are provided that let your Web page monitor the network activity of the user's RealPlayer. GetPacketsReceived indicates the total number of packets that the player received correctly from the RealSystem Server, and GetPacketsTotal indicates the total number of packets that should have been received by the player up to the point at which this method was called, including the packets that were lost. If no packets were lost, GetPacketsTotal returns the same number as GetPacketsReceived.

You can also monitor how well the user's RealPlayer is receiving packets. GetPacketsEarly indicates the number of packets that were received early. GetPacketsLate indicates the number of packets that were received late. GetPacketsMissing indicates the number of packets that were never received. GetPacketsOutOfOrder indicates the number of packets that were received out of order.

GetSourceTransport returns the type of protocol used for the stream by the user's RealPlayer. This method either returns "udp" or "tcp", depending on the source transport.

Obtaining RealPlayer Version Information

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the version.htm sample application.

Two methods provide version information for the RealPlayer controls you have embedded on your web page.

The first, GetIsPlus, returns true if the version of the player playing back your presentation is RealPlayer Plus or false if the player is the basic RealPlayer. With this information, you could provide different options to the different types of players. Since the basic RealPlayer does not provide all of the options of RealPlayer Plus, your Web page could then respond differently to a user playing your presentation with RealPlayer Plus.

The second method that supplies version information is GetVersionInfo. This method returns the version of the RealPlayer plug-in running on the user's machine (in period-deliniated form, such as "6.0.7.788", which is the Embedded RealPlayer build for RealPlayer 8). With this information, your Web page can once again provide different options for different versions of the player.

The following table lists the equivalent RealPlayer releases, stand-alone builds, and embedded player builds. Use this information to differentiate between versions.

Event Handling

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the events.htm sample application.

RealPlayer includes methods for enabling or disabling keyboard and mouse events on your Web page. Also included is a method that can be used in plug- ins to make event handling act more like event handling in ActiveX controls.

Available Methods

The SetWantKeyboardEvents method sets whether or not keyboard events are returned from the user's RealPlayer. If SetWantKeyboardEvents is set to true, the keyboard event callbacks, OnKeyDown, OnKeyPress, and OnKeyUp, are sent from RealPlayer when a keyboard event occurs. If this method is set to false, keyboard events are not sent. You can use the GetWantKeyboardEvents method to determine if keyboard events have been requested from the user's RealPlayer.

The SetWantMouseEvents method works in much the same way. If SetWantMouseEvents is set to true, the mouse event callbacks, OnLButtonDown, OnLButtonUp, OnMouseMove, OnRButtonDown, and OnRButtonUp, are sent from RealPlayer when a mouse event occurs. If this method is set to false, mouse events are not sent. You can use the GetWantMouseEvents method to determine if mouse events have been requested from the user's RealPlayer.

The SetConsoleEvents method is provided to let plug-in designers make their plug-ins behave more like the ActiveX control. By setting the value parameter of the SetConsoleEvents method to false, only the plug-in to which the console connects will send events.

How Event Handling Works

In ActiveX, you specify the particular ActiveX control for which your function is handling events. Thus any event that occurs in reference to a specific ActiveX control is always handled only by that single control.

If, however, you are using multiple plug-ins on a page and an event occurs on that page, a Java applet cannot determine from which plug-in the event was sent. (Although you could add multiple Java applets to the page to handle each individual plug-in, in general all events for all plug-ins that share the same console name are sent to a single applet.) For example, if you have two plug-ins on a page and generate a mouse or button event in either of the plug- ins, the event goes to the applet, but the applet cannot determine which plug- in generated the event.

The SetConsoleEvents method does not affect ActiveX controls.

You can use the GetConsoleEvents method to determine whether console events are enabled. If GetConsoleEvents is true, then console events are enabled and events from any applet will be sent to the plug-in. If this method is set to false, console events are disabled and only the plug-in to which the console connects will send events.

Getting User Preference Settings

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the prefer.htm sample application.

Some of the preference settings from the RealPlayer Preferences dialog can be retrieved by your Web page. You can then use this information to customize your Web page to the preferences of the user's RealPlayer.

The GetConnectionBandwidth method returns the value of the user's RealPlayer connection bandwidth preference in milliseconds. You can use this information to determine whether your presentation will play properly on the user's RealPlayer (in the case of a single bandwidth presentation) or to determine the optimal playback bandwith (in the case of SureStream content).

The GetPreferredLanguageString method returns a string that identifies the preferred language for content as specified by the user under the Content tab of her RealPlayer Preferences dialog. The user's RealPlayer returns a string of the form "xx-yy, xx, *". You can use the "xx-yy" portion of the string to determine the user's preferred language. For example, English (United States) returns the raw string "en-us, en, *", of which "en-us" refers to the preferred language. A complete list of all the language preferences that can be set by RealPlayer can be found in the SMIL language codes appendix of the RealSystem Production Guide.

Note: Some versions of RealPlayer return portions of the preferred language string as capital letters. You should design your Web page to handle these capital letters appropriately when comparing these returned stings against a table of known languages.

GetPreferredLanguageID and GetUserCountryID return standardized language identifications and standard country identifications. In Windows, these returned values are defined in olenls.h.

Categories of Callback Methods

The methods listed in Appendix B "Callback Methods" are described here according to the usage category to which they belong. For example, all of the methods related to detecting changes to a presentation, are grouped together and described in the following section, "Detecting Changes in Presentation Data".

Note: Obsolete callback methods are included in these categories, but are colored gray. Read the obsolete method's description to determine which method to use instead.

Detecting Changes in Presentation Data

.....

When a title, author, and copyright statement have been encoded in a clip, this information can be retrieved using the GetTitle, GetAuthor, and GetCopyright methods. In multi-clip presentations, these methods return the information associated with the currently-playing clip.

The SetTitle, Netscape OnlyNetscape OnlySetAuthor, and SetCopyright methods can be used to dynamically change whether the title, author, and copyright information for a clip is displayed. This information is normally displayed in the clip information control (the www.real.com Home Button control) for each clip. In multi-clip presentations, these methods override the clip information for the entire presentation, not just the currently-playing clip. These methods are useful if you are presenting a multi-clip presentation and want to supply your own title, author, and copyright information for the entire presentation.

Event Handling

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the events.htm sample application.

RealPlayer includes methods for enabling or disabling keyboard and mouse events on your Web page. Also included is a method that can be used in plug- ins to make event handling act more like event handling in ActiveX controls.

Available Methods

The SetWantKeyboardEvents method sets whether or not keyboard events are returned from the user's RealPlayer. If SetWantKeyboardEvents is set to true, the keyboard event callbacks, OnKeyDown, OnKeyPress, and OnKeyUp, are sent from RealPlayer when a keyboard event occurs. If this method is set to false, keyboard events are not sent. You can use the GetWantKeyboardEvents method to determine if keyboard events have been requested from the user's RealPlayer.

The SetWantMouseEvents method works in much the same way. If SetWantMouseEvents is set to true, the mouse event callbacks, OnLButtonDown, OnLButtonUp, OnMouseMove, OnRButtonDown, and OnRButtonUp, are sent from RealPlayer when a mouse event occurs. If this method is set to false, mouse events are not sent. You can use the GetWantMouseEvents method to determine if mouse events have been requested from the user's RealPlayer.

The SetConsoleEvents method is provided to let plug-in designers make their plug-ins behave more like the ActiveX control. By setting the value parameter of the SetConsoleEvents method to false, only the plug-in to which the console connects will send events.

How Event Handling Works

In ActiveX, you specify the particular ActiveX control for which your function is handling events. Thus any event that occurs in reference to a specific ActiveX control is always handled only by that single control.

If, however, you are using multiple plug-ins on a page and an event occurs on that page, a Java applet cannot determine from which plug-in the event was sent. (Although you could add multiple Java applets to the page to handle each individual plug-in, in general all events for all plug-ins that share the same console name are sent to a single applet.) For example, if you have two plug-ins on a page and generate a mouse or button event in either of the plug- ins, the event goes to the applet, but the applet cannot determine which plug- in generated the event.

The SetConsoleEvents method does not affect ActiveX controls.

You can use the GetConsoleEvents method to determine whether console events are enabled. If GetConsoleEvents is true, then console events are enabled and events from any applet will be sent to the plug-in. If this method is set to false, console events are disabled and only the plug-in to which the console connects will send events.

Controlling Audio

.....

You can embed various audio controls in your Web page to get and set the volume of the presentation, mute the presentation, and determine if the presentation is being played in stereo or monaural.

To set the volume of the presentation, use the Netscape OnlySetVolume method. The parameter you enter for this method is a percentage of the total volume, that is, if you want the volume to be set to 50%, use the number 50 as this method's parameter. To determine the current volume of the presentation, use the Netscape OnlyGetVolume method. This method returns the current volume setting as a percentage of the total volume.

To mute the presentation, use the SetMute method. Set this method's parameter to true to mute the presentation, and false to return the sound volume to its previous level. To determine if the presentation is currently muted, use the GetMute method. This method returns true if the presentation is muted and false if it is not.

To determine if the current presentation is stereo or monaural, use the GetStereoState method. This method returns true if the presentation is stereo, and false if the presentation is monaural.

Obtaining Play State Information

.....

For More Information: For a demonstration of how to use one or more of these methods in a Netscape plug-in, see the prefetch.htm sample application.

RealPlayer provides a method for obtaining the current play state of a presentation on your Web page. In addition, you can determine the elapsed buffering time and remaining buffering time of a presentation.

GetPlayState returns an integer that indicates the current state of the RealPlayer. The possible play states denoted by the returned integer include:

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

Knowledge of the current presentation state can be very useful. For example, you could disable the image status text written along the bottom of the image window, and replace it with the current presentation state in a custom display panel.

Note: The image status text only appears along the bottom of the image window when no other control, such as a status panel or status field, is available to display the status text.

Like the information returned from GetPlayState, the information displayed along the bottom of the image window indicates whether the playback is contacting, buffering, and so on. To disable this text, set the SetImageStatus method's parameter to false. To determine whether the status text is currently enabled or disabled, use the GetImageStatus method. In addition,

Another example is to determine the amount of time that has elapsed since buffering began for a requested presentation. After the embedded player has contacted the host for the requested presentation, the player buffers the content to provide smooth playback of the presentation. You can obtain the elapsed time using the GetBufferingTimeElapsed method or determine the amount of buffering time remaining, using the GetBufferingTimeRemaining method.

Error Handling

.....

You can designate whether or not the RealPlayer embedded in your Web page displays error dialogs. If the SetWantErrors method is set to true, error messages from the player are trapped, and not displayed in an error dialog box. If SetWantErrors is set to false, error messages are displayed in an error dialog box. You can use the GetWantErrors method to determine if error messages are being trapped. If GetWantErrors returns true, error messages are being trapped. If GetWantErrors returns true, error message will be displayed when they occur.

When a player error occurs, the GetLastErrorMoreInfoURL method supplies a URL that can be used to provide more information than is provided by the standard error string.

If no URL is available to supply more information, this method returns nothing.

The GetLastErrorRMACode method returns a value that represents the error code returned by RealPlayer. The values of the error codes and their descriptions can be found in the RealSystem SDK rmaerror.h file and in the RealSystem SDK Developer's Guide.

Other RealPlayer error methods include GetLastErrorSeverity, which responds with the severity of the error, and GetLastStatus, which responds with the text of the last status message returned by the OnShowStatus callback.

Also included are two user-defined error methods: GetLastErrorUserCode and GetLastErrorUserString. The GetLastErrorUserCode returns a user-defined error code, and GetLastErrorUserString returns a user-defined string that describes the last error that occurred. If you have designed a custom plug-in for RealPlayer, you can use both of these methods to return your own error codes and error strings for your plug-in. If you are not providing a custom plug-in for RealPlayer, both of these methods return nothing.

Seeking Through a Clip

.....

The Embedded RealPlayer provides several methods that can be used to obtain information about the currently-playing clip, including determining the present clip position, total length, and whether you can seek through the presentation.

During playback, you can use the GetCanSeek method to verify whether you can seek through the clip. When the method returns true, you can then use the GetLength and GetPosition methods to obtain the clip length and current position in the clip. The actual length is returned as the total number of milliseconds in the clip. The position is returned as the number of milliseconds already played. You can also use the information returned from the GetLength method to ensure that the postion entered in the SetPosition method does not exceed the total length of the clip.

Another method that can be used when the GetCanSeek method returns true is SetCanSeek. This method allows you to specify whether a clip can be seeked. However, if you use the SetCanSeek method to allow seeking through an inherently unseekable clip, such as a live broadcast, the set method will have no effect.

©2001 RealNetworks, Inc. All rights reserved. For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen.