Annotation of libwww/Library/src/HTMIME.html, revision 2.30
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.23 frystyk 121: <PRE>
2.1 timbl 122: #endif
2.8 frystyk 123: </PRE>
2.24 frystyk 124: <P>
125: <HR>
2.22 frystyk 126: <ADDRESS>
2.30 ! frystyk 127: @(#) $Id: HTMIME.html,v 2.29 1999/02/07 18:29:05 frystyk Exp $
2.22 frystyk 128: </ADDRESS>
2.24 frystyk 129: </BODY></HTML>
Webmaster