Annotation of libwww/Library/src/HTPEP.html, revision 2.6
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <!-- Changed by: Henrik Frystyk Nielsen, 8-Jul-1996 -->
2.4 frystyk 4: <TITLE>W3C Sample Code Library libwww PEP Engine</TITLE>
2.1 frystyk 5: </HEAD>
6: <BODY>
7: <H1>
8: PEP Engine
9: </H1>
10: <PRE>
11: /*
12: ** (c) COPYRIGHT MIT 1995.
13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16: <P>
17: The <I>PEP Manager</I> is a registry for <I>PEP Protocols</I> that follow
18: the generic syntax defined by the <A HREF="../../Protocols/">HTTP</A> <I>PEP
19: protocol</I> headers. All <I>PEP Protocols</I> are registered at run-time
20: in form of a <I>PEP Module</I>. A <I>PEP Module</I> consists of the following:
21: <DL>
22: <DT>
23: <B>protocol</B>
24: <DD>
25: The name which is used to identify the protocol.
26: <DT>
27: <B>BEFORE Filter</B>
28: <DD>
29: When a new request is issued, the <I>PEP Manager</I> looks in the URL tree
30: to see if we have any PEP information for this particular request. The search
31: is based on the realm (if known) in which the request belongs and the URL
32: itself. If a record is found then the <I>PEP Manager</I> calls the <I>PEP
33: Module</I> in order to generate the PEP protocol headers.
34: <DT>
35: <B>AFTER Filter</B>
36: <DD>
37: After a request has terminated and the result was lack of required PEP protocol
38: headers, the request should normally be repeated with a new set of PEP protocol
39: headers. The AFTER filter is responsible for extracting the challenge from
40: the HTTP response and store it in the URL tree, so that we next time we request
41: the same URL we know that it is protected and we can ask the user for the
42: appropriate PRP protocol headers.
43: <DT>
44: <B>garbage collection</B>
45: <DD>
46: The PEP information is stored in a <A HREF="HTUTree.html">URL Tree</A> but
47: as it doesn't know the format of the protocol specific parts, you must register
48: a garbage collector (gc). The gc is called when node is deleted in the tree.
49: </DL>
50: <P>
51: <B>Note: </B>The <I>PEP Manager</I> itself consists of <B>BEFORE</B> and
52: an <B>AFTER</B> <A HREF="HTFilter.html">filter</A> - just like the <I>PEP
53: Modules</I>. This means that any <I>PEP Module</I> also can be registered
54: directly as a <B>BEFORE</B> and <B>AFTER</B>
55: <A HREF="HTFilter.html">filter</A> by the <A HREF="HTNet.html">Net Manager</A>.
56: The reason for having the two layer model is that the <I>PEP Manager</I>
57: maintains a single <A HREF="HTUTree.html">URL tree</A> for storing PEP
58: information for all <I>PEP Protocols</I>.
59: <P>
60: A<I> PEP Module</I> has three resources, it can use when creating PEP protocol
61: headers:
62: <UL>
63: <LI>
64: Handle the <I>PEP protocol headers</I> send from the remote party (typically
65: in the form of a HTTP response.
66: <LI>
67: Handle the <I>PEP protocol headers</I> which typically are to part of the
68: next request.
69: <LI>
70: Add information to the <A HREF="HTUTree.html">URL Tree</A>
71: </UL>
72: <P>
73: This module is implemented by <A HREF="HTPEP.c">HTPEP.c</A> (get it?), and
2.5 frystyk 74: it is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.1 frystyk 75: Library</A>.
76: <PRE>
77: #ifndef HTPEP_H
78: #define HTPEP_H
79: #include "HTList.h"
80: #include "HTReq.h"
81: #include "HTUTree.h"
82:
2.6 ! vbancrof 83: #ifdef __cplusplus
! 84: extern "C" {
! 85: #endif
! 86:
2.1 frystyk 87: typedef struct _HTPEPModule HTPEPModule;
88: </PRE>
89: <H2>
90: PEP Module Registration
91: </H2>
92: <P>
93: A <I>PEP Protocol</I> is registered by registering an <I>PEP Module</I> to
94: in the <I>PEP Manager</I>.
95: <H3>
96: Add a PEP Module
97: </H3>
98: <P>
99: You can add a PEP protocol by using the following method. Each of the callback
100: function must have the type as defined below.
2.3 frystyk 101: <PRE>
102: extern HTPEPModule * HTPEP_newModule(const char * protocol,
103: HTNetBefore * before,
104: HTNetAfter * after,
105: HTUTree_gc * gc);
2.1 frystyk 106: </PRE>
107: <H3>
108: Find a PEP Module
109: </H3>
110: <PRE>extern HTPEPModule * HTPEP_findModule (const char * protocol);
111: </PRE>
112: <H3>
113: Delete a PEP Module
114: </H3>
115: <PRE>extern BOOL HTPEP_deleteModule (const char * protocol);
116: </PRE>
117: <H3>
118: Delete ALL PEP modules
119: </H3>
120: <PRE>extern BOOL HTPEP_deleteAllModules (void);
121: </PRE>
122: <H2>
123: Handling the URL Tree
124: </H2>
125: <P>
126: The PEP information is stored as <A HREF="HTUTree.html">URL Trees</A>. The
127: root of a URL Tree is identified by a <I>hostname</I> and a <I>port number</I>.
128: Each URL Tree contains a set of templates and realms which can be used to
129: predict what information to use in a hierarchical tree.
130: <P>
131: The URL trees are automatically collected after some time so the application
132: does not have to worry about freeing the trees. When a node in a tree is
133: freed, the gc registered as part of the PEP Module is called.
134: <P>
135: Server applications can have different PEP setups for each hostname and port
136: number, they control. For example, a server with interfaces
137: "<CODE>www.foo.com</CODE>" and "<CODE>internal.foo.com</CODE>" can have different
138: protection setups for each interface.
139: <H3>
140: Add information to the Database
141: </H3>
142: <P>
143: Add a PEP information node to the database. If the entry is already found
144: then it is replaced with the new one. The template must follow normal URI
145: syntax but can include a wildcard Return YES if added (or replaced), else
146: NO
147: <PRE>extern HTPEPModule * HTPEP_findModule (const char * name);
148: </PRE>
149: <H2>
150: The PEP Manager Filters
151: </H2>
152: <P>
153: As mentioned, the <I>PEP Manager</I> is itself a set of
154: <A HREF="HTFilter.html">filters</A> that can be registered by the
155: <A HREF="HTNet.html">Net manager</A>.
156: <PRE>
2.3 frystyk 157: extern HTNetBefore HTPEP_beforeFilter;
158: extern HTNetAfter HTPEP_afterFilter;
2.1 frystyk 159: </PRE>
160: <PRE>
2.6 ! vbancrof 161: #ifdef __cplusplus
! 162: }
! 163: #endif
! 164:
2.1 frystyk 165: #endif /* NOT HTPEP_H */
166: </PRE>
167: <P>
168: <HR>
169: <ADDRESS>
2.6 ! vbancrof 170: @(#) $Id: HTPEP.html,v 2.5 1998/05/14 02:10:54 frystyk Exp $
2.1 frystyk 171: </ADDRESS>
172: </BODY></HTML>
Webmaster