Gong Scripting API Reference

This page explains the programmability of the Gong applets which gives flexibility to the use of Gong. Most people do not need to understand this when they want to use Gong. The information is primarily for programmers who want to use the Gong programmability but it is also useful if you are interested to know how it works.

The programmability of the Gong applets is provided by a Gong applet scripting interface, which facilitate communications between the Gong/NanoGong applet and the HTML page containing the applet. The interface can be controlled by any Web client scripting language such as JavaScript and VBScript.

Various examples using the Gong Scripting API are available in the Gong real-time control page and the NanoGong page. All the examples in these pages use JavaScript as the scripting language although it can be easily changed to VBScript.

The functions provided in the interface are listed below:

  • String sendGongRequest(String xmlString)
    Make a request to the Gong/NanoGong applet using an XML string containing the request name and parameters.
  • String sendGongRequest(String name, String param)
    Make a named request to the Gong/NanoGong applet with one parameter.
  • String sendGongRequest(String name, String param1, String param2)
    Make a named request to the Gong/NanoGong applet with two parameters.
  • String sendGongRequest(String name, String param1, String param2, String param3)
    Make a named request to the Gong/NanoGong applet with three parameters.
  • String sendGongRequest(String name, String param1, String param2, String param3, String param4)
    Make a named request to the Gong/NanoGong applet with four parameters.

Currently there are 23 types of request which can be sent to a Gong/NanoGong applet. Each of the requests has its own parameter set. These parameters can be sent to the Gong applet as part of the XML string or in the parameter arguments when sent as a named request.

The list of requests is shown below with their description and availability in the Gong and NanoGong applets.

Request Name Description Availability
PlayMedia Play the current voice recording in the applet. Gong/NanoGong
RecordMedia Start a new recording in the applet. Gong/NanoGong
PauseMedia Temporarily stop an active playback of the media. Gong/NanoGong
StopMedia Stop an active playback or recording. Gong/NanoGong
SetMediaTime Set the time of the media at any moment. Gong/NanoGong
GetMediaTime Get the time of the media at any moment. Gong/NanoGong
SetMediaRate Set the playback rate of the media at any moment. Gong/NanoGong
GetMediaRate Get the playback rate of the media at any moment. Gong/NanoGong
GetMediaStatus Get the current status of the media in the applet. Gong/NanoGong
GetAudioLevel Get the current audio level of the media in the applet. Gong/NanoGong
MoveToPrevMessage Move the selected message to the previous in the list of messages. Gong Only
MoveToNextMessage Move the selected message to the next in the list of messages. Gong Only
SelectMessage Select a message from the list of messages. Gong Only
GetCurrentMessageId Get the id of the currently selected message in the applet. Gong Only
SearchMessage Search for a message using a search text and a range of options. Gong Only
GetMessage Get the XML representation of the currently selected message. Gong Only
GetMessageContent Get the text content of the currently selected message in HTML or plain text. Gong Only
PostMessage Post a new message to the applet using a subject and optionally a text content. Gong Only
SaveMessage Save the current voice recording to the hard disk. Gong/NanoGong
GetCurrentToken Get the currently played token(word) in the active playback. Gong Only
GetBoardName Get the current board name. Gong Only
GetBoardData Get the current board data in XML representation. Gong Only
GetVersion Get the version of the Gong/NanoGong applet. Gong/NanoGong

The following tables describe the specification of the requests when using the functions.

Request Name Specification
PlayMedia
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 Start time in milliseconds (optional)
Parameter 3 End time in milliseconds (optional)
Parameter 4 -
Return Value Start time in milliseconds;End time in milliseconds

Using XML Form
XML Input <PlayMediaRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> <StartTime>[Start time in milliseconds]</StartTime> <StopTime>[End time in milliseconds]</StopTime> </PlayMediaRequest>
XML Output <PlayMediaResponse xmlns="http://gong.ust.hk/gasi10"> <StartTime>Start time in milliseconds</StartTime> <StopTime>End time in milliseconds</StopTime> </PlayMediaResponse>
RecordMedia
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 Permitted duration in milliseconds (optional)
Parameter 3 -
Parameter 4 -
Return Value Permitted duration in milliseconds

Using XML Form
XML Input <RecordMediaRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> <Duration>[Permitted duration in milliseconds]</Duration> </RecordMediaRequest>
XML Output <RecordMediaResponse xmlns="http://gong.ust.hk/gasi10"> <Duration>Permitted duration in milliseconds</Duration> </RecordMediaResponse>
PauseMedia
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The current media time in milliseconds

Using XML Form
XML Input <PauseMediaRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> </PauseMediaRequest>
XML Output <PauseMediaResponse xmlns="http://gong.ust.hk/gasi10"> <Time>The current media time in milliseconds</Time> </PauseMediaResponse>
StopMedia
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The media duration in milliseconds

Using XML Form
XML Input <StopMediaRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> </StopMediaRequest>
XML Output <StopMediaResponse xmlns="http://gong.ust.hk/gasi10"> <Duration>The media duration in milliseconds</Duration> </StopMediaResponse>
SetMediaTime
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 The media time in milliseconds
Parameter 3 -
Parameter 4 -
Return Value -

Using XML Form
XML Input <SetMediaTimeRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> <Time>The media time in milliseconds</Time> </SetMediaTimeRequest>
XML Output <SetMediaTimeResponse xmlns="http://gong.ust.hk/gasi10"/>
GetMediaTime
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The media time in milliseconds

Using XML Form
XML Input <GetMediaTimeRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> </GetMediaTimeRequest>
XML Output <GetMediaTimeResponse xmlns="http://gong.ust.hk/gasi10"> <Time>The media time in milliseconds</Time> </GetMediaTimeResponse>
SetMediaRate
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 The media rate between 0.5 to 1.5 with normal rate at 1.0
Parameter 3 -
Parameter 4 -
Return Value -

Using XML Form
XML Input <SetMediaRateRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> <Rate>The media rate between 0.5 to 1.5 with normal rate at 1.0</Rate> </SetMediaRateRequest>
XML Output <SetMediaRateResponse xmlns="http://gong.ust.hk/gasi10"/>
GetMediaRate
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The media rate between 0.5 to 1.5 with normal rate at 1.0

Using XML Form
XML Input <GetMediaRateRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> </GetMediaRateRequest>
XML Output <GetMediaRateResponse xmlns="http://gong.ust.hk/gasi10"> <Rate>The media rate between 0.5 to 1.5 with normal rate at 1.0</Rate> </GetMediaRateResponse>
GetMediaStatus
Using Named Request Form
Parameter 1 Media type (always 'audio' for the current version)
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The media status in one of these values:
playing, recording, paused, stopping, stopped, closing and closed

Using XML Form
XML Input <GetMediaStatusRequest xmlns="http://gong.ust.hk/gasi10"> <MediaType>audio</MediaType> </GetMediaStatusRequest>
XML Output <GetMediaStatusResponse xmlns="http://gong.ust.hk/gasi10"> <Status>The media status in one of these values: playing, recording, paused, stopping, stopped, closing and closed</Status> </GetMediaStatusResponse>
GetAudioLevel
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The audio level in the range of 0 to 1

Using XML Form
XML Input <GetAudioLevelRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <GetAudioLevelResponse xmlns="http://gong.ust.hk/gasi10"> <Level>The audio level in the range of 0 to 1</Level> </GetAudioLevelResponse>
MoveToPrevMessage
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The message id of the message after moving

Using XML Form
XML Input <MoveToPrevMessageRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <MoveToPrevMessageResponse xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the message after moving</MessageId> </MoveToPrevMessageResponse>
MoveToNextMessage
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The message id of the message after moving

Using XML Form
XML Input <MoveToNextMessageRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <MoveToNextMessageResponse xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the message after moving</MessageId> </MoveToNextMessageResponse>
SelectMessage
Using Named Request Form
Parameter 1 The message id of the message to be selected
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value -

Using XML Form
XML Input <SelectMessageRequest xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the message to be selected</MessageId> </SelectMessageRequest>
XML Output <SelectMessageResponse xmlns="http://gong.ust.hk/gasi10"/>
GetCurrentMessageId
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The message id of the current message

Using XML Form
XML Input <GetCurrentMessageIdRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <GetCurrentMessageIdResponse xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the current message</MessageId> </GetCurrentMessageIdResponse>
SearchMessage
Using Named Request Form
Parameter 1 The search text
Parameter 2 The search options with the following field in a single line semi-colon delimited string:
Case-sensitive search, can be true or false;
Search for whole words only, can be true or false;
Use regular expression, can be true or false;
Search author, can be true or false;
Search subject, can be true or false;
Search content, can be true or false
Parameter 3 -
Parameter 4 -
Return Value The message in XML representation

Using XML Form
XML Input <SearchMessageRequest xmlns="http://gong.ust.hk/gasi10"> <Text>The search text</Text> <Options> <CaseSensitive>Case-sensitive search, can be true or false</CaseSensitive> <WholeWords>Search for whole words only, can be true or false</WholeWords> <Regex>Use regular expression, can be true or false</Regex> <Targets> <Author>Search author, can be true or false</Author> <Subject>Search subject, can be true or false</Subject> <Content>Search text content, can be true or false</Content> </Targets> </Options> </SearchMessageRequest>
XML Output <SearchMessageResponse xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the message</MessageId> </SearchMessageResponse>
GetMessage
Using Named Request Form
Parameter 1 The message id of the message
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The message in XML representation

Using XML Form
XML Input <GetMessageRequest xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the message</MessageId> </GetMessageRequest>
XML Output <GetMessageResponse xmlns="http://gong.ust.hk/gasi10"> <Message>The message in XML representation</Message> </GetMessageResponse>
GetMessageContent
Using Named Request Form
Parameter 1 The message id of the message
Parameter 2 The content type of the message: text/plain or text/html
Parameter 3 -
Parameter 4 -
Return Value The message content in the requested type

Using XML Form
XML Input <GetMessageContentRequest xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of the message</MessageId> <ContentType>The content type of the message: text/plain or text/html</ContentType> </GetMessageContentRequest>
XML Output <GetMessageContentResponse xmlns="http://gong.ust.hk/gasi10"> <Content>The message content in requested type</Content> </GetMessageContentResponse>
PostMessage
Using Named Request Form
Parameter 1 The message id of the parent message (0 if there is no parent message)
Parameter 2 The author name (required only if the user is a guest)
Parameter 3 The subject of the message
Parameter 4 The content of the message
Return Value The message id of newly created message

Using XML Form
XML Input <PostMessageRequest xmlns="http://gong.ust.hk/gasi10"> <Parent>The message id of the parent message (0 if there is no parent message)</Parent> <Name>[The author name]</Name> <Subject>The subject of the message</Subject> <Content>The content of the message</Content> </PostMessageRequest>
XML Output <PostMessageResponse xmlns="http://gong.ust.hk/gasi10"> <MessageId>The message id of newly created message</MessageId> </PostMessageResponse>
SaveMessage
Using Named Request Form
Parameter 1 The file type: wav/adpcm or flv/pcm
Parameter 2 The filename
Parameter 3 The path of the saved file
Parameter 4 -
Return Value The full path of the saved voice file

Using XML Form
XML Input <SaveMessageRequest xmlns="http://gong.ust.hk/gasi10"> <Type>The file type: wav/adpcm or flv/pcm</Type> <Filename>The filename</Filename> <Path>The path of the saved file</Path> </SaveMessageRequest>
XML Output <SaveMessageResponse xmlns="http://gong.ust.hk/gasi10"> <File>The full path of the saved voice file</File> </SaveMessageResponse>
GetCurrentToken
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The current playing token in XML representation

Using XML Form
XML Input <GetCurrentTokenRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <GetCurrentTokenResponse xmlns="http://gong.ust.hk/gasi10"> <Token>The current playing token in XML representation</Token> </GetCurrentTokenResponse>
GetBoardName
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The current board name

Using XML Form
XML Input <GetBoardNameRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <GetBoardNameResponse xmlns="http://gong.ust.hk/gasi10"> <Name>The current board name</Name> </GetBoardNameResponse>
GetBoardData
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The current board data in XML representation

Using XML Form
XML Input <GetBoardDataRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <GetBoardDataResponse xmlns="http://gong.ust.hk/gasi10"> <Board>The current board data in XML representation</Board> </GetBoardDataResponse>
GetVersion
Using Named Request Form
Parameter 1 Empty string
Parameter 2 -
Parameter 3 -
Parameter 4 -
Return Value The version of the Gong/NanoGong applet

Using XML Form
XML Input <GetVersionRequest xmlns="http://gong.ust.hk/gasi10"/>
XML Output <GetVersionResponse xmlns="http://gong.ust.hk/gasi10"> <Version>The version of the Gong/NanoGong applet</Version> </GetVersionResponse>