C API Reference -- Ns_RegisterFilter

### Ns_RegisterFilter

#### Overview

Register a filter function to handle a method/URL combination

#### Syntax

        typedef int (Ns_FilterProc) (void *context, Ns_Conn *conn, int
    why);

        Ns_ProcHandle Ns_RegisterFilter(
        char *hServer,
        char *method,
        char *URLpatterns,
        Ns_FilterProc *proc,
        int why,
        void *context
        );

#### Description

This function will register a filter procedure for a method/URL combination on a server. 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 procedures are run in last-registered last-run order. A filter procedure is often used for logging.

The `why` argument can be any of the following, or some combination of them by bitwise OR-ing (with "|") them together:

  NS_FILTER_PRE_AUTH: the filter will be called before authorization of a page
  NS_FILTER_POST_AUTH: the filter will be called after authorization but before a page has been returned
  NS_FILTER_TRACE: the filter will be called after the connection has been totally processed

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

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

- NS_FILTER_BREAK: The server will not process any more pre-authorization filters for this connection, and it will continue on with authorization.

- NS_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 returned a proper response to the client before returning NS_FILTER_RETURN.

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

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

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

- NS_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 to the client before returning NS_FILTER_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:

- NS_OK: The server will continue to the next trace filter.

- NS_FILTER_BREAK, NS_FILTER_RETURN: The rest of the trace filters are ignored

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

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

#### Examples

        static int
        ReportUse(void *context, Ns_Conn *conn, int why){
         int status=NS_OK;
         switch(why){
          case NS_FILTER_PRE_AUTH:
           Ns_Log(Notice, "User trying to access %s",conn->request->url);
             break;
            case NS_FILTER_POST_AUTH:
              Ns_Log(Notice, "User authorized to access %s",conn->request-
    >url);
              break;
            case NS_FILTER_TRACE:
              Ns_Log(Notice, "User has retrieved %s",conn->request->url);
              break;
            default:
              status=NS_ERROR;
          }
          return status;
        }
        int
        Ns_ModuleInit(char *hServer, char *hModule){
          Ns_RegisterFilter(hServer, "GET", "/test/a*", ReportUse,
            Ns_FILTER_PRE_AUTH, NULL);
          Ns_RegisterFilter(hServer, "GET", "/test/b*", ReportUse,
            Ns_FILTER_POST_AUTH, NULL);
          Ns_RegisterFilter(hServer, "GET", "/test/c*", ReportUse,
            Ns_FILTER_TRACE, NULL);
          Ns_RegisterFilter(hServer, "GET", "/test/d*", ReportUse,
            Ns_FILTER_PRE_AUTH | NS_FILTER_POST_AUTH, NULL);
          Ns_RegisterFilter(hServer, "GET", "/test/e*", ReportUse,
            Ns_FILTER_POST_AUTH | NS_FILTER_TRACE, NULL);
          Ns_RegisterFilter(hServer, "GET", "/test/f*", ReportUse,
            Ns_FILTER_PRE_AUTH | Ns_FILTER_POST_AUTH | NS_FILTER_TRACE,
    NULL);

Top of Page
Copyright © 1998-99 America Online, Inc.