[prev] [toc] [next]

5 System Configurations

5.1 Gong Client Parameters

Client parameters control various aspects of the Gong client such as server connection and program appearance. If the Gong client is executed as an application program the parameters are provided in an INI file called 'gong.ini'. Otherwise if the Gong client is a Java applet™ the parameters are set as applet parameters.

The Gong client usually comes with an appropriate set of parameters. Therefore, you are not required to alter the values unless you understand what the parameters are used for.

The following table summaries the parameters for the Gong client and their descriptions.

Name Description
Server.Hostname The Gong server address.
Either the server's hostname or IP address can be used here.
Server.Port The Gong server connection port number.
The range is 0 to 65535. The default port number is port 8000.
Login.WelcomeMessage The welcome message to be shown at the log on window.
The parameter value can have one line only but can be expressed as two lines by separating the lines with a '\n' character. The default message is 'Welcome to the Gong system!\nPlease login:'.
Login.ShowGuestButton Whether to show the guest button on the log on window.
The value is either 'true' or 'false'. The default value is 'true'.
Message.ShowYaleInterface Whether to show the Cantonese Yale user interface on the message composition window.
The value is either 'true' or 'false'. The default value is 'false'.
Message.ShowPinyinInterface Whether to show the Pinyin user interface on the message composition window.
The value is either 'true' or 'false'. The default value is 'false'.
System.Color The system color to be used by basic controls.
The color is expressed in hexidecimal representation of the red, green and blue components. For example, red is 'ff0000' and light yellow is 'ffff80'. The default color in RGB values is (195, 225, 245), i.e. 'c3e1f5'.
System.SecondaryColor The system secondary color to be used by other controls.
The color is expressed in hexidecimal representation of the red, green and blue components. For example, red is 'ff0000' and light yellow is 'ffff80'. The default color in RGB values is (195, 225, 245), i.e. 'c3e1f5'.
System.BackgroundColor The system background color of windows.
The color is expressed in hexidecimal representation of the red, green and blue components. For example, red is 'ff0000' and light yellow is 'ffff80'. The default color in RGB values is (195, 225, 245), i.e. 'c3e1f5'.
System.ControlFont The system font of the controls.
Should be careful with the font choice because not all font can be used to display multilingual data. The default font is 'SansSerif'.
System.UserFont The system font of the user input data.
Should be careful with the font choice because not all font can be used to display multilingual data. The default font is 'SansSerif'.
System.Language The system language.
It selects the language to be used throughout the user interface. The value is expressed as the locale string. The currently available values are:
  • en - American English
  • en_UK - British English
  • ja - Japanese
  • zh - Traditional Chinese
  • zh_CN - Simplified Chinese
The default language is 'en'.
Info.Username The username to be used for logging on the system.
When this value is specified together with the password the system would skip the system logon process. In other words the user is automatically logged on the Gong system without the need to type in his/her username and password.
Info.Password The password to be used for logging on the system.
When this value is specified together with the username the system would skip the system logon process. In other words the user is automatically logged on the Gong system without the need to type in his/her username and password.
Info.Guest Whether to log on the system as a guest user.
This value can be true or false. When this value is true the user will log on the system automatically as a guest user.
Info.Board The selected board code in the system.
The code represents the board to be selected in the system. When this value is specified the board selection process will be skipped.
Info.Message The message id of a pre-selected message.
The id of the message is specified so that the system can select the right message when the user logs on the board.
Info.MessageSubject The message subject of a pre-selected message.
The keyword of the message subject is specified so that the system can select the right message when the user logs on the board.
Info.Encrypted Whether the sensitive information are encrypted.
This value can be true or false. When it is true this set of values (Info.Username, Info.Password, Info.Board) has to be encrypted with standard DES encryption algorithm.

5.1.1 Gong INI File

The Gong INI file is used to store the client parameters for the Gong application program. The parameters are listed in the file as a name-value pair in separate lines.

For example to specify the Gong server connection port as 8000 you can use a name-value pair of the 'Server.Port' parameter.

...
Server.Port=8000
...

Each parameter can only be put in one line unless a '\' is used to separate the lines. You can also write comments in the file using a '#' symbol in the beginning of a line.

5.1.2 Gong Applet Parameters

When Gong is executed as Java applet™ parameters are given as applet parameters. Applet parameters are listed as the HTML 'param' tags within the 'applet' element which are placed inside the HTML page containing the Gong applet.

For example to specify the Gong server connection port as 8000 you can put a 'param' tag using the 'Server.Port' parameter name.

<applet name='gong' archive='gong.jar' code='gong.GongApplet' ...>
  ...
  <param name='Server.Port' value='8000'>
  ...
</applet>

If there are more than one parameter you can put more than one 'param' tag inside the 'applet' element.

5.1.3 Encrypted Parameters (under construction)

Sorry this section is under construction.

5.1.3.1 JSP/Servlet Example

Sorry this section is under construction.

5.1.3.2 PHP Example

Sorry this section is under construction.

5.1.3.3 ASP Example

Sorry this section is under construction.

5.2 Gong Server Parameters

Server parameters control the Gong server execution. They are stored in an INI file called 'gongServer.ini'. These parameters are listed in the file as a name-value pair in separate lines. Only the server administrator would need to adjust the value of these parameters.

The following table shows the list of parameters that can be configured in the server.

Name Description
Server.Port The Gong server connection port number.
The range is 0 to 65535. The default port number is port 8000.
Server.ConnectionString The Gong server streaming connection string.
This value specifies the connection to use for chat sessions. The system will try in the order specified in the string for a valid connection so that streaming audio can be transmitted between the client and the server. The connection is expressed in tokens separated by semi-colons. Each token represents one available connection with this format:
<protocol: either udp or tcp>:<port number>
For example, a UDP connection on port 80 would be 'udp:80'. The default connection string is 'udp:6970; udp:7070; tcp:7070'.
Server.MaximumConnection The maximum number of users who can log on the server.
The default value is no limit, i.e. 0.
Server.MaximumConnectionError The error message returns to the client when the maximum number of users is reached.
The value can be separated into two lines using the '\n' character.
Server.ClientIdleLimit The user idle time to kick out a client connection.
If the user is idle for this specified amount of time, he/she may get kicked out of the server when the maximum user number is reached. The default value is no limit, i.e. 0.
Session.LocalConnectorLimit The limit of user connection without recording for a single chat session.
The default value is 20.
Session.LocalWriterLimit The limit of user connection with recording for a single chat session.
The default value is 5.
Session.GlobalConnectorLimit The limit of user connection without recording for chat sessions in the server.
The default value is 40.
Session.GlobalWriterLimit The limit of user connection with recording for chat sessions in the server.
The default value is 10.
Session.RecordingTimeLimit The maximum recording time of a chat session.
The value is in millisec. The default value is 600000, i.e. 10 mins.
Info.EncryptionKey The encryption key for the Gong client parameters.
The key is a string with a maximum length of 8 characters. If the length is less than 8 characters, padding zeros will be added at the end. The default value is 'Gong'.

5.3 Gong Applet Scripting Interface

A Gong applet scripting interface is provided by the Gong system in order to facilitate communications between the Gong applet and the HTML page containing the applet.

There are two functions provided in the interface:

Currently there are twenty one types of request which can be sent to a Gong 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 'param' argument when sent as plain text. Below is the list of requests that are available from the applet.

  1. Play Media
    Start the playback of the selected message in the Gong applet.
  2. Record Media
    Start a new recording in the Gong applet.
  3. Pause Media
    Temporarily stop an active playback of the media.
  4. Stop Media
    Stop an active playback or recording.
  5. Set Media Time
    Set the time of the media at any moment.
  6. Get Media Time
    Get the time of the media at any moment.
  7. Set Media Rate
    Set the playback rate of the media at any moment.
  8. Get Media Rate
    Get the playback rate of the media at any moment.
  9. Get Media Status
    Get the current status of the media in the applet.
  10. Move to Previous Message
    Move the selected message to the previous in the list of messages.
  11. Move to Next Message
    Move the selected message to the next in the list of messages.
  12. Select Message
    Select a message from the list of messages.
  13. Get Current Message Id
    Get the id of the currently selected message in the applet.
  14. Search Message
    Search for a message using a search text and a range of options.
  15. Get Message
    Get the XML representation of the currently selected message.
  16. Get Message Content
    Get the text content of the currently selected message in HTML or plain text.
  17. Post Message
    Post a new message to the applet using a subject and optionally a text content.
  18. Get Current Token
    Get the currently played token(word) in the active playback.
  19. Get Board Name
    Get the current board name.
  20. Get Board Data
    Get the current board data in XML representation.
  21. Get Version
    Get the version of the Gong applet.

The following tables describe the specification of these two functions.

String sendRequest(String xmlString)
Description
Make a request to the Gong applet.
Input
An XML representation of the request including the request name and its parameters in one of the following forms†:
  1. Play Media
    <PlayMediaRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
      <StartTime>[Start time in milliseconds]</StartTime>
      <StopTime>[End time in milliseconds]</StopTime>
    </PlayMediaRequest>
  2. Record Media
    <RecordMediaRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
      <Duration>[Permitted duration in milliseconds]</Duration>
    </RecordMediaRequest>
  3. Pause Media
    <PauseMediaRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
    </PauseMediaRequest>
  4. Stop Media
    <StopMediaRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
    </StopMediaRequest>
  5. Set Media Time
    <SetMediaTimeRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
      <Time>The media time in milliseconds</Time>
    </SetMediaRateRequest>
  6. Get Media Time
    <GetMediaTimeRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
    </GetMediaTimeRequest>
  7. Set Media Rate
    <SetMediaRateRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
      <Rate>Playback rate within 0.5 (slow) and 1.5 (fast) where 1.0 is natural speed</Rate>
    </SetMediaRateRequest>
  8. Get Media Rate
    <GetMediaRateRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
    </GetMediaRateRequest>
  9. Get Media Status
    <GetMediaStatusRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MediaType>audio</MediaType>
    </GetMediaStatusRequest>
  10. Move to Previous Message
    <MoveToPrevMessageRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  11. Move to Next Message
    <MoveToNextMessageRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  12. Select Message
    <SelectMessageRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the message to be selected</MessageId>
    </SelectMessageRequest>
  13. Get Current Message Id
    <GetCurrentMessageIdRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  14. Search Message
    <SearchMessageRequest xmlns="http://www.cs.ust.hk/gong/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>
  15. Get Message
    <GetMessageRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the message</MessageId>
    </GetMessageRequest>
  16. Get Message Content
    <GetMessageContentRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the message</MessageId>
      <ContentType>The returned content type of either text/plain or text/html</ContentType>
    </GetMessageContentRequest>
  17. Post Message
    <PostMessageRequest xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Subject>The subject of the new message</Subject>
      <Content>[The text content of the new message]</Content>
    </PostMessageRequest>
  18. Get Current Token
    <GetCurrentTokenRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  19. Get Board Name
    <GetBoardNameRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  20. Get Board Data
    <GetBoardDataRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  21. Get Version
    <GetVersionRequest xmlns="http://www.cs.ust.hk/gong/gasi10"/>
† Optional parameters are enclosed by square brackets.
Return
An XML response in one of the following formats:
  1. Play Media
    <PlayMediaResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <StartTime>Actual start time in milliseconds</StartTime>
      <StopTime>Actual end time in milliseconds</StopTime>
    </PlayMediaResponse>
  2. Record Media
    <RecordMediaResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Duration>Actual permitted duration in milliseconds</Duration>
    </RecordMediaResponse>
  3. Pause Media
    <PauseMediaResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Time>The current media time in milliseconds</Time>
    </PauseMediaResponse>
  4. Stop Media
    <StopMediaResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Duration>[Recorded duration in milliseconds if a recording is stopped]</Duration>
    </StopMediaResponse>
  5. Set Media Time
    <SetMediaTimeResponse xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  6. Get Media Time
    <GetMediaTimeResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Time>The current media time in milliseconds</Time>
    </GetMediaTimeResponse>
  7. Set Media Rate
    <SetMediaRateResponse xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  8. Get Media Rate
    <GetMediaRateResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Rate>The current playback rate</Rate>
    </GetMediaRateResponse>
  9. Get Media Status
    <GetMediaStatusResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Status>
        The status of the media which can be:
        playing or recording or paused or stopping or
        stopped or closing or closed
      </Status>
    </GetMediaStatusResponse>
  10. Move to Previous Message
    <MoveToPrevMessageResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the previous message</MessageId>
    </MoveToNextMessageResponse>
  11. Move to Next Message
    <MoveToNextMessageResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the next message</MessageId>
    </MoveToNextMessageResponse>
  12. Select Message
    <SelectMessageResponse xmlns="http://www.cs.ust.hk/gong/gasi10"/>
  13. Get Current Message Id
    <GetCurrentMessageIdResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the currently selected message</MessageId>
    </GetCurrentMessageIdResponse>
  14. Search Message
    <SearchMessageResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the message matching the search</MessageId>
    </SearchMessageResponse>
  15. Get Message
    <GetMessageResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Message>The message in XML representation</Message>
    </GetMessageResponse>
  16. Get Message Content
    <GetMessageContentResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Content>The text content of the message in the requested content type</Content>
    </GetMessageContentResponse>
  17. Post Message
    <PostMessageResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <MessageId>The id of the new message</MessageId>
    </PostMessageResponse>
  18. Get Current Token
    <GetCurrentTokenResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Token>The token in XML representation</Token>
    </GetCurrentTokenResponse>
  19. Get Board Name
    <GetBoardNameResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Name>The name of the current board</Name>
    </GetBoardNameResponse>
  20. Get Board Data
    <GetBoardDataResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Board>The data of the current board in XML representation</Board>
    </GetBoardDataResponse>
  21. Get Version
    <GetVersionResponse xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Version>The current version string</Version>
    </GetVersionResponse>
  22. Fault
    <Fault xmlns="http://www.cs.ust.hk/gong/gasi10">
      <Code>[Fault code]</Code>
      <Reason>[Fault reason]</Reason>
    </Fault>
Exception
An exception will be thrown if an error occurs.
 
String sendRequest(String name, String param)
Description
Make a request to the Gong applet.
Input
The request name and the set of parameters† associated with the request.
  1. Play Media
    name: "PlayMedia"
    param: "audio;[Start time in milliseconds];[End time in milliseconds]"
  2. Record Media
    name: "RecordMedia"
    param: "audio;[Permitted duration in milliseconds]"
  3. Pause Media
    name: "PauseMedia"
    param: "audio"
  4. Stop Media
    name: "StopMedia"
    param: "audio"
  5. Set Media Time
    name: "SetMediaTime"
    param: "audio;The media time in milliseconds"
  6. Get Media Time
    name: "GetMediaTime"
    param: "audio"
  7. Set Media Rate
    name: "SetMediaRate"
    param: "audio;Playback rate within 0.5 (slow) and 1.5 (fast) where 1.0 is natural speed"
  8. Get Media Rate
    name: "GetMediaRate"
    param: "audio"
  9. Get Media Status
    name: "GetMediaStatus"
    param: "audio"
  10. Move to Previous Message
    name: "MoveToPrevMessage"
    param: ""
  11. Move to Next Message
    name: "MoveToNextMessage"
    param: ""
  12. Select Message
    name: "SelectMessage"
    param: "The id of the message to be selected"
  13. Get Current Message Id
    name: "GetCurrentMessageId"
    param: ""
  14. Search Message
    name: "SearchMessage"
    param: "The search text;
            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 text content, can be true or false"
  15. Get Message
    name: "GetMessage"
    param: "The id of the message"
  16. Get Message Content
    name: "GetMessageContent"
    param: "The id of the message;The returned content type of either text/plain or text/html"
  17. Post Message
    name: "PostMessage"
    param: "The subject of the new message;[The text content of the new message]"
  18. Get Current Token
    name: "GetCurrentToken"
    param: ""
  19. Get Board Name
    name: "GetBoardName"
    param: ""
  20. Get Board Data
    name: "GetBoardData"
    param: ""
  21. Get Version
    name: "GetVersion"
    param: ""
† Optional parameters are enclosed by square brackets.
Return
A response containing the values requested.
  1. Play Media
    "Actual start time in milliseconds;Actual end time in milliseconds"
  2. Record Media
    "Actual permitted duration in milliseconds"
  3. Pause Media
    "The current media time in milliseconds"
  4. Stop Media
    "[Recorded duration in milliseconds if a recording is stopped]"
  5. Set Media Time
    Nil
  6. Get Media Time
    "The current media time in milliseconds"
  7. Set Media Rate
    Nil
  8. Get Media Rate
    "The current playback rate"
  9. Get Media Status
    "The status of the media which can be:
     playing or recording or paused or stopping or stopped or closing or closed"
  10. Move to Previous Message
    "The id of the previous message"
  11. Move to Next Message
    "The id of the next message"
  12. Select Message
    Nil
  13. Get Current Message Id
    "The id of the currently selected message"
  14. Search Message
    "The id of the message matching the search"
  15. Get Message
    "The message in XML representation"
  16. Get Message Content
    "The text content of the message in the requested content type"
  17. Post Message
    "The id of the new message"
  18. Get Current Token
    "The token in XML representation"
  19. Get Board Name
    "The name of the current board"
  20. Get Board Data
    "The data of the current board in XML representation"
  21. Get Version
    "The current version string"
Exception
An exception will be thrown if an error occurs.

To illustrate the scripting interface the following sections use JavaScript and VBScript to create a simple two-buttons player with a Gong applet.

5.3.1 JavaScript Example

In the following example JavaScript is used to control the Gong applet with two HTML form buttons. The Gong applet resides on the HTML page but is hidden from the user.

<html>
<head>
    <title>JavaScript Example</title>
    <script type="text/javascript">
    <!--
    function doplay() {
        try {
            document.getElementById("gong").sendRequest("PlayMedia", "audio");
        }
        catch (e) {
            alert("Failed to play the message.");
        }
    }

    function dostop() {
        try {
            document.getElementById("gong").sendRequest("StopMedia", "audio");
        }
        catch (e) {
            alert("Failed to stop the message.");
        }
    }
    // -->
    </script>
</head>
<body>
    <h1>Simple Playback using Gong Applet</h1>
    <form>
        <input type="button" value="Play" onclick="doplay()" />
        <input type="button" value="Stop" onclick="dostop()" />
    </form>
    <applet id="gong" archive="gong.jar" code="gong.GongApplet" style="display:none" ...>
        ...
    </applet>
</body>
</html>

For a working example please go to the Gong website at http://www.cs.ust.hk/gong.

5.3.2 VBScript Example

In the following example VBScript is used to control the Gong applet with two HTML form buttons. The Gong applet resides on the HTML page but is hidden from the user.

<html>
<head>
    <title>VBScript Example</title>
    <script type="text/vbscript">
    <!--
    Sub Play_OnClick()
        On Error Resume Next
        document.gong.sendRequest "PlayMedia", "audio"
        If Err.Number <> 0 Then
            alert("Failed to play the message.");
            Exit Sub
        End If
    End Sub

    Sub Stop_OnClick()
        On Error Resume Next
        document.gong.sendRequest "StopMedia", "audio"
        If Err.Number <> 0 Then
            alert("Failed to stop the message.");
            Exit Sub
        End If
    End Sub
    // -->
    </script>
</head>
<body>
    <h1>Simple Playback using Gong Applet</h1>
    <form>
        <input type="button" value="Play" name="Play" />
        <input type="button" value="Stop" name="Stop" />
    </form>
    <applet name="gong" archive="gong.jar" code="gong.GongApplet" width="0" height="0" ...>
        ...
    </applet>
</body>
</html>

For a working example please go to the Gong website at http://www.cs.ust.hk/gong.