Annotation of libwww/Library/src/HTMIME.html, revision 2.31.2.1
2.6 timbl 1: <HTML>
2: <HEAD>
2.30 frystyk 3: <TITLE>W3C Sample Code Library libwww MIME Parsers</TITLE>
2.6 timbl 4: </HEAD>
5: <BODY>
2.24 frystyk 6: <H1>
2.30 frystyk 7: Libwww MIME Parsers
2.24 frystyk 8: </H1>
2.9 frystyk 9: <PRE>
10: /*
2.13 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.9 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.24 frystyk 15: <P>
16: The MIME parser stream presents a MIME document with a header and possibly
17: a footer. It recursively invokes the format manager to handle embedded formats
18: like MIME multipart. As well as stripping off and parsing the headers, the
19: MIME parser has to parse any weird MIME encodings it may meet within the
2.30 frystyk 20: body parts of messages, and must deal with <A HREF="HTBound.html">multipart
21: messages</A> (see HTBound.h).
2.24 frystyk 22: <P>
23: This module is implemented to the level necessary for operation with WWW,
24: but is not currently complete for any arbitrary MIME message.
25: <P>
2.9 frystyk 26: This module is implemented by <A HREF="HTMIME.c">HTMIME.c</A>, and it is
2.28 frystyk 27: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.24 frystyk 28: Library</A>.
2.9 frystyk 29: <PRE>
30: #ifndef HTMIME_H
2.1 timbl 31: #define HTMIME_H
32:
33: #include "HTStream.h"
2.15 frystyk 34: #include "HTFormat.h"
2.6 timbl 35: </PRE>
2.30 frystyk 36: <H2>
37: How to Deal with Unknown Data
38: </H2>
2.29 frystyk 39: <P>
40: When the MIME parser can't find a target stream, for example because the
2.30 frystyk 41: media type is unknown, or it has a content encoding or transfer encoding
42: that it doesn't know about then it has to get rid of the data in some other
43: fashion, for example by dumping it to local disk (but it could also be dumping
44: it to a black hole). The following two functions allow you to set and get
45: the stream to use in this situation. By default, libwww provides an
46: implementation of a save stream as <A HREF="HTFSave.html">HTSaveLocally</A>
47: which you may want to use - this is for example used by the
48: <A HREF="HTProfil.html">current profiles</A>.
2.29 frystyk 49: <PRE>
50: extern void HTMIME_setSaveStream (HTConverter * save_stream);
51: extern HTConverter * HTMIME_saveStream (void);
52: </PRE>
2.30 frystyk 53: <H2>
54: MIME Parse Stream
55: </H2>
56: <P>
57: This stream parses a complete MIME message and if a media type header is
58: found then the stream stack is called to create the nest stream instance
59: in the stream pipe. Any piece of the MIME body is pumped right through the
60: stream.
2.8 frystyk 61: <PRE>
2.20 frystyk 62: extern HTConverter HTMIMEConvert;
2.18 frystyk 63: </PRE>
2.30 frystyk 64: <H2>
65: MIME Header ONLY Parse Stream
66: </H2>
67: <P>
68: This stream parses a complete MIME header and then returnes
69: <CODE>HT_LOADED</CODE>. It does not set up any streams and resting data stays
70: in the buffer. This can be used if you only want to parse the headers before
71: you decide what to do next. This is for example the case with HTTP HEAD requests.
2.18 frystyk 72: <PRE>
2.20 frystyk 73: extern HTConverter HTMIMEHeader;
2.18 frystyk 74: </PRE>
2.30 frystyk 75: <H2>
76: MIME Footer ONLY Parse Stream
77: </H2>
2.24 frystyk 78: <P>
2.23 frystyk 79: Parse only a footer, for example after a chunked encoding.
2.18 frystyk 80: <PRE>
2.23 frystyk 81: extern HTConverter HTMIMEFooter;
82: </PRE>
2.30 frystyk 83: <H2>
84: HTTP 100 Continue Parse Stream
85: </H2>
86: <P>
87: The 100 continue status codes can come at any time - we take them and put
88: the data down a temporary stream. When the 100 continue message has been
89: parsed, the stream returns <CODE>HT_CONTINUE</CODE>
2.27 frystyk 90: <PRE>
91: extern HTConverter HTMIMEContinue;
92: </PRE>
2.30 frystyk 93: <H2>
94: HTTP 101 Switching Protocol Parse Stream
95: </H2>
96: <P>
97: The 101 Switching Protocol status code indicates that the rest of the stream
98: is using another format, protocol, what ever. The result is the same - we
99: are done parsing here and must leave the rest to the next stream which hopefully
100: knows more about how to parse the rest of the stream. The stream stack is
101: called to look for a stream registered for handling
102: <TT><A HREF="HTFormat.html#type">WWW_MIME_UPGRADE</A></TT>. This steam should
103: return <CODE>HT_LOADED</CODE> when it is done, <CODE>HT_ERROR</CODE> if an
104: error occurred and <CODE>HT_OK</CODE> as long as it just reads more data.
105: <PRE>
106: extern HTConverter HTMIMEUpgrade;
107: </PRE>
108: <H2>
109: HTTP 206 Partial Data MIME Parse Stream
110: </H2>
111: <P>
112: In case we sent a <I>Range conditional GET</I> we may get back a 206 Partial
113: Response. This response must be appended to the already existing cache entry
114: before presented to the user. That is, first we load the
115: <A HREF="HTCache.html">cached object</A> and pump it down the pipe and then
116: the new data follows. Only the latter part gets appended to the cache, of
117: course.
2.25 frystyk 118: <PRE>
119: extern HTConverter HTMIMEPartial;
120: </PRE>
2.31 kahan 121: <H2>
122: HTMIME_anchor2response
123: </H2>
124: <P>
125: Copies the anchor HTTP headers into a response object by means
126: of the generic _dispatchParsers function. Written so that we can
127: copy the HTTP headers stored in the cache to the response object.
128: <PRE>
2.31.2.1! kahan 129: #ifndef NO_CACHE
! 130: extern HTConverter HTCacheCopyHeaders;
! 131: #endif
2.31 kahan 132: </PRE>
2.23 frystyk 133: <PRE>
2.1 timbl 134: #endif
2.8 frystyk 135: </PRE>
2.24 frystyk 136: <P>
137: <HR>
2.22 frystyk 138: <ADDRESS>
2.31.2.1! kahan 139: @(#) $Id: HTMIME.html,v 2.32 2000/12/18 17:00:56 kahan Exp $
2.22 frystyk 140: </ADDRESS>
2.24 frystyk 141: </BODY></HTML>
Webmaster