1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
<!--plsfield:text-->
<HTML><HEAD>
<TITLE>C API Reference -- Ns_RegisterFilter</TITLE>
<LINK rel=Previous href="c-ch292.htm">
<LINK rel=ToC href="toc.htm">
<LINK rel=Index href="master.htm">
<LINK rel=Next href="c-ch294.htm">
</HEAD><BODY BGCOLOR="#ffffff"><A NAME="topofpage"></A>
<TABLE WIDTH=100%>
<TR>
<TD ALIGN=LEFT>
<A NAME="topofpage"></A> <IMG SRC="as-c-sm.gif">
</TD>
<TD ALIGN=RIGHT>
<A href="c-ch292.htm"><IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm> <IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm> <IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="c-ch294.htm"> <IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<A name="7983"> </A>
</TD>
</TR>
</TABLE>
<a name="368833">
</a><h3>Ns_RegisterFilter</h3>
<a name="368834">
</a><h4>Overview</h4>
Register a filter function to handle a method/URL combination
<a name="368835">
</a><a name="368836">
</a><h4>Syntax</h4>
<pre> <a name="369004"></a>typedef int (Ns_FilterProc) (void *context, Ns_Conn *conn, int
why);
<a name="369015"></a>
<a name="369005"></a>Ns_ProcHandle Ns_RegisterFilter(
<a name="369006"></a>char *hServer,
<a name="369007"></a>char *method,
<a name="369008"></a>char *URLpatterns,
<a name="369009"></a>Ns_FilterProc *proc,
<a name="369010"></a>int why,
<a name="369011"></a>void *context
<a name="369012"></a>);
</pre><p><a name="368843">
</a><h4>Description</h4>
<p><a name="369228">
</a>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.</p>
<p><a name="369203">
</a>The <code>why</code> argument can be any of the following, or some combination of them by bitwise OR-ing (with "|") them together:</p>
<dl>
<dd> NS_FILTER_PRE_AUTH: the filter will be called before authorization of a page
<dd> NS_FILTER_POST_AUTH: the filter will be called after authorization but before a page has been returned
<dd> NS_FILTER_TRACE: the filter will be called after the connection has been totally processed
</dl>
<p><a name="369019">
</a>Using pre-authorization, the procedure will be called (assuming that the method/URL combination matches) just before authorization. If the procedure returns:</p>
<ul><li>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.<a name="369020">
</a>
<p><li>NS_FILTER_BREAK: The server will not process any more pre-authorization filters for this connection, and it will continue on with authorization.<a name="369021">
</a>
<p><li>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.<a name="369022">
</a>
<p></ul><p><a name="369023">
</a>Using post-authorization, the procedure will be called (assuming that the method/URL combination matches) just after successful authorization. If the procedure returns:</p>
<ul><li>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.<a name="369024">
</a>
<p><li>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.<a name="369025">
</a>
<p><li>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.<a name="369026">
</a>
<p></ul><p><a name="369027">
</a>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:</p>
<ul><li>NS_OK: The server will continue to the next trace filter.<a name="369028">
</a>
<p><li>NS_FILTER_BREAK, NS_FILTER_RETURN: The rest of the trace filters are ignored<a name="369029">
</a>
<p></ul><p><a name="369233">
</a>The URLpatterns can contain standard string-matching characters. For example, these are valid URLpatterns:</p>
<dl>
<dd> /employees/*.tcl
<dd> /accounts/*/out
</dl>
<a name="369231">
</a><h4>Examples</h4>
<pre> <a name="369240"></a>static int
<a name="369241"></a>ReportUse(void *context, Ns_Conn *conn, int why){
<a name="369242"></a> int status=NS_OK;
<a name="369243"></a> switch(why){
<a name="369244"></a> case NS_FILTER_PRE_AUTH:
<a name="369245"></a> Ns_Log(Notice, "User trying to access %s",conn->request->url);
<a name="369246"></a> break;
<a name="369247"></a> case NS_FILTER_POST_AUTH:
<a name="369248"></a> Ns_Log(Notice, "User authorized to access %s",conn->request-
>url);
<a name="369249"></a> break;
<a name="369250"></a> case NS_FILTER_TRACE:
<a name="369251"></a> Ns_Log(Notice, "User has retrieved %s",conn->request->url);
<a name="369252"></a> break;
<a name="369253"></a> default:
<a name="369254"></a> status=NS_ERROR;
<a name="369255"></a> }
<a name="369256"></a> return status;
<a name="369257"></a>}
<a name="369258"></a>int
<a name="369259"></a>Ns_ModuleInit(char *hServer, char *hModule){
<a name="369260"></a> Ns_RegisterFilter(hServer, "GET", "/test/a*", ReportUse,
<a name="369261"></a> Ns_FILTER_PRE_AUTH, NULL);
<a name="369262"></a> Ns_RegisterFilter(hServer, "GET", "/test/b*", ReportUse,
<a name="369263"></a> Ns_FILTER_POST_AUTH, NULL);
<a name="369264"></a> Ns_RegisterFilter(hServer, "GET", "/test/c*", ReportUse,
<a name="369265"></a> Ns_FILTER_TRACE, NULL);
<a name="369266"></a> Ns_RegisterFilter(hServer, "GET", "/test/d*", ReportUse,
<a name="369267"></a> Ns_FILTER_PRE_AUTH | NS_FILTER_POST_AUTH, NULL);
<a name="369268"></a> Ns_RegisterFilter(hServer, "GET", "/test/e*", ReportUse,
<a name="369269"></a> Ns_FILTER_POST_AUTH | NS_FILTER_TRACE, NULL);
<a name="369270"></a> Ns_RegisterFilter(hServer, "GET", "/test/f*", ReportUse,
<a name="369237"></a> Ns_FILTER_PRE_AUTH | Ns_FILTER_POST_AUTH | NS_FILTER_TRACE,
NULL);
</pre><p>
<TABLE BORDER="2" CELLPADDING="1" width="100%">
<TR><TD COLSPAN=3><P ALIGN=Center>
<IMG SRC="bluebult.gif">
<A HREF="#topofpage">
<FONT SIZE=-1>Top of Page</FONT></A>
<IMG SRC="bluebult.gif">
</TD></TR>
<TR><TD COLSPAN=3><P ALIGN=Center>
<A href="c-ch292.htm">
<IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm>
<IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm>
<IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="c-ch294.htm">
<IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<BR align=center>
<FONT size=-1>Copyright © 1998-99 America Online,
Inc.</FONT>
</TD></TR></TABLE></BODY></HTML><!--plsfield:end-->
|
