Appendix B: Callback Methods

This appendix 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 2 "Using Methods and Callbacks".

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:
percent_complete: The amount of buffering that is complete, in percent.

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:
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 flags parameter 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. 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.
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.

Parameter Values for the Possible Mouse Button Events
Bit Flag 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.

Returns void.

OnLButtonUp

Sent when the user releases the left mouse button. 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," on page 87.
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. 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," on page 87.
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
5	Paused

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. 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 Table , "Parameter Values for the Possible Mouse Button Events," on page 87.
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. 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 Table , "Parameter Values for the Possible Mouse Button Events," on page 87.
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," on page 89.

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.

Returns void.