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. For example, the URL /NS/Admin is bound to a Tcl script that generates and returns a server administration page. 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. For example, a single Tcl script handles a URL that starts at /NS/Db/GetSearchForm. The names of the database pool and database table for which to generate the search form are specified as the fourth and fifth elements of the URL path, for example: /NS/Db/GetSearchForm/nsdbpool/employees.

Operation Arguments

The nsdbpool and employees parts of the URL are arguments to the operation. In this case, where the pool and table names are part of the URL, individual permission records can be set for different tables. For example, you may add a record to restrict the /NS/Db/GetSearchForm/nsdbpool/employees URL so only system users may access the search form for a table of employees.*

The permission records for other search forms are unaffected by this permission record. Most likely, they inherit their records from the /NS/GetSearchForm record or perhaps the /NS or / records.

Another 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, the operation function above could have been (but was not) written to find the table name as a query string argument and the URL would have taken the form /NS/Db/GetSearchForm?employees. In this case, where the query string specifies the operation's arguments, only one record can specify the permissions for all possible table search forms. 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. On the other hand, the Tcl script operation that handles the /NS/About URL is a non-inherited function because it is designed to only handle the /NS/About URL (the /NS/About/a/b/c URL would not make sense in this case).

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 virtual server.*

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.