Annotation of libwww/Library/src/HTPEP.html, revision 2.5
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:
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.
2.3 frystyk 97: <PRE>
98: extern HTPEPModule * HTPEP_newModule(const char * protocol,
99: HTNetBefore * before,
100: HTNetAfter * after,
101: HTUTree_gc * gc);
2.1 frystyk 102: </PRE>
103: <H3>
104: Find a PEP Module
105: </H3>
106: <PRE>extern HTPEPModule * HTPEP_findModule (const char * protocol);
107: </PRE>
108: <H3>
109: Delete a PEP Module
110: </H3>
111: <PRE>extern BOOL HTPEP_deleteModule (const char * protocol);
112: </PRE>
113: <H3>
114: Delete ALL PEP modules
115: </H3>
116: <PRE>extern BOOL HTPEP_deleteAllModules (void);
117: </PRE>
118: <H2>
119: Handling the URL Tree
120: </H2>
121: <P>
122: The PEP information is stored as <A HREF="HTUTree.html">URL Trees</A>. The
123: root of a URL Tree is identified by a <I>hostname</I> and a <I>port number</I>.
124: Each URL Tree contains a set of templates and realms which can be used to
125: predict what information to use in a hierarchical tree.
126: <P>
127: The URL trees are automatically collected after some time so the application
128: does not have to worry about freeing the trees. When a node in a tree is
129: freed, the gc registered as part of the PEP Module is called.
130: <P>
131: Server applications can have different PEP setups for each hostname and port
132: number, they control. For example, a server with interfaces
133: "<CODE>www.foo.com</CODE>" and "<CODE>internal.foo.com</CODE>" can have different
134: protection setups for each interface.
135: <H3>
136: Add information to the Database
137: </H3>
138: <P>
139: Add a PEP information node to the database. If the entry is already found
140: then it is replaced with the new one. The template must follow normal URI
141: syntax but can include a wildcard Return YES if added (or replaced), else
142: NO
143: <PRE>extern HTPEPModule * HTPEP_findModule (const char * name);
144: </PRE>
145: <H2>
146: The PEP Manager Filters
147: </H2>
148: <P>
149: As mentioned, the <I>PEP Manager</I> is itself a set of
150: <A HREF="HTFilter.html">filters</A> that can be registered by the
151: <A HREF="HTNet.html">Net manager</A>.
152: <PRE>
2.3 frystyk 153: extern HTNetBefore HTPEP_beforeFilter;
154: extern HTNetAfter HTPEP_afterFilter;
2.1 frystyk 155: </PRE>
156: <PRE>
157: #endif /* NOT HTPEP_H */
158: </PRE>
159: <P>
160: <HR>
161: <ADDRESS>
2.5 ! frystyk 162: @(#) $Id: HTPEP.html,v 2.4 1997/02/16 18:42:48 frystyk Exp $
2.1 frystyk 163: </ADDRESS>
164: </BODY></HTML>
Webmaster