Chapter 7: Embedded Player Callbacks

This chapter describes the RealPlayer callback methods sent to inform an application or script that a RealPlayer event has occurred. The callback methods are listed here in alphabetical order and each description contains information about how to use the callback in your Netscpae plug-in or ActiveX control, an example of syntax and usage, and backward compatibilty tips for various API versions.

For More Information: For information about categories of callback methods, such as those used to handle user interactions with your presentation, see Chapter 5.

OnAuthorChange

Sent when the author string changes.

OnAuthorChange(string author)

author

The new author string.

Returns void.

OnBuffering

Sends a percentage of the buffering that has completed.

OnBuffering(int32 flags, int32 percent_complete)

flags

The buffering flags. One of the following values:

0 — Buffering start up.

1 — Buffering resulting from a seek.

2 — Buffering resulting from network congestion.

3 — Buffering resulting from resuming after pausing a live presentation.

Note: If you are programming in C++, use the values of the flags found in the BUFFERING_REASON enumerator in rmacore.h (supplied with the RealSystem SDK).

percent_complete

The amount of buffering that is complete, in percent.

Warning! The use of this method varies slightly between programming languages. In C++, the datatype of this parameter is int32, while in Java, the datatype is int16. Either datatype may be used when developing in Javascript or VBScript.

Returns void.

OnClipClosed

Sent to indicate that no clip is currently opened by the control. This method is compatible with RealPlayer version 5.0 and later.

OnClipClosed(void)

Warning! The use of this method varies slightly between programming languages. In C++, the name of the method is OnClipClosed, while in Java and Javascript, the name is onClipClosed.

Returns void.

OnClipOpened

Sent when a clip is opened by the control. This method is compatible with RealPlayer version 5.0 and later.

OnClipOpened(string short_clip_name, string url)

Warning! The use of this method varies slightly between programming languages. In C++, the name of the method is OnClipOpened, while in Java and Javascript, the name is onClipOpened.

short_clip_name

The name of the clip that is opened.

url

The URL of the clip that is opened.

Returns void.

OnContacting

Sent when RealPlayer contacts a host.

OnContacting(string host_name)

host_name

The host name string.

Returns void.

OnCopyrightChange

Sent when the copyright string changes.

OnCopyrightChange(string copyright)

copyright

The new copyright string.

Returns void.

OnErrorMessage

Sent when an error occurs.

OnErrorMessage(
    int16 severity,
    int32 rma_code,
    int32 user_code,
    string user_string,
    string more_info_url,
    string error
)

severity

The error level for the last error. See GetLastErrorSeverity for more information about severity levels.

rma_code

The 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.realnetworks.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.

user_code

The user error code from the last error. For more information, see GetLastErrorUserCode.

user_string

The error string from the last error dialog. For more information, see GetLastErrorUserString.

more_info_url

The "more info" URL from the last error. This may be nothing (for example, if there is no "more info" URL).

error

A text description of the error.

Returns void.

OnGotoURL

Sent when an URL event is encountered for the RealPlayer clip currently playing. This event occurs only if the AutoGotoURL setting is FALSE. (This setting is modified either by using the AUTOGOTOURL parameter in the <EMBED> or <OBJECT> tag, or by using the SetAutoGoToURL method.)

This method is compatible with RealPlayer version 5.0 and later.

OnGotoURL(string url, string target)

Warning! The use of this method varies slightly between programming languages. In C++, the name of the method is OnGotoURL, while in Java and Javascript, the name is onGoToURL.

url

Contains the URL that would have been sent to the browser if AutoGotoURL were TRUE.

target

The name of the browser or frame the URL should have been opened in if AutoGotoURL were TRUE.

Returns void.

OnKeyDown

Sent when the user presses and holds down a keyboard key. This callback method is only sent when the set parameter of the SetWantKeyboardEvents method is set to true.

OnKeyDown(int32 flags, int32 key)

Warning! When programming in Java or Javascript, the flags parameter is not available. The proper syntax is:
OnKeyDown(int32 key).

flags

The bit flags for the key press. Windows defines the values for this parameter in the Windows Platform SDK from Microsoft, under the WM_CHAR message.

key

The key code for the key that was pressed and held.

Returns void.

OnKeyPress

Sent when the user presses and releases a keyboard key. This callback method is only sent when the set parameter of the SetWantKeyboardEvents method is set to true.

OnKeyPress(int32 flags, int32 key)

Warning! When programming in Java or Javascript, the flagsparameter is not available. The proper syntax is:
OnKeyPress(int32 key).

flags

The bit flags for the key press. Windows defines the values for this parameter in the Windows Platform SDK from Microsoft, under the WM_CHAR message.

key

The key code for the key that was pressed and released.

Returns void.

OnKeyUp

Sent when user releases keyboard key. This callback method is only sent when the set parameter of the SetWantKeyboardEvents method is set to true.

OnKeyUp(int32 flags, int32 key)

Warning! When programming in Java or Javascript, the flags parameter is not available. The proper syntax is:
OnKeyUp(int32 key).

flags

The bit flags for the key press. Windows defines the values for this parameter in the Windows Platform SDK from Microsoft, under the WM_CHAR message.

key

The key code for the key the user has released.

Returns void.

OnLButtonDown

Sent when the user holds down the left mouse button when the cursor is placed over the embedded component. This callback method is only sent when the set parameter of the SetWantMouseEvents method is set to true.

OnLButtonDown(int32 button_flags, int32 x_pos, int32 y_pos)

button_flags

The bit flags for mouse and mouse button events.

The following table lists the possible values for the button_flags parameter.

Parameter Values for the Possible Mouse Button Events
Bit Flat Value	Mouse Button Event
`MK_LBUTTON`	The left mouse button is pressed.
`MK_RBUTTON`	The right mouse button is pressed.
`MK_SHIFT`	The Shift key on the keyboard is pressed.
`MK_CONTROL`	The Ctrl key on the keyboard is pressed.
`MK_MBUTTON`	The middle mouse button is pressed.

x_pos

The x position of the mouse when the left button is pressed.

y_pos

The y position of the mouse when the left button is pressed.

Returns void.

OnLButtonUp

Sent when the user releases the left mouse button while the cursor is positioned over the embedded component. This callback method is only sent when the set parameter of the SetWantMouseEvents method is set to true.

OnLButtonUp(int32 button_flags, int32 x_pos, int32 y_pos)

button_flags

The bit flags for mouse and mouse button events. For a list of possible values for this parameter, see Table , "Parameter Values for the Possible Mouse Button Events,".

x_pos

The x position of the mouse when the left mouse button is released.

y_pos

The y position of the mouse when the left mouse button is released.

Returns void.

OnMouseMove

Sent when the user moves the mouse cursor over the embedded component. This callback method is only sent when the set parameter of the SetWantMouseEvents method is set to true.

Note: This callback is sent when the operating system notifies the plug-in or ActiveX control that the mouse has moved.

OnMouseMove(int32 button_flags, int32 x_pos, int32 y_pos)

button_flags

The bit flags for mouse and mouse button events. For a list of possible values for this parameter, see Table , "Parameter Values for the Possible Mouse Button Events,".

x_pos

The x position of the mouse.

y_pos

The y position of the mouse.

Returns void.

OnMuteChange

Sent when the volume is muted or unmuted.

OnMuteChange(boolean mute)

mute

If true, the volume is muted. If false, the volume is restored.

Returns void.

OnPlayStateChange

Sent when the play state of the presentation in RealPlayer changes.

OnPlayStateChange(int32 old_state, int32 new_state)

Warning! When programming an ActiveX control, the old_state parameter is not available. The proper syntax is:
OnPlayStateChange(int32 new_state). If your ActiveX application requires both the old_state and new_state parameters, use the OnStateChange callback instead.

old_state

The previous play state.

new_state

The current play state.

The following table lists the possible values for the old_state and new_state parameters:

Parameter Values for the Possible Play States
Parameter Value	Play State
`0`	Stopped
`1`	Contacting
`2`	Buffering
`3`	Playing
`4`	Seeking

Returns void.

OnPosLength

Sent when the position in the clip changes.

OnPosLength(int32 pos, int32 len)

Note: This callback is intended for a Netscape plug-in only. If you are coding an ActiveX control, use the OnPositionChange callback instead.

pos

The current position of the clip, in milliseconds.

len

The length of the clip, in milliseconds.

Returns void.

OnPositionChange

Sent when the position in the clip changes.

OnPositionChange(int32 pos, int32 len)

Note: This callback is intended for an ActiveX control only. If you are coding a Netscape plug-in, use the OnPosLength callback instead.

pos

The current position of the clip, in milliseconds.

len

The length of the clip, in milliseconds.

Returns void.

OnPostSeek

Sent when a seek completes.

OnPostSeek(int32 old_time, int32 new_time)

old_time

The presentation time, in milliseconds, before the seek occurred.

new_time

The presentation time, in milliseconds, after the seek occurred.

Returns void.

OnPreFetchComplete

Sent when the component has fetched the stream header information. Called if PREFETCH is set to true in the <EMBED> or <OBJECT> tag or if the set parameter of the SetPreFetch method is set to true.

OnPreFetchComplete(void)

Returns void.

OnPreSeek

Sent when the user performs a seek by moving the presentation position slider.

OnPreSeek(int32 old_time, int32 new_time)

old_time

The presentation time, in milliseconds, when the seek occurred.

new_time

The time, in milliseconds, to which the presentation is seeking.

Returns void.

OnPresentationClosed

Sent when the presentation stops.

OnPresentationClosed(void)

Returns void.

OnPresentationOpened

Sent when the presentation starts.

OnPresentationOpened(void)

Returns void.

OnRButtonDown

Sent when the user holds down the right mouse button while the cursor is positioned over the embedded component. This callback method is only sent when the set parameter of the SetWantMouseEvents method is set to true.

OnLButtonDown(int32 button_flags, int32 x_pos, int32 y_pos)

button_flags

The bit flags for mouse and mouse button events. For a list of possible values for this parameter, see the table "Parameter Values for the Possible Mouse Button Events".

x_pos

The x position of the mouse when the right button is pressed.

y_pos

The y position of the mouse when the right button is pressed.

Returns void.

OnRButtonUp

Sent when the user releases the right mouse button while the cursor is positioned over the embedded component. This callback method is only sent when the set parameter of the SetWantMouseEvents method is set to true.

OnRButtonUp(int32 button_flags, int32 x_pos, int32 y_pos)

button_flags

The bit flags for mouse and mouse button events. For a list of possible values for this parameter, see the table "Parameter Values for the Possible Mouse Button Events".

x_pos

The x position of the mouse when the right mouse button is released.

y_pos

The y position of the mouse when the right mouse button is released.

Returns void.

OnShowStatus

Sent to indicate that the status text is changing. This method is compatible with RealPlayer version 5.0 and later.

OnShowStatus(string status_text)

Warning! The use of this method varies slightly between programming languages. In C++, the name of the method is OnShowStatus, while in Java and Javascript, the name is onShowStatus.

status_text

The new status text.

Returns void.

OnStateChange

Sent when the play state of the presentation in RealPlayer changes.

Note: This callback is intended for an ActiveX control only. If you are coding a Netscape plug-in, use the OnPlayStateChange callback instead.

OnStateChange(int32 old_state, int32 new_state)

old_state

The previous play state.

new_state

The current play state.

For a list of possible values for the old_state and new_state parameters, see Table , "Parameter Values for the Possible Play States,".

Returns void.

OnTitleChange

Sent when the title string changes.

OnTitleChange(string title)

title

The new title string.

Returns void.

OnVolumeChange

Sent when the volume level changes.

OnVolumeChange(int32 new_volume)

new_volume

The new volume level. The valid volume range is 0 through 100, where 0 represents no volume.

Warning! The use of this method varies slightly between programming languages. In C++, the datatype of this parameter is int16, while in Java, the datatype is int32. Either datatype may be used when developing in Javascript or VBScript.

Returns void.