ns_register(n) 4.99 "NaviServer Built-in Commands"

NAME

ns_register - Register Tcl/ADP handlers

TABLE OF CONTENTS

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    COMMANDS
    SEE ALSO
    KEYWORDS

SYNOPSIS

ns_register_adptag command ?endcommand? proc ns_register_fastpath ?-noinherit? method url ns_register_filter when method URLpattern script ?args? ns_register_proc ?-noinherit? method URL myproc ?args? ns_unregister_proc ?-noinherit? method URL ns_register_proxy method protocol script ?args? ns_register_trace method URLpattern script ?args? ns_unregister_url2file ?-noinherit? ?-recurse? url ns_register_url2file ?-noinherit? url script ?args? ns_register_fasturl2file ?-noinherit? url ?basepath? ns_register_tcl ?-noinherit? ?-cache cache? method url ?file?

DESCRIPTION

COMMANDS

ns_register_adptag command ?endcommand? proc

ns_register_adptag registers a procedure to be called when the specified beginning and ending tags are used in an ADP. The command is the beginning tag to look for, and the endcommand is the ending tag to look for. The proc is the procedure that will be called when Naviserver encounters those tags when processing an ADP.

There are two ways to use ns_register_adptag, with and without the endcommand parameter:

• If the endcommand parameter is specified, the procedure you specify with proc must be of the form:
  
  proc myadpproc { string tagset }
  
  The string is the string of characters between the beginning tag and the ending tag. The tagset is an ns_set of parameters that were specified with the beginning tag. The return value of the procedure will be sent to the browser in place of the string of text that was specified between the beginning and ending tags.
  
  The string is not parsed, which means that you cannot include ADP tags in the string unless you execute ns_adp_parse on the string inside the procedure that processes the registered ADP tag.
  
  
• If endcommand is not specified, then no closing tag is required. The procedure (proc) will be called every time the specified command is encountered. The procedure should take one parameter, an ns_set containing the parameters to the tag:
  
  proc myadpproc { tagset }

Note: This function cannot be called after the server has started. It must be called in a Tcl script in a virtual server's Tcl directory so that it can be initialized at server startup time.

For example, suppose you want to register a tag that displays the enclosed text only if it is Christmas. You could register the tag as follows:

ns_register_adptag "christmas" "/christmas" xmas proc xmas {string tagset} { if { [ns_fmttime [ns_time] "%m/%d"] == "12/25" } { return $string } }

Then, in an ADP, you could use these tags:

<christmas>Merry Christmas to all, and to all a good night!</christmas>

This example shows the use a registered tag without an endcommand. The tag is registered as follows:

ns_register_adptag hello helloproc proc helloproc { tags } { return "Hello, [ns_set get $tags name]." }

In an ADP, you could then use this tag:

<hello name=Bob>

ns_register_fastpath ?-noinherit? method url

This command register given url pattern to be processed by fast path subsystem, i.e. all requestes that match will be served by corresponding .adp files if resolved. This can be used when there is no global fast path handler installed.

method GET, POST OR HEAD url url pattern

ns_register_filter when method URLpattern script ?args?

ns_register_filter registers a Tcl filter script for the specified method/URL combination on a virtual server. The script can be called at one or more of three given times: pre-authorization, post-authorization before page data has been returned to the user, and after the connection has been processed and closed.

This function will be called at the specified stage of a connection, if the method/URL combination for the filter matches the method/URL combination for the connection using glob style matching.

The URLpattern can contain standard string-matching characters. For example, these are valid URLpatterns:

/employees/*.tcl /accounts/*/out

Valid values for the when argument are: preauth, postauth, and trace.

Using pre-authorization, the procedure will be called (assuming that the method/URL combination matches) just before authorization. If the procedure returns with a code of:

• TCL_OK (using: return "filter_ok"): The server will continue to the next pre-authorization filter for this connection, or, if there are no more pre-authorization filters, it will continue on with authorization.
  
  
• TCL_BREAK (using: return "filter_break"): The server will not process any more pre-authorization filters for this connection, and it will continue on with authorization.
  
  
• TCL_RETURN (using: return "filter_return"): The server will close the connection and will not run any more pre-authorization filters. It will not authorize the request, and it will not run the function registered for this METHOD/URL. It WILL run any trace functions registered for this METHOD/URL, usually including logging. It is assumed that the filter has sent a proper response (e.g., using ns_return) to the client before returning TCL_RETURN.

Using post-authorization, the procedure will be called (assuming that the method/URL combination matches) just after successful authorization. If the procedure returns:

• TCL_OK (using: return "filter_ok"): The server will continue to the next post-authorization filter for this connection, or, if there are no more post-authorization filters, it will run the function registered to handle this request.
  
  
• TCL_BREAK (using: return "filter_break"): The server will not process any more post-authorization filters for this connection, and it will run the function registered to handle this request.
  
  
• TCL_RETURN (using: return "filter_return"): The server will close the connection and will not run any more post-authorization filters and it will not run the function registered for this METHOD/URL. It WILL run any trace functions registered for this METHOD/URL, usually including logging. It is assumed that the filter has returned a proper response (e.g., using ns_return) to the client before returning TCL_RETURN.

Using trace, the procedure will be called (assuming that the method/URL combination match) after the connection has been totally processed and closed. If the procedure returns:

• TCL_OK (using: return "filter_ok"): The server will continue to the next trace filter.
  
  
• TCL_BREAK, TCL_RETURN (using: return "filter_break" or return "filter_return"): The rest of the trace filters are ignored.

ns_register_filter and ns_register_proc are similar, but significantly different. With ns_register_proc, the specified URL is used to match that URL and any URL below it in the hierarchy. Wildcards such as "*" are meaningful only for the final part of the URL, such as /scripts/*.tcl. With ns_register_filter, the URLpattern is used to match URLs as a string with standard string-matching characters. ns_register_proc results in a single match, whereas multiple ns_register_filters can be matched and will be called. Be aware that executing the same ns_register_filter statement more than once (as you might do when re-initializing Tcl) will add the filter more than once! You may want to have a shared variable set so that you don't do this. This example expires all HTML files after an hour.

ns_share -init {set filters_installed 0} filters_installed if {!$filters_installed} { set filters_installed 1 ns_register_filter postauth GET /*.html ExpireSoon 3600 } proc ExpireSoon {seconds why} { ns_set update [ns_conn outputheaders] Expires [ns_httptime [expr $seconds + [ns_time]]] }

ns_register_proc ?-noinherit? method URL myproc ?args?

ns_unregister_proc ?-noinherit? method URL

ns_register_proc registers the procname to handle the specified method/URL combination. When the server gets a matching request, it calls procname with the connection id and any arguments specified here.

If -noinherit is specified, the requested URL must match the specified URL exactly. For example, if the URL specified with ns_register_proc is /foo/bar, procname will not be called unless the requested URL is exactly /foo/bar.

If -noinherit is not specified, the requested URL can match the specified URL or any URL below it. For example, if the URL specified with ns_register_proc is /foo/bar, procname will be called for /foo/bar, /foo/bar/hmm, and any other URL below /foo/bar, provided there is not already another procedure registered for that exact URL or for an URL with a closer match. Note that you must use a glob-style matching character if you want inheritance for file names. For example, if you want /foo/bar to match /foo/bar.html, you must use:

ns_register_proc /foo/bar*

You can register two procedures for any given method/URL combination by calling ns_register_proc once with the -noinherit flag set and once without it. Only one of the procedures will be called for any given request, depending on whether the URL was an exact match or not. For example:

ns_register_proc -noinherit GET /foo/bar Aproc ns_register_proc GET /foo/bar Bproc ns_register_proc GET /foo/bar/hmm Cproc

Aproc will be called when the requested URL is exactly /foo/bar. Bproc will be called when the requested URL is below /foo/bar, provided there is not already another procedure registered to be called for that exact URL or for an URL with a closer match. Cproc (not Bproc) will be called when the requested URL is equal to or below /foo/bar/hmm. Syntax for the registered procedure The conn (connection) argument is optional for procedures registered by ns_register_proc if the procedure has 0 or 1 arguments (not including conn). The following examples show the variations that can be used in this case:

ns_register_proc GET /noargs noargs ns_register_proc GET /context context fnord ns_register_proc GET /conncontext conncontext greeblev proc noargs { } { ns_returnnotice 200 "noargs" };# noargs proc context { context } { ns_returnnotice 200 "context is $context" };# context proc conncontext { conn context } { ns_returnnotice 200 "conncontext is $context" };# conncontext

The conn (connection) argument is required for procedures registered by ns_register_proc if the procedure has 2 or more arguments (not including conn). The conn argument will be filled automatically with the connection information. The first argument following conn will always take the value supplied by ns_register_proc, if there is one, or an empty value. All other arguments must supply a default value. The following examples show the variations that can be used in this case:

ns_register_proc GET /twoargs twoargs fnord ns_register_proc GET /threeargs threeargs fnord fjord proc twoargs { conn context { greeble bork } } { # Do stuff... } proc threeargs { conn context {greeble bork } { hoover quark } { # Do stuff... }

When a GET of /twoargs is requested, the conn argument will be filled automatically, the context argument will be assigned "fnord" and the greeble argument will be assigned the default value "bork". When a GET of /threeargs is requested, the conn argument will be filled automatically, the context argument will be assigned "fnord" and the greeble argument will be assigned "fjord", and the hoover argument will be assigned the default value "quark".

ns_unregister_proc unregisters the procname to handle the speci- fied method/URL combination. This command unregisters any Tcl or C functions previously regis- tered for this method/URL combination and with the same inheri- tance setting. That is, if the -noinherit flag is specified with ns_unregister_proc, the function previously registered with the -noinherit flag using ns_register_proc (or the NS_OP_NOINHERIT flag in ns_RegisterRequest) will be unregistered. If -noinherit is omitted, the function previously registered without the -noin- herit flag (or the NS_OP_NOINHERIT flag) will be unregistered.

ns_register_proxy method protocol script ?args?

ns_register_proxy registers a Tcl script as a handler for the specified method/protocol combination.

Example of HTTP proxy server:

ns_register_proxy GET http http_proxy_handler proc http_proxy_handler { args } { set port [ns_conn port] if {$port == 0} { set port 80 } set url http://[ns_conn host]:$port[ns_conn url]?[ns_conn query] ns_return 200 text/html [ns_httpget $url]] }

ns_register_trace method URLpattern script ?args?

ns_register_trace registers a Tcl script as a trace for the specified method/URL combination. After the server handles the request for the specified method on an URL that matches the URLpattern, it calls the trace script with the connection id and any arguments (args) specified.

The URLpattern can contain standard string-matching characters. For example, these are valid URLpatterns:

/employees/*.tcl /accounts/*/out

ns_register_trace is similar to ns_register_proc except that the pattern-matching for the URL is performed differently. With ns_register_proc, the specified URL is used to match that URL and any URL below it in the hierarchy. Wildcards such as "*" are meaningful only for the final part of the URL, such as /scripts/*.tcl. With ns_register_trace, the URLpattern is used to match URLs as a string with standard string-matching characters.

ns_register_proc results in a single match, whereas multiple ns_register_trace's can be matched and will be called.

ns_unregister_url2file ?-noinherit? ?-recurse? url

ns_register_url2file ?-noinherit? url script ?args?

ns_register_fasturl2file ?-noinherit? url ?basepath?

These commands are used to perform runtime resolving of the requested urls into corresponding files that will be served to the client. They use ns_url2file interface which resolves file for current url.

url Register or unregister callback for given url pattern script Tcl script to be called to return full path to the requested url

ns_register_tcl ?-noinherit? ?-cache cache? method url ?file?

Register Tcl file to be called when request matches method/url combination. This is to enable extention-less urls or for mapping actual files into virtual urls. -cache Specifies for how long to keep result int he cache, in seconds or absolute time file If this argument is omitted, it will register standard C-based callback which will resolve url into absolute .tcl file and execute it.

SEE ALSO

ns_register_adp

KEYWORDS

ADP , request