Annotation of libwww/Library/src/HTResponse.html, revision 2.9
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <!-- Changed by: Henrik Frystyk Nielsen, 15-Jul-1996 -->
2.3 frystyk 4: <TITLE>W3C Sample Code Library libwww Response Class</TITLE>
2.1 frystyk 5: </HEAD>
6: <BODY>
7: <H1>
8: The Response Class
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>
2.2 frystyk 17: The response object is created as a placeholder for the response received
18: by the remote server. All filters can then use the information passed in
19: the response and act appropriately. The response objetc is deleted automatically
20: when the corresponding request object is deleted. We try and do some fancy
21: tricks in order to do lazy parsing and reusing parsed values so that we can
22: optimize the code.
2.1 frystyk 23: <P>
24: This module is implemented by <A HREF="HTResponse.c">HTResponse.c</A>, and
2.8 frystyk 25: it is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.1 frystyk 26: Library</A>.
27: <PRE>
28: #ifndef HTRESPONSE_H
29: #define HTRESPONSE_H
30:
31: typedef struct _HTResponse HTResponse;
32:
33: #include "HTEvent.h"
34: #include "HTList.h"
35: #include "HTAssoc.h"
36: #include "HTFormat.h"
37: #include "HTUser.h"
38: </PRE>
39: <H2>
40: Creating and Deleting Response Objects
41: </H2>
42: <P>
43: The response obejct gets created when we start receiving a response from
44: a remote server.
45: <H3>
46: Create Response Object
47: </H3>
48: <P>
49: Creates a new response object with a corresponding User Profile object.
50: <PRE>
51: extern HTResponse * HTResponse_new (void);
52: </PRE>
53: <H3>
54: Delete Response Object
55: </H3>
56: <P>
57: This function deletes the object and cleans up the memory.
58: <PRE>
59: extern BOOL HTResponse_delete (HTResponse * response);
60: </PRE>
61: <H2>
62: Redirections
63: </H2>
64: <P>
65: When a redirection response is returned to the Library, for example from
66: a remote HTTP server, this code is passed back to the application. The
67: application can then decide whether a new request should be established or
68: not. These two methods return the redirection information required to issue
69: a new request, that is the new anchor and any list of keywords associated
70: with this anchor.
71: <PRE>
72: extern HTAnchor * HTResponse_redirection (HTResponse * response);
73: extern BOOL HTResponse_setRedirection (HTResponse * response, HTAnchor * anchor);
74: </PRE>
75: <H2>
76: Retry Request After
77: </H2>
78: <P>
79: Some services, for example HTTP, can in case they are unavailable at the
80: time the request is issued send back a time and date stamp to the client
81: telling when they are expected to back online. In case a request results
82: in a HT_RETRY status, the application can use any time indicated in this
83: field to retry the request at a later time. The Library does not initiate
84: any request on its own - it's for the application to do. The time returned
85: by this function is in calendar time or -1 if not available.
86: <PRE>
87: extern time_t HTResponse_retryTime (HTResponse * response);
88: extern BOOL HTResponse_setRetryTime (HTResponse * response, time_t retry);
89: </PRE>
90: <H2>
91: <A NAME="Access">HTTP Access Authentication Challanges</A>
92: </H2>
93: <P>
94: When a access denied response is returned to the Library, for example from
95: a remote HTTP server, this code is passed back to the application. The
96: application can then decide whether a new request should be established or
97: not. These two methods return the authentication information required to
98: issue a new request, that is the new anchor and any list of keywords associated
99: with this anchor.
100: <PRE>
101: extern BOOL HTResponse_addChallenge (HTResponse * response, char * token, char * value);
102:
103: extern BOOL HTResponse_deleteChallengeAll (HTResponse * response);
104:
105: extern HTAssocList * HTResponse_challenge (HTResponse * response);
106: </PRE>
107: <H3>
108: Realms
109: </H3>
110: <PRE>
111: extern BOOL HTResponse_setRealm (HTResponse * response, char * realm);
112: extern const char * HTResponse_realm (HTResponse * response);
113: </PRE>
114: <H3>
115: Access Authentication Schemes
116: </H3>
117: <PRE>
118: extern BOOL HTResponse_setScheme (HTResponse * response, char * scheme);
119: extern const char * HTResponse_scheme (HTResponse * response);
120: </PRE>
121: <H2>
122: HTTP Connection Control Directives
123: </H2>
124: <P>
125: The connection control directives are all part of the connection header and
126: control the behavior of this connection. The respose object contains the
127: connection information that we have received in the response.
128: <PRE>
129: extern BOOL HTResponse_addConnection (HTResponse * response,
130: char * token, char * value);
131: extern BOOL HTResponse_deleteConnectionAll (HTResponse * response);
132: extern HTAssocList * HTResponse_connection (HTResponse * response);
133: </PRE>
134: <H2>
135: HTTP Extensions (PEP)
136: </H2>
137: <P>
138: HTTP can be extended in several ways but traditionally it has been by using
139: new headers. Here we present a new idea which provides a framework for describing
140: extensions and their scope. This is only an idea an may be modified later!
141: The implementation of the extensions can be found in the
142: <A HREF="HTPEP.html">PEP module</A>
143: <H3>
144: Protocol
145: </H3>
146: <P>
147: This association list is a list of the extension directives that were received
148: as part of the response.
149: <PRE>
150: extern BOOL HTResponse_addProtocol (HTResponse * response,
151: char * token, char * value);
152: extern BOOL HTResponse_deleteProtocolAll (HTResponse * response);
153: extern HTAssocList * HTResponse_protocol (HTResponse * response);
154: </PRE>
155: <H3>
156: Protocol Info
157: </H3>
158: <P>
159: This association list is a list of the extension directives that were received
160: as part of the response.
161: <PRE>
162: extern BOOL HTResponse_addProtocolInfo (HTResponse * response,
163: char * token, char * value);
164: extern BOOL HTResponse_deleteProtocolInfoAll (HTResponse * response);
165: extern HTAssocList * HTResponse_protocolInfo (HTResponse * response);
166: </PRE>
167: <H3>
168: Protocol Request
169: </H3>
170: <P>
171: This association list is a list of the extension directives that were received
172: as part of the response.
173: <PRE>
174: extern BOOL HTResponse_addProtocolRequest (HTResponse * response,
175: char * token, char * value);
176: extern BOOL HTResponse_deleteProtocolRequestAll (HTResponse * response);
177: extern HTAssocList * HTResponse_protocolRequest (HTResponse * response);
178: </PRE>
179: <H2>
180: HTTP Cache Control Directives
181: </H2>
182: <P>
183: This association list is a list of the cache control directives that have
184: been received as part of the response. We also keep track of whether the
185: response is cachable or not.
186: <PRE>
187: extern BOOL HTResponse_addCacheControl (HTResponse * response,
188: char * token, char *value);
189: extern BOOL HTResponse_deleteCacheControlAll (HTResponse * response);
190: extern HTAssocList * HTResponse_cacheControl (HTResponse * response);
191: </PRE>
192: <H3>
193: Is the response Cachable?
194: </H3>
195: <P>
196: The various <CODE>cache-control</CODE> headers and directives decides whether
197: an object is cachable or not. Check these methods before starting caching!
198: <PRE>
199: extern BOOL HTResponse_isCachable (HTResponse * me);
200: extern BOOL HTResponse_setCachable (HTResponse * me, BOOL mode);
201: </PRE>
202: <H3>
203: Has the Response been Cached?
204: </H3>
205: <P>
206: When we gc the response object we need to know whether the header lists have
207: been inherited by other objects (the <A HREF="HTAnchor.html">anchor</A> object,
208: for example) and hence shouldn't be deleted. We can tell the response object
209: this by using the following method call
210: <PRE>
211: extern BOOL HTResponse_isCached (HTResponse * me, BOOL mode);
212: </PRE>
213: <H3>
214: Some Cache-Control helper Methods
215: </H3>
216: <P>
217: Some useful helper functions for handling specific response cache directives
218: <PRE>
219: extern time_t HTResponse_maxAge (HTResponse * response);
220: extern BOOL HTResponse_mustRevalidate (HTResponse * response);
221: extern char * HTResponse_noCache (HTResponse * response);
222: </PRE>
223: <H3>
224: Partial responses and Range Retrievals
225: </H3>
226: <P>
227: Libwww can issue range requests in case we have already obtained a part of
228: the entity body. Since all HTTP entities are represented in HTTP messages
229: as sequences of bytes, the concept of a byte range is meaningful for any
230: HTTP entity. (However, not all clients and servers need to support byte-range
231: operations.) Byte range specifications in HTTP apply to the sequence of bytes
232: in the entity-body (not necessarily the same as the message-body). A byte
233: range operation may specify a single range of bytes, or a set of ranges within
234: a single entity.
235: <PRE>
236: extern BOOL HTResponse_addRange (HTResponse * response,
237: char * unit, char * range);
238: extern BOOL HTResponse_deleteRangeAll (HTResponse * response);
239: extern HTAssocList * HTResponse_range (HTResponse * response);
240: </PRE>
241: <H3>
242: Content Length
243: </H3>
244: <P>
245: We store the content length so that we have an idea of how many bytes to
246: expect.
247: <PRE>
248: extern long int HTResponse_length (HTResponse * response);
249: extern void HTResponse_setLength (HTResponse * response, long int length);
250: extern void HTResponse_addLength (HTResponse * response, long int deltalength);
251: </PRE>
252: <H3>
253: Content Type (Media type)
254: </H3>
255: <P>
256: We store the content-type of the response along with the charset, level and
257: all other paramaters that may follow the content-type itself.
258: <PRE>
259: extern HTFormat HTResponse_format (HTResponse * response);
260: extern void HTResponse_setFormat (HTResponse * response, HTFormat format);
261: </PRE>
262: <P>
263: The Response object stores all content type parameters (charset, level, etc.)
264: in an Association list so here you will always be able to find them. We also
265: have a few methods for the special cases: <CODE>charset</CODE> and
266: <CODE>level</CODE> as they are often needed.
267: <PRE>
268: extern HTAssocList * HTResponse_formatParam (HTResponse * response);
269: extern BOOL HTResponse_addFormatParam (HTResponse * response,
270: const char * name, const char * value);
271: </PRE>
272: <H4>
273: Charset parameter to Content-Type
274: </H4>
275: <PRE>
2.9 ! frystyk 276: extern HTCharset HTResponse_charset (HTResponse * response);
2.1 frystyk 277: extern BOOL HTResponse_setCharset (HTResponse * response, HTCharset charset);
278: </PRE>
279: <H4>
280: Level parameter to Content-Type
281: </H4>
282: <PRE>
283: extern HTLevel HTResponse_level (HTResponse * response);
284: extern BOOL HTResponse_setLevel (HTResponse * response, HTLevel level);
285: </PRE>
286: <H3>
287: Content Encodings
288: </H3>
289: <P>
290: The list of encodings that we have received in the response.
291: <PRE>
292: extern HTList * HTResponse_encoding (HTResponse * response);
293: extern BOOL HTResponse_addEncoding (HTResponse * response, HTEncoding enc);
294: </PRE>
295: <H3>
2.7 frystyk 296: Transfer Encodings
297: </H3>
298: <P>
299: The list of encodings that we have received in the response.
300: <PRE>
301: extern HTList * HTResponse_transfer (HTResponse * response);
302: extern BOOL HTResponse_addTransfer (HTResponse * response, HTEncoding te);
303: </PRE>
304: <H3>
2.1 frystyk 305: Content Transfer Encodings
306: </H3>
307: <P>
308: Any transfer encoding that we have received in the response.
309: <PRE>
2.7 frystyk 310: extern HTEncoding HTResponse_contentTransferEncoding (HTResponse * response);
311: extern BOOL HTResponse_setContentTransferEncoding (HTResponse * response,
312: HTEncoding cte);
2.1 frystyk 313: </PRE>
314: <H3>
2.6 frystyk 315: Vary Headers
316: </H3>
317: <P>
318: Any Vary header fields
319: <PRE>
320: extern BOOL HTResponse_addVariant (HTResponse * me, char * token, char * value);
321: extern BOOL HTResponse_deleteVariantAll (HTResponse * me);
322: extern HTAssocList * HTResponse_variant (HTResponse * me);
323: </PRE>
324: <H3>
2.4 frystyk 325: Trailers
326: </H3>
327: <P>
328: Any trailer header fields
329: <PRE>
330: extern BOOL HTResponse_addTrailer (HTResponse * me, char * token, char * value);
331: extern BOOL HTResponse_deleteTrailerAll (HTResponse * me);
332: extern HTAssocList * HTResponse_trailer (HTResponse * me);
333: </PRE>
334:
335: <H3>
2.1 frystyk 336: Original Response Headers
337: </H3>
338: <P>
339: The <A HREF="HTMIME.html">MIME parser</A> may add the original response headers
340: as (name,value) pairs. The information may be picked up by the
341: <A HREF="WWWCache.html">persistent cache manager</A>.
342: <PRE>
343: extern BOOL HTResponse_addHeader (HTResponse * response,
344: char * token, char * value);
345: extern BOOL HTResponse_deleteHeaderAll (HTResponse * response);
346: extern HTAssocList * HTResponse_header (HTResponse * response);
2.5 frystyk 347:
348: extern HTAssocList * HTResponse_handOverHeader (HTResponse * me);
2.1 frystyk 349: </PRE>
350: <PRE>
351: #endif /* HTRESPONSE_H */
352: </PRE>
353: <P>
354: <HR>
355: <ADDRESS>
2.9 ! frystyk 356: @(#) $Id: HTResponse.html,v 2.8 1998/05/14 02:11:01 frystyk Exp $
2.1 frystyk 357: </ADDRESS>
358: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTResponse.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src