HomeVisionXL

Plug-ins

Downloads

Tools

Other

HomeVisionXL Web Server Plugin

The Web Server plugin provides the same functionality as the Web Server of the Windows HomeVision software with two additions: After installing and enabling the Web Server plug-in, full documentation of the features and operation of the Web Server will be available in the HomeVisionXL help system. The Web Server help pages can be accessed from the Help menu, or by pressing F1 on the Web Server configuration screen. You can browse through all the help pages for the Web Server using the << and >> buttons on the help viewer toolbar.

Basic operation

The web server responds to incoming requests from web browsers. Such a request specifies a Universal Resource Identifier (URI) and possibly some additional post data generated from a HTML form. A URI consists of a number of distinctive parts:
  1. The naming scheme of the mechanism used to access the resource.
  2. The name of the machine hosting the resource.
  3. The port number handling access to the resource (optional).
  4. The name of the resource itself, given as a path.
  5. The fragment identifier, specifying a location within the resource (optional).
  6. A query string containing additional data to be forwarded to the resource (optional).
An example of a URI containing all the parts is:
http://localhost:1033/index.cgi#information?device=HomeVision

The different parts of this URI are:

  1. http
  2. localhost
  3. 1033
  4. index.cgi
  5. information
  6. device=HomeVision
The other characters in the URI are needed to be able to unambiguously distinguish the different parts.

The web server plugin is only able to handle URIs for the HTTP mechanism. The hostname has to refer to the machine the web server is running on. The port number can be configured on the web server configuration dialog.

In addition to the standard tags that may be present in a HTML document, the web server plugin will scan the document for special HV tags and substitute the appropriate text. For details, see the Windows HomeVision documentation for the web browser. Also the methods for performing actions on the HomeVision controller described there work with the web server plugin.

WAP devices

Thanks to Ron Boston, the web server plugin is now also capable of supporting WAP (Wireless Access Protocol) devices using Wireless Markup Language (WML). The HV WML capability allows web access to HV via cell phones and other WAP enabled devices.

The standard set of predefined web pages is also available in a WML version. These web pages will be served when the requested URI specifies the page name with a wml extension.

If the URI doesn't specify a full resource name but just a path upto a directory name, the software will examine the accept parameter in the HTTP request. If the list of MIME types that the requesting device will accept includes text/vnd.wap.wml, it is assumed to be a WAP device. In that case the server will try to find one of the following file names in the indicated directory: index.wml, index.cgi, index.html. For non-WAP devices the list of file names the server will look for is: index.html, index.htm, index.cgi. The first file from the list that is found will go through the normal pre-processing and is then returned to the requesting device.

Dynamically generated resources

The web server plugin is not only able to return static HTML pages, it can also run executable (CGI) programs or scripts that generate a page on the fly. The plugin recognizes a few file extensions that indicate the type of resource:
.html and .htm
These are the usual HTML formatted files.
.wml
These are WML formatted files intended for WAP phones.
.txt
Plain text without embedded formatting information.
.css
Cascading style sheet definitions.
.gif, .jpg, .jpeg and .png
Different image formats.
Any other file will be checked to determine if it is executable. If it is, it will be executed and the standard output and standard error of the process are returned to the web browser that initiated the request.

The executable generating the dynamic web pages may be written in any programming- or scripting language available on the machine that runs the web server. Examples: sh script, tcl script, perl script, compiled C program, etc. The output of the program must start with one or more lines that complete the response header. In its simplest form this is just an empty line indicating the end of the response header. All other lines of the response header must contain an identifier, a colon and a value. Anything else will result in an error.

The default mime type associated with a dynamic web page is text/html. A CGI program can change this by including the Content-Type identifier in the response header. Example: To indicate plain text content the output of the program should start with: 

Content-Type: text/plain

<The plain text starts here>
Other useful identifiers that can be used in the response header are:
  • Set-Cookie
  • Status
  • Location
Useful (and less useful) information is passed to the CGI program through the environment and the standard input of the program. Below is alist of the most important variables:
PATH
The search path for commands. It is a colon-separated list of directories in which the shell looks for commands.

REQUEST_METHOD
Indicates the way additional data is passed to the resource. Possible values are:
  • GET: The data is included in the query string part of the URI. In this case the data is presented to the CGI program in the QUERY_STRING environment variable.
  • POST: The data follows the request header. With this method the data is passed to the CGI program through its standard input. The size of the data is stored in the CONTENT_LENGTH environment variable.


QUERY_STRING
The query string part of the URI.

CONTENT_LENGTH
The number of bytes of data available on the standard input. This variable only exists for POST requests.

HTTP_ACCEPT
A list of MIME types that the requesting device can handle. You can use this in your cgi script to determine if the information generated by the script should be presented in html or wml format.

HTTP_REFERER
The web page that contains the link that was followed to reach this page.

Posted data is always first parsed by the web server plugin to check for any special HomeVision actions tags. The appropriate actions are executed before the CGI program is started. If the output of the CGI program has a mime type of text/html or text/vnd.wap.wml, the output is scanned for HV information tags. These tags are automatically replaced with the specified information. For all other mime types the output of the CGI program is passed unaltered.

Any CGI program running longer than 5 minutes is assumed to be stuck in a loop and will be killed.

Last modified: 5 March 2009, 18:09 CET