NAME¶
ns_register_adp, ns_register_proc, ns_unregister_adp, ns_unregister_proc -
Facilities to manage mappings for HTTP requests to Tcl procedures or ADP files
SYNOPSIS¶
ns_register_adp ?-noinherit? method url file
ns_register_proc ?-noinherit? method url proc ?arg?
ns_unregister_adp ?-noinherit? method url
ns_unregister_proc ?-noinherit? method url
DESCRIPTION¶
These commands manage mappings of HTTP request to Tcl procedures or ADP files.
The server will invoke the given procedure or ADP file when the corresponding
method/url combination is requested.
The
method is normally one of
GET or
POST although there is
no restriction as internally method is always treated simply as a string.
Specialized applications, for example, a WebDav file server, could register
additional methods such as
PUT,
DELETE, or
BROWSE.
The
url parameter specifies the trailing, pathname portion of an url, for
example,
/myapp/search. Requests for the specified url or any url's
with additional path elements which do not have more specific mappings will be
handled by the given procedure or ADP file. This behavior can be changed with
the optional
-noinherit flag in which case only exact match url's will
be handled.
In addition, for the final pathname component, a "glob-style" pattern
may also be specified to further restrict the match. For example,
/myapp/*.adp would handle requests for all url which start with
/myapp and have a final pathname component which ends with the
.adp extension. Note that the method cannot be specified as a glob
pattern, i.e., attempting to map "*" will map the single character
string "*" as the method, it will not map all possible methods.
Calls to
ns_register_proc and
ns_register_adp are normally placed
in server initialization scripts. The
ns_unregister_proc and
ns_unregister_adp commands are rarely used, normally only in the
context of development or debugging.
- ns_register_adp ?-noinherit? method url file
- This command maps the given method/url combination to a specific ADP file.
The file argument must be an absolute pathname and a regular file.
When the server receives a matching request, it will allocate a Tcl
interpreter and invoke the ns_adp_include command with the given
file, returning the results of the output buffer to the client when the
command returns.
Note it is also possible to provide mappings for ADP files in the config
file as well although those mappings are intended to support mixing of ADP
and static files in the server's basic page root. Using
ns_register_adp can provide more general mappings, not requiring
actual ADP files to exist at the corresponding location in the filesystem.
- ns_register_proc ?-noinherit? method url proc
?arg?
- This command maps the given method/url combination to a Tcl procedure.
When the server receives a matching request, it allocates a Tcl
interpreter and calls Tcl_Eval with a script constructed of the
procedure with zero, one, or two arguments depending on the arguments
expected for the procedure. If the procedure accepts no arguments, none
are passed and the arg parameter to ns_register_proc, if
given, is ignored. If it takes one argument, the procedure is passed the
optional arg parameter or a null string if no argument was given.
If the procedure accepts two arguments, the first argument will be the
"connection id" followed by the argument as described for the
case of one argument. The connection id is a small string of the form
"cns#" where # is a monotonically increasing integer value which
will eventually wrap after the server has been running for a long time.
This id is also returned via the the ns_conn id command. This
connection id is for information purposes only and is is otherwise useless
and not required to be passed to any other AOLserver Tcl command. See the
EXAMPLES section for details on how various arguments are handled
for request procedures.
- ns_unregister_adp ?-noinherit? method url
- ns_unregister_proc ?-noinherit? method url
- These commands are identical and can be used to remove any mapping for the
given method/url. Note that no check is made to confirm the given mapping
exists or was in fact a Tcl procedure, ADP file, or some other C-level
mapping created with the Ns_RegisterRequest routine. The optional
-noinherit flag, if specified, requests removal of mappings
previously made with the -noinherit flag with the commands above or
via the NS_OP_NOINHERIT bit set in a call to the
Ns_RegisterRequest routine.
EXAMPLES¶
The following example demonstrates the use of the
-noinherit flag. Assume
the following startup initializations code:
ns_register_proc -noinherit GET /foo/bar Aproc
ns_register_proc GET /foo/bar Bproc
ns_register_proc GET /foo/bar/hmm Cproc
In this case,
Aproc will be called when the requested URL is exactly
/foo/bar while
Bproc will be called when the requested URL is
anything 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.
The following example demonstrates the multiple forms of which a Tcl procedure
can be defined:
ns_register_proc GET /zeroargs 0args myarg
ns_register_proc GET /onearg 1arg myarg
ns_register_proc GET /twoargs 2args myarg
ns_register_proc GET /twoargs 2args myarg
proc 0args {} {
ns_returnnotice 200 "no args"
} ;# noargs
proc 1arg {arg} {
ns_returnnotice 200 "arg: $arg"
} ;# context
proc 2args {conn arg} {
ns_returnnotice 200 "connid: $conn, arg: $arg"
} ;# conncontext
When a request for the /twoargs URL is received, the
2args procedure will
be called with the value of the connection id as the
conn variable and
"myarg" as the value of the
arg variable.
When the server receives a request for
/onearg, the server will invoke
the
1arg procedure with just "myarg" as the value for the
arg procedure variable. The connection id, if needed, can be obtained
with
ns_conn id.
Finally, when the server receives a request for
/zeroargs, the
0args procedure will be called with no options. The "myarg"
value passed to
ns_register_proc is ignored and the connection id, if
needed, can be obtained with
ns_conn id.
SEE ALSO¶
ns_adp(n),
Ns_RegisterRequest(3), Ns_UrlSpecificGet(n), Ns_UrlSpecificSet(n)
KEYWORDS¶
request callback, connection