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