Annotation of libwww/Library/src/HTPEP.html, revision 2.2
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <!-- Changed by: Henrik Frystyk Nielsen, 8-Jul-1996 -->
4: <TITLE>W3C Reference Library libwww PEP Engine</TITLE>
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
74: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
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:
83: typedef struct _HTPEPModule HTPEPModule;
84: </PRE>
85: <H2>
86: PEP Module Registration
87: </H2>
88: <P>
89: A <I>PEP Protocol</I> is registered by registering an <I>PEP Module</I> to
90: in the <I>PEP Manager</I>.
91: <H3>
92: Add a PEP Module
93: </H3>
94: <P>
95: You can add a PEP protocol by using the following method. Each of the callback
96: function must have the type as defined below.
97: <PRE>extern HTPEPModule * HTPEP_newModule(const char * protocol,
98: HTNetCallback * before,
99: HTNetCallback * after,
100: HTUTree_gc * gc);
101: </PRE>
102: <H3>
103: Find a PEP Module
104: </H3>
105: <PRE>extern HTPEPModule * HTPEP_findModule (const char * protocol);
106: </PRE>
107: <H3>
108: Delete a PEP Module
109: </H3>
110: <PRE>extern BOOL HTPEP_deleteModule (const char * protocol);
111: </PRE>
112: <H3>
113: Delete ALL PEP modules
114: </H3>
115: <PRE>extern BOOL HTPEP_deleteAllModules (void);
116: </PRE>
117: <H2>
118: Handling the URL Tree
119: </H2>
120: <P>
121: The PEP information is stored as <A HREF="HTUTree.html">URL Trees</A>. The
122: root of a URL Tree is identified by a <I>hostname</I> and a <I>port number</I>.
123: Each URL Tree contains a set of templates and realms which can be used to
124: predict what information to use in a hierarchical tree.
125: <P>
126: The URL trees are automatically collected after some time so the application
127: does not have to worry about freeing the trees. When a node in a tree is
128: freed, the gc registered as part of the PEP Module is called.
129: <P>
130: Server applications can have different PEP setups for each hostname and port
131: number, they control. For example, a server with interfaces
132: "<CODE>www.foo.com</CODE>" and "<CODE>internal.foo.com</CODE>" can have different
133: protection setups for each interface.
134: <H3>
135: Add information to the Database
136: </H3>
137: <P>
138: Add a PEP information node to the database. If the entry is already found
139: then it is replaced with the new one. The template must follow normal URI
140: syntax but can include a wildcard Return YES if added (or replaced), else
141: NO
142: <PRE>extern HTPEPModule * HTPEP_findModule (const char * name);
143: </PRE>
144: <H2>
145: The PEP Manager Filters
146: </H2>
147: <P>
148: As mentioned, the <I>PEP Manager</I> is itself a set of
149: <A HREF="HTFilter.html">filters</A> that can be registered by the
150: <A HREF="HTNet.html">Net manager</A>.
151: <PRE>
2.2 ! frystyk 152: extern HTNetCallback HTPEP_beforeFilter, HTPEP_afterFilter;
2.1 frystyk 153: </PRE>
154: <PRE>
155: #endif /* NOT HTPEP_H */
156: </PRE>
157: <P>
158: <HR>
159: <ADDRESS>
2.2 ! frystyk 160: @(#) $Id: HTPEP.html,v 2.1 1996/07/08 19:10:53 frystyk Exp $
2.1 frystyk 161: </ADDRESS>
162: </BODY></HTML>
Webmaster