AOLserver Operations

The most common way to extend AOLserver is to write a C function or Tcl script to handle a particular URL or hierarchy of URLs. These functions (or scripts) are called operations.

The AOLserver C and Tcl APIs allow you to register operations that handle a single URL, for example, /extend/myop, or an entire hierarchy of URLs. Registering a hierarchy of URLs is useful for common operations that need to service requests for multiple URLs rooted at the same base URL.

Operation Arguments

One way to send an argument to an operation function is to append the argument as a URL query string, separated from the URL by a single question mark (?). For example, /ABC/accounts?employees. The query string is ignored for permission purposes.

Operation Data

Some operations also require data other than arguments that can be encoded in the URL, typically as additional path elements or query string data. The two most common types are POST data, which includes encode key value pairs of strings that represent the data on an HTML form or PUT data that typically includes the contents of a file to be saved on the server.

In the case of POST data, the AOLserver automatically decodes the form data and stores the strings in an Ns_Set structure within the Ns_Conn structure for the current connection (the Ns_Set and Ns_Conn are described below). The set is accessible to your Tcl script through the ns_set and ns_conn functions.

Other content, such as PUT data, will be available to your operation function as a single block of memory in C that you may copy, modify, or save as you require. Within Tcl you can use the ns_writecontent function to copy the content to a file on disk. Because everything in Tcl is a string, you cannot modify binary content directly. The ns_writecontent function allows you to transfer the content to a disk file in a single operation without having to convert the data into a string format within your script.

Operation Inheritance

When registering a C or Tcl procedure to handle a URL, one of the most important concepts is that of URL inheritance. Inheritance refers to whether your operation is registered to handle a single URL or if it is registered to be "inherited" by URLs lower in the URL hierarchy. For example, the AOLserver operation that gets and saves pages is an inherited operation because it is registered to handle URLs at the root of the AOLserver URL hierarchy ("/") and to handle any other URLs that are not registered to be handled by more specific URLs.

By default operations are inherited. To register operations that are not inherited, you can set a flag when calling the C API function Ns_RegisterRequest() or add the -noinherit flag to the Tcl function ns_register_proc .

Trace, Shutdown, and Access Checking

The C API allows you to register trace, shutdown, and access checking procedures for each server. (These options are not currently supported through the Tcl API.) A trace function is a function that is run after each connection and is ideal for logging operations. A shutdown procedure is invoked just before the server shuts down and can be used, for example, to close a connection to remote server opened by your C API module initialization routine. A C module can also provide the AOLserver with an alternative URL access checking procedure. Your custom procedure may interface with an existing user authorization system.