2000-10-26 22:43:56 +00:00
|
|
|
<html><head>
|
|
|
|
|
<title>GSMimeParser</title>
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
2001-04-25 14:19:57 +00:00
|
|
|
<a href ="GSMimeDocument.html">[Previous] </a>
|
|
|
|
|
<a href ="GSMime.html">[Up] </a>
|
2000-10-26 22:43:56 +00:00
|
|
|
<h1>GSMimeParser</h1>
|
|
|
|
|
<h3>Authors </h3>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
|
|
|
|
|
<dd>
|
|
|
|
|
</dl>
|
2001-03-03 10:00:31 +00:00
|
|
|
<p>Version: $Revision$</p>
|
|
|
|
|
<p>Date: $Date$</p>
|
2000-10-26 22:43:56 +00:00
|
|
|
<h2><a name ="cont-0">GSMimeParser</a></h2>
|
|
|
|
|
<h2><a name ="GSMimeParser">GSMimeParser</a></h2>
|
|
|
|
|
<p><b>Declared in: </b> Foundation/GSMime.h</p>
|
|
|
|
|
<p><b>Inherits from: </b> NSObject</p>
|
|
|
|
|
<p><b>Conforms to: </b> NSObject
|
|
|
|
|
</p>
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
This class provides support for parsing MIME messages
|
2000-11-17 06:55:58 +00:00
|
|
|
into GSMimeDocument objects. Each parser object maintains
|
|
|
|
|
an associated document into which data is stored.
|
2000-10-26 22:43:56 +00:00
|
|
|
</p>
|
|
|
|
|
|
2001-08-07 11:34:59 +00:00
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
You supply the document to be parsed as one or more data
|
|
|
|
|
items passed to the <code>Parse:</code> method, and (if
|
|
|
|
|
the method always returns <code>YES</code>, you give it
|
|
|
|
|
a final <code>nil</code> argument to mark the end of the
|
|
|
|
|
document.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
On completion of parsing a valid document, the
|
|
|
|
|
<code>document</code> method returns the resulting parsed document.
|
|
|
|
|
</p>
|
|
|
|
|
|
2000-10-26 22:43:56 +00:00
|
|
|
|
|
|
|
|
<h2>Instance Variables </h2>
|
|
|
|
|
<ul>
|
|
|
|
|
</ul>
|
|
|
|
|
<h2>Methods </h2>
|
|
|
|
|
<ul>
|
2001-04-25 14:19:57 +00:00
|
|
|
<li ><a href ="GSMimeParser.html#method-0">+mimeParser</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-1">-contextFor:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-2">-data</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-3">-decodeData:fromRange:intoData:withContext:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-4">-document</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-5">-isComplete</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-6">-isInBody</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-7">-isInHeaders</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-8">-parse:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-9">-parseHeader:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-10">-parsingHeaders</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-11">-scanHeader:named:inTo:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-12">-scanSpace:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-13">-scanSpecial:</a>
|
|
|
|
|
<li ><a href ="GSMimeParser.html#method-14">-scanToken:</a>
|
2000-10-26 22:43:56 +00:00
|
|
|
</ul>
|
|
|
|
|
<hr><h2>Class Methods </h2>
|
|
|
|
|
<h3><a name ="method-0">mimeParser</a></h3>
|
|
|
|
|
+ (GSMimeParser*) <b>mimeParser</b>;<br>
|
|
|
|
|
|
|
|
|
|
Create a parser.
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<hr><h2>Instances Methods </h2>
|
2000-11-17 13:27:22 +00:00
|
|
|
<h3><a name ="method-1">contextFor:</a></h3>
|
|
|
|
|
- (GSMimeCodingContext*) <b>contextFor:</b> (NSDictionary*)headerInfo;<br>
|
|
|
|
|
|
|
|
|
|
Return a coding context object to be used for decoding data
|
|
|
|
|
according to the scheme specified in the header.
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
The default implementation supports the following transfer
|
|
|
|
|
encodings specified in either a <code>transfer-encoding</code>
|
|
|
|
|
of <code>content-transfer-encoding</code> header -
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2001-04-25 14:19:57 +00:00
|
|
|
<li >base64
|
|
|
|
|
<li >quoted-printable
|
|
|
|
|
<li >binary
|
|
|
|
|
<li >7bit
|
|
|
|
|
<li >8bit
|
|
|
|
|
<li >chunked (for HTTP/1.1)
|
2000-11-17 13:27:22 +00:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-2">data</a></h3>
|
|
|
|
|
- (NSData*) <b>data</b>;<br>
|
|
|
|
|
|
|
|
|
|
Return the data accumulated in the parser. If the parser is
|
|
|
|
|
still parsing headers, this will be the header data read so far.
|
|
|
|
|
If the parse has parsed the body of the message, this will be
|
|
|
|
|
the data of the body, with any transfer encoding removed.
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-3">decodeData:fromRange:intoData:withContext:</a></h3>
|
2000-11-17 13:27:22 +00:00
|
|
|
- (BOOL) <b>decodeData:</b> (NSData*)sourceData <b>fromRange:</b> (NSRange)aRange <b>intoData:</b> (NSMutableData*)destinationData <b>withContext:</b> (GSMimeCodingContext*)ctxt;<br>
|
2000-11-16 16:20:24 +00:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
Decodes the raw data from the specified range in the source
|
|
|
|
|
data object and appends it to the destination data object.
|
|
|
|
|
The context object provides information about the content
|
|
|
|
|
encoding type in use, and the state of the decoding operation.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
This method may be called repeatedly to incrementally decode
|
|
|
|
|
information as it arrives on some communications channel.
|
|
|
|
|
It should be called with a nil source data item (or with
|
|
|
|
|
the atEnd flag of the context set to YES) in order to flush
|
|
|
|
|
any information held in the context to the output data
|
|
|
|
|
object.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
You may override this method in order to implement
|
|
|
|
|
additional coding schemes.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-4">document</a></h3>
|
2000-11-16 12:10:37 +00:00
|
|
|
- (GSMimeDocument*) <b>document</b>;<br>
|
|
|
|
|
|
|
|
|
|
Returns the object into which raw mime data is being parsed.
|
|
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-5">isComplete</a></h3>
|
|
|
|
|
- (BOOL) <b>isComplete</b>;<br>
|
|
|
|
|
|
|
|
|
|
Returns YES if the document parsing is known to be completed.
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-6">isInBody</a></h3>
|
|
|
|
|
- (BOOL) <b>isInBody</b>;<br>
|
|
|
|
|
|
|
|
|
|
Returns YES if all the document headers have been parsed but
|
|
|
|
|
the document body parsing may not yet be complete.
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-7">isInHeaders</a></h3>
|
|
|
|
|
- (BOOL) <b>isInHeaders</b>;<br>
|
|
|
|
|
|
|
|
|
|
Returns YES if parsing of the document headers has not yet
|
|
|
|
|
been completed.
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<h3><a name ="method-8">parse:</a></h3>
|
2000-10-26 22:43:56 +00:00
|
|
|
- (BOOL) <b>parse:</b> (NSData*)rawData;<br>
|
|
|
|
|
|
2001-08-07 11:34:59 +00:00
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
This method is called repeatedly to pass raw mime data into
|
|
|
|
|
the parser. It returns <code>YES</code> as long as it wants
|
|
|
|
|
more data to complete parsing of a document, and <code>NO</code>
|
|
|
|
|
if parsing is complete, either due to having reached the end of
|
|
|
|
|
a document or due to an error.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
Since it is not always possible to determine if the end of a
|
|
|
|
|
MIME document has been reached from its content, the method
|
|
|
|
|
may need to be called with a nil argument after you have
|
|
|
|
|
passed all the data to it ... this tells it that the data
|
|
|
|
|
is complete.
|
|
|
|
|
</p>
|
|
|
|
|
|
2000-10-26 22:43:56 +00:00
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-9">parseHeader:</a></h3>
|
2000-11-16 12:10:37 +00:00
|
|
|
- (BOOL) <b>parseHeader:</b> (NSString*)aRawHeader;<br>
|
2000-10-26 22:43:56 +00:00
|
|
|
|
2000-11-16 12:10:37 +00:00
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
This method is called to parse a header line <em>for the
|
|
|
|
|
current document</em>, split its contents into an info
|
|
|
|
|
dictionary, and add that information to the document.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
The standard implementation of this method scans basic
|
|
|
|
|
information and then calls <code>scanHeaders:named:into:</code>
|
|
|
|
|
to complete the parsing of the header.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
This method also performs consistency checks on headers scanned
|
|
|
|
|
so it is recommended that it is not overridden, but that
|
|
|
|
|
subclasses override <code>scanHeaders:named:into:</code> to
|
|
|
|
|
implement custom scanning.
|
|
|
|
|
</p>
|
|
|
|
|
|
2000-11-17 06:55:58 +00:00
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
As a special case, for HTTP support, this method also parses
|
|
|
|
|
lines in the format of HTTP responses as if they were headers
|
|
|
|
|
named <code>http</code>. The resulting header info dictionary
|
|
|
|
|
contains -
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>HttpMajorVersion
|
|
|
|
|
<dd>The first part of the version number
|
|
|
|
|
<dt>HttpMinorVersion
|
|
|
|
|
<dd>The second part of the version number
|
2000-11-17 15:36:44 +00:00
|
|
|
<dt>NSHTTPPropertyServerHTTPVersionKey
|
|
|
|
|
<dd>The full HTTP protocol version number
|
|
|
|
|
<dt>NSHTTPPropertyStatusCodeKey
|
2000-11-17 06:55:58 +00:00
|
|
|
<dd>The HTTP status code
|
2000-11-17 15:36:44 +00:00
|
|
|
<dt>NSHTTPPropertyStatusReasonKey
|
2000-11-17 06:55:58 +00:00
|
|
|
<dd>The text message (if any) after the status code
|
|
|
|
|
</dl>
|
|
|
|
|
|
2000-11-16 12:10:37 +00:00
|
|
|
|
2000-10-26 22:43:56 +00:00
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-10">parsingHeaders</a></h3>
|
2000-10-26 22:43:56 +00:00
|
|
|
- (BOOL) <b>parsingHeaders</b>;<br>
|
|
|
|
|
|
|
|
|
|
Returns YES if the parser is expecting to read mime headers,
|
|
|
|
|
Returns NO is the parser has already been passed all the
|
|
|
|
|
data containing headers, and is now waiting for the body of
|
2000-11-17 06:55:58 +00:00
|
|
|
the mime message (or has been passed all data).
|
2000-10-26 22:43:56 +00:00
|
|
|
|
2000-11-16 12:10:37 +00:00
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-11">scanHeader:named:inTo:</a></h3>
|
2000-11-16 12:10:37 +00:00
|
|
|
- (BOOL) <b>scanHeader:</b> (NSScanner*)aScanner <b>named:</b> (NSString*)aName <b>inTo:</b> (NSMutableDictionary*)info;<br>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
This method is called to parse a header line and split its
|
|
|
|
|
contents into an info dictionary.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
On entry, the dictionary is already partially filled,
|
|
|
|
|
the name argument is a lowercase representation of the
|
|
|
|
|
header name, and the scanner is set to a scan location
|
|
|
|
|
immediately after the colon in the header string.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
If the header is parsed successfully, the method should
|
|
|
|
|
return YES, otherwise NO.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
You should not call this method directly yourself, but may
|
|
|
|
|
override it to support parsing of new headers.
|
|
|
|
|
</p>
|
|
|
|
|
|
2000-11-17 06:55:58 +00:00
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
You should be aware of the parsing that the standard
|
|
|
|
|
implementation performs, and that <em>needs</em> to be
|
|
|
|
|
done for certain headers in order to permit the parser to
|
|
|
|
|
work generally -
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>content-disposition
|
|
|
|
|
<dd>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>Parameters
|
|
|
|
|
<dd>
|
|
|
|
|
A dictionary containing parameters as key-value pairs
|
|
|
|
|
in lowercase
|
|
|
|
|
|
|
|
|
|
<dt>Value
|
|
|
|
|
<dd>
|
|
|
|
|
The content disposition (excluding parameters) as a
|
|
|
|
|
lowercase string.
|
|
|
|
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dt>content-type
|
|
|
|
|
<dd>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>Parameters
|
|
|
|
|
<dd>
|
|
|
|
|
A dictionary containing parameters as key-value pairs
|
|
|
|
|
in lowercase.
|
|
|
|
|
|
|
|
|
|
<dt>SubType
|
|
|
|
|
<dd>The MIME subtype lowercase
|
|
|
|
|
<dt>Type
|
|
|
|
|
<dd>The MIME type lowercase
|
|
|
|
|
<dt>value
|
|
|
|
|
<dd>The full MIME type (xxx/yyy) in lowercase
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dt>content-transfer-encoding
|
|
|
|
|
<dd>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>Value
|
|
|
|
|
<dd>The transfer encoding type in lowercase
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dt>http
|
|
|
|
|
<dd>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>HttpVersion
|
|
|
|
|
<dd>The HTTP protocol version number
|
|
|
|
|
<dt>HttpMajorVersion
|
|
|
|
|
<dd>The first component of the version number
|
|
|
|
|
<dt>HttpMinorVersion
|
|
|
|
|
<dd>The second component of the version number
|
|
|
|
|
<dt>HttpStatus
|
|
|
|
|
<dd>The response status value (numeric code)
|
|
|
|
|
<dt>Value
|
|
|
|
|
<dd>The text message (if any)
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dt>transfer-encoding
|
|
|
|
|
<dd>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>Value
|
|
|
|
|
<dd>The transfer encoding type in lowercase
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-12">scanSpace:</a></h3>
|
2000-11-17 06:55:58 +00:00
|
|
|
- (BOOL) <b>scanSpace:</b> (NSScanner*)aScanner;<br>
|
|
|
|
|
|
|
|
|
|
A convenience method to scan past any whitespace in the scanner
|
|
|
|
|
in preparation for scanning something more interesting that
|
|
|
|
|
comes after it. Returns YES if any space was read, NO otherwise.
|
2000-11-16 12:10:37 +00:00
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-13">scanSpecial:</a></h3>
|
2000-11-16 12:10:37 +00:00
|
|
|
- (NSString*) <b>scanSpecial:</b> (NSScanner*)aScanner;<br>
|
|
|
|
|
|
|
|
|
|
A convenience method to use a scanner (that is set up to scan a
|
|
|
|
|
header line) to scan in a special character that terminated a
|
|
|
|
|
token previously scanned. If the token was terminated by
|
|
|
|
|
whitespace and no other special character, the string returned
|
|
|
|
|
will contain a single space character.
|
|
|
|
|
|
|
|
|
|
<hr>
|
2000-11-17 15:36:44 +00:00
|
|
|
<h3><a name ="method-14">scanToken:</a></h3>
|
2000-11-16 12:10:37 +00:00
|
|
|
- (NSString*) <b>scanToken:</b> (NSScanner*)aScanner;<br>
|
|
|
|
|
|
|
|
|
|
A convenience method to use a scanner (that is set up to scan a
|
|
|
|
|
header line) to scan a header token - either a quoted string or
|
|
|
|
|
a simple word.
|
|
|
|
|
<ul>
|
2001-04-25 14:19:57 +00:00
|
|
|
<li >Leading whitespace is ignored.
|
|
|
|
|
<li >Backslash escapes in quoted text are converted
|
2000-11-16 12:10:37 +00:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
2000-10-26 22:43:56 +00:00
|
|
|
<hr>
|
|
|
|
|
</body>
|
|
|
|
|
|
|
|
|
|
</html>
|
