Table of Contents

Member Database Support

The database support allows you to integrate the information in a member database with one or more VolanoChatPro servers in the following ways:

• You can restrict to the VolanoChatPro server to visitors who enter valid member names and passwords when entering to chat.
• You can allow both members and non-members to access the server but reserve member names for use only by their owners.
• You can highlight members in the VolanoChatPro server by prefixing their profiles with a link to their own Web page.

The database need not reside on the same machine as the VolanoChatPro server. It can provide a central directory for several VolanoChatPro servers, as shown in the figure below.

If you do not have a database, you can get a full featured Structured Query Language (SQL) database for free from T.c.X. DataKonsultAB, called MySQL. MySQL supports many different programming interfaces, including:

• it's own C programming interface,
• the Perl Database Interface (DBI), by Tim Bunce, and
• the Java JDBC™ Database Access API, by Sun Microsystems.

You provide the information from your database to the VolanoChat server through three simple CGI scripts. The scripts are invoked by a Uniform Resource Locator (URL) you define to the VolanoChatPro server. The scripts can be implemented in any language and architecture supported by your Web server and your database. You can even write the scripts in Java as a Java servlet and add them to VolanoChat's built-in servlet runner. The three scripts, and the names of the properties which define their addresses, are:

member.access

to obtain member access,

member.name

to check whether a member name exists, and

member.document

to display a member Web page.

Both member.access and member.name are VolanoChat server properties, while member.document is a VolanoChat applet property.

Member access

The member access script is invoked when members enter their name and password into the member interface of the VolanoChat applet. It is invoked as a normal HTTP GET request, and its response determines whether the VolanoChatPro server grants access to the member.

The access script is defined by the URL you specify with the member.access server property. The VolanoChatPro server drops in the member name and password which the visitor entered on the VolanoChat member applet. For example, you might define a script with a format as follows:

member.access=http://red.volano.com/member?name={0}&password={1}

The VolanoChatPro server fills in this URL template such that:

• {0} is filled in with the member name, and
• {1} is filled in with the member password.

The member access script returns an XML document with a single root element of the form:

<result value="[true|false|error]">
Profile or error string.
</result>

If the member name and password are valid, the access script returns a result of true along with the optional member profile string. For example:

<result value="true">
This is the member's profile.
</result>

If the member name is not found or the password is not valid, the access script returns a result of false. For example:

<result value="false">
</result>

If an error occurs processing the request, the access script returns a result of error along with an optional descriptive error message. For example:

<result value="error">
Unable to connect to database.
</result>

Member name

The member name script is invoked each time someone enters a chat room. It is invoked as a normal HTTP GET request, and its response determines whether the visitor may enter the chat room with the chosen name. This script implements name reservation for your members.

The access script is defined by the URL you specify with the member.name server property. The VolanoChatPro server drops in the member name which the visitor entered on the main chat window as the nickname for entering the room. For example, you might define a script with a format as follows:

member.name=http://red.volano.com/taken?name={0}

The VolanoChatPro server fills in this URL template such that:

• {0} is filled in with the chosen nickname.

The member name script returns an XML document with a single root element of the form:

<result value="[true|false|error]">
</result>

If the nickname is taken by a member, the name script returns a result of true. For example:

<result value="true">
</result>

If the nickname is not taken by a member, the name script returns a result of false. For example:

<result value="false">
</result>

If an error occurs processing the request, the name script returns a result of error along with an optional descriptive error message. For example:

<result value="error">
Unable to connect to database.
</result>

Member document

The member document script is invoked when a visitor clicks on the member profile link which is prefixed to each member's profile in the chat rooms. It is invoked as a normal HTTP GET request, and it should return the Web page associated with the member.

The access script is defined by the URL you specify with the member.document VolanoChat applet property. The VolanoChat applet drops in the member's nickname and the nickname of the person requesting the page, if available. For example, you might define a script with a format as follows:

member.document=http://red.volano.com/page?for=%0&by=%1

Note that the server member.access and member.name properties use the Java 1.1 notation of "{n}" for substitution variables, while this member.document applet property use the Java 1.0.2 notation of "%n".

The VolanoChat applet fills in this URL template such that:

• %0 is filled in with the member's nickname, and
• %1 is filled in with the nickname of the person clicking the link, if available. This field is an empty string if the nickname is not available.

The requestor's nickname is available if the requestor is clicking the link in a chat room or is also a member. The nickname is unavailable if the requestor is not a member and is clicking the link from the main chat panel outside any chat room. Members will always have their name filled in the %1 variable, whether they've entered a room or not.

General notes

Make sure to set the content type of the XML response document to plain text by adding the following header to your member.access and member.name script response:

Content-type: text/plain

You should send back the HTML response document of the member.document script as HTML text with:

Content-type: text/html

As with any HTTP GET request, the nickname and password variables are URL encoded before being sent. So "John Smith" is sent as either "John+Smith" or "John%20Smith", and a password string such as "tes/ting" is sent as "tes%2Fting". Most CGI script libraries have simple routines for decoding the variables from their URL encoded form into their original values. Note that it is the responsibility of the member access, name, and document scripts to decide whether things such as upper and lower case are important.

When forming the XML response document, you need to put the tags exactly as shown in the examples above, although you may also put the result on one line as follows:

<result value="false"></result>

or put the profile or error string on multiple lines as follows:

<result value="true">
This is the
profile.
</result>

In the latter case, you'll get the single line "This is the profile." for the profile.

Check HTML

Table of Contents