NAME

       ns_register_filter, ns_register_proc, ns_register_trace - Register a filter, proc or trace callback

SYNOPSIS

       ns_register_filter option ?arg arg ...?

       ns_register_proc option ?arg arg ...?

       ns_register_trace option ?arg arg ...?
_________________________________________________________________

DESCRIPTION

   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 URL
       patterns:

       /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   (using: return "filter_break"): The rest of the trace filters are ignored.

       TCL_RETURN  (using: return "filter_break"): The rest of the trace filters are ignored.

       Syntax for the registered procedure:

       The  conn  (connection)  argument  is  optional  for  procedures  registered by ns_register_filter if the
       procedure has 1 or 2 arguments (including why but not including conn). The following  examples  show  the
       variations that can be used in this case:

       ns_register_filter trace GET /noargs filter_noargs
       ns_register_filter trace GET /context filter_context fnord
       ns_register_filter trace GET /conncontext filter_conncontext

       proc filter_noargs { why } {
           ns_log Notice "filter noargs"
           return filter_ok
       } ;# filter_noargs

       proc filter_context { arg why } {
           ns_log Notice "filter context. Arg: $arg"
           return filter_ok
       } ;# filter_noargs

       proc filter_conncontext { conn arg why } {
           ns_log Notice "filter conn context"
           return filter_ok
       } ;# filter_noargs

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

       ns_register_filter postauth GET /threeargs threeargs aaa
       ns_register_filter postauth GET /fourargs fourargs aaa bbb ccc

       proc threeargs { conn context { greeble bork } why } {
           ...
       } ;

       proc fourargs { conn context { greeble bork } {hoover quark} why } {
          ...
       } ;

       When  a  GET  of  /threeargs  is  requested, the conn and why arguments will be filled automatically, the
       context argument will be assigned "aaa" and the greeble argument  will  be  assigned  the  default  value
       "bork".   When  a GET of /fourargs is requested, the conn and why arguments will be filled automatically,
       the context argument will be assigned "aaa", the greeble argument will be assigned "bbb", and the  hoover
       argument will be assigned the default value "quark".

   ns_register_trace:

       Register  a  Tcl  trace  script  to  a  method  and  matching URL.  (Note: This function is obsolete. Use
       ns_register_filter instead.)

       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

       Note  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.

SEE ALSO

       ns_register_proc(n), ns_register_tag(n), ns_register_adptag(n)

KEYWORDS

AOLserver                                              4.0                                 ns_filter(3aolserver)