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