Annotation of libwww/Library/src/HTMIME.html, revision 2.33
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.33 ! vbancrof 35:
! 36: #ifdef __cplusplus
! 37: extern "C" {
! 38: #endif
2.6 timbl 39: </PRE>
2.30 frystyk 40: <H2>
41: How to Deal with Unknown Data
42: </H2>
2.29 frystyk 43: <P>
44: When the MIME parser can't find a target stream, for example because the
2.30 frystyk 45: media type is unknown, or it has a content encoding or transfer encoding
46: that it doesn't know about then it has to get rid of the data in some other
47: fashion, for example by dumping it to local disk (but it could also be dumping
48: it to a black hole). The following two functions allow you to set and get
49: the stream to use in this situation. By default, libwww provides an
50: implementation of a save stream as <A HREF="HTFSave.html">HTSaveLocally</A>
51: which you may want to use - this is for example used by the
52: <A HREF="HTProfil.html">current profiles</A>.
2.29 frystyk 53: <PRE>
54: extern void HTMIME_setSaveStream (HTConverter * save_stream);
55: extern HTConverter * HTMIME_saveStream (void);
56: </PRE>
2.30 frystyk 57: <H2>
58: MIME Parse Stream
59: </H2>
60: <P>
61: This stream parses a complete MIME message and if a media type header is
62: found then the stream stack is called to create the nest stream instance
63: in the stream pipe. Any piece of the MIME body is pumped right through the
64: stream.
2.8 frystyk 65: <PRE>
2.20 frystyk 66: extern HTConverter HTMIMEConvert;
2.18 frystyk 67: </PRE>
2.30 frystyk 68: <H2>
69: MIME Header ONLY Parse Stream
70: </H2>
71: <P>
72: This stream parses a complete MIME header and then returnes
73: <CODE>HT_LOADED</CODE>. It does not set up any streams and resting data stays
74: in the buffer. This can be used if you only want to parse the headers before
75: you decide what to do next. This is for example the case with HTTP HEAD requests.
2.18 frystyk 76: <PRE>
2.20 frystyk 77: extern HTConverter HTMIMEHeader;
2.18 frystyk 78: </PRE>
2.30 frystyk 79: <H2>
80: MIME Footer ONLY Parse Stream
81: </H2>
2.24 frystyk 82: <P>
2.23 frystyk 83: Parse only a footer, for example after a chunked encoding.
2.18 frystyk 84: <PRE>
2.23 frystyk 85: extern HTConverter HTMIMEFooter;
86: </PRE>
2.30 frystyk 87: <H2>
88: HTTP 100 Continue Parse Stream
89: </H2>
90: <P>
91: The 100 continue status codes can come at any time - we take them and put
92: the data down a temporary stream. When the 100 continue message has been
93: parsed, the stream returns <CODE>HT_CONTINUE</CODE>
2.27 frystyk 94: <PRE>
95: extern HTConverter HTMIMEContinue;
96: </PRE>
2.30 frystyk 97: <H2>
98: HTTP 101 Switching Protocol Parse Stream
99: </H2>
100: <P>
101: The 101 Switching Protocol status code indicates that the rest of the stream
102: is using another format, protocol, what ever. The result is the same - we
103: are done parsing here and must leave the rest to the next stream which hopefully
104: knows more about how to parse the rest of the stream. The stream stack is
105: called to look for a stream registered for handling
106: <TT><A HREF="HTFormat.html#type">WWW_MIME_UPGRADE</A></TT>. This steam should
107: return <CODE>HT_LOADED</CODE> when it is done, <CODE>HT_ERROR</CODE> if an
108: error occurred and <CODE>HT_OK</CODE> as long as it just reads more data.
109: <PRE>
110: extern HTConverter HTMIMEUpgrade;
111: </PRE>
112: <H2>
113: HTTP 206 Partial Data MIME Parse Stream
114: </H2>
115: <P>
116: In case we sent a <I>Range conditional GET</I> we may get back a 206 Partial
117: Response. This response must be appended to the already existing cache entry
118: before presented to the user. That is, first we load the
119: <A HREF="HTCache.html">cached object</A> and pump it down the pipe and then
120: the new data follows. Only the latter part gets appended to the cache, of
121: course.
2.25 frystyk 122: <PRE>
123: extern HTConverter HTMIMEPartial;
124: </PRE>
2.31 kahan 125: <H2>
126: HTMIME_anchor2response
127: </H2>
128: <P>
129: Copies the anchor HTTP headers into a response object by means
130: of the generic _dispatchParsers function. Written so that we can
131: copy the HTTP headers stored in the cache to the response object.
132: <PRE>
2.32 kahan 133: #ifndef NO_CACHE
134: extern HTConverter HTCacheCopyHeaders;
135: #endif
2.31 kahan 136: </PRE>
2.23 frystyk 137: <PRE>
2.33 ! vbancrof 138: #ifdef __cplusplus
! 139: }
2.1 timbl 140: #endif
2.33 ! vbancrof 141:
! 142: #endif /* HTMIME_H */
2.8 frystyk 143: </PRE>
2.24 frystyk 144: <P>
145: <HR>
2.22 frystyk 146: <ADDRESS>
2.33 ! vbancrof 147: @(#) $Id: HTMIME.html,v 2.32 2000/12/18 17:00:56 kahan Exp $
2.22 frystyk 148: </ADDRESS>
2.24 frystyk 149: </BODY></HTML>
Webmaster