Scout technical reference

Introduction

In the current implementation, Scout is served from an HTTP server. Thus, web clients and other web servers can easily connect to the service and parse the output.

Each Scout request has two key elements, the channel and the op, short for the operation. channel specifies the target room; op specifies the type of information requested.

Any room is eligible for Scout service. The currently defined op values are:

• count, the number of users in the room
• topic, the topic of the room

Scout data is updated every five minutes.

Constants and conventions

The utility script (useful only with js format) base address is http://scout1.ufs.liveharmony.org/scout/util

Use GET for all requests. The parameters are:

• channel for the channel name; omit the leading hashmark (#)
• op for the operation name; set to topic or count; see above.
• format for the interface name; set to raw or js
• version for the interface version; set to 1

The current version is 1.

Interfaces

Raw interface

The returned string is not HTML-escaped; inserting it directly into a page may create a cross-site scripting vulnerability. Use a suitable escaping function such as PHP's htmlentities() or Perl's HTML::Entities::encode before echoing the string to a user.

JavaScript interface

Webmasters wishing to use the JavaScript interface must first load the utility script.

For each request, the server will output a JavaScript (automatically loaded immediately) that "registers" a piece of data. From that point on, the data returned are available to the rest of the page.

After loading the utility script, the following functions are available:

lh_scout_insert_here(channel, op)

lh_scout_insert_container(channel, op, id)

lh_scout_get_raw(channel, op)

lh_scout_get_html(channel, op)

lh_scout_tohtml(str)

Notes

• You must load the utility script before using these functions or referencing Scout scripts. The utility script constructs the internal data strctures and provides support functions.
• The built-in JavaScript Number function can convert strings to numbers.
• Do not define or modiy any lh_scout functions or variables; your changes may conflict with future versions.

Sample applications

User information

Room statistics

Notes

• All color codes are removed from channel topics.
• Scout retrieves data from the public room list; channels that are set to "private" or "secret" cannot use the current version.
• Topics will not be shown unless at least one user is present in the room.
• The error protocol has not yet been formally defined.
• Scout data (notably topics and room names) are provided by users and not monitored by liveHarmony.

Possible future enhancements

• Improve/create user documentation
• Standardize terms (placement vs. insertion, format vs. interface...currently ad-hoc, confusing synonyms)
• Return the last update time along with each value (this feature is implemented in the back end but not in the front end)
• Improve error reporting (option for preferring an error message to default content?)
• Lookup of individual users
• Provide an XML-RPC interface
• Provide "live" data

Back to top