mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-27 02:30:53 +00:00
fe0730b760
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@10667 72102866-910b-0410-8b05-ffd578937521
351 lines
11 KiB
XML
351 lines
11 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
|
<gsdoc base="GSMimeParser" prev="GSMimeDocument" up="GSMime">
|
|
<head>
|
|
<title>GSMimeParser</title>
|
|
<author name="Richard Frith-Macdonald">
|
|
<email address="rfm@gnu.org"/>
|
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
|
</author>
|
|
<version>$Revision$</version>
|
|
<date>$Date$</date>
|
|
</head>
|
|
<body>
|
|
<chapter>
|
|
<heading>GSMimeParser</heading>
|
|
<class name="GSMimeParser" super="NSObject">
|
|
<declared>Foundation/GSMime.h</declared>
|
|
<conform>NSObject</conform>
|
|
<desc>
|
|
<p>
|
|
This class provides support for parsing MIME messages
|
|
into GSMimeDocument objects. Each parser object maintains
|
|
an associated document into which data is stored.
|
|
</p>
|
|
<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>
|
|
</desc>
|
|
|
|
<method type="GSMimeParser*" factory="yes">
|
|
<sel>mimeParser</sel>
|
|
<desc>
|
|
Create a parser.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSMimeCodingContext*">
|
|
<sel>contextFor:</sel>
|
|
<arg type="NSDictionary*">headerInfo</arg>
|
|
<desc>
|
|
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>
|
|
<list>
|
|
<item>base64</item>
|
|
<item>quoted-printable</item>
|
|
<item>binary</item>
|
|
<item>7bit</item>
|
|
<item>8bit</item>
|
|
<item>chunked (for HTTP/1.1)</item>
|
|
</list>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSData*">
|
|
<sel>data</sel>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>decodeData:</sel>
|
|
<arg type="NSData*">sourceData</arg>
|
|
<sel>fromRange:</sel>
|
|
<arg type="NSRange">aRange</arg>
|
|
<sel>intoData:</sel>
|
|
<arg type="NSMutableData*">destinationData</arg>
|
|
<sel>withContext:</sel>
|
|
<arg type="GSMimeCodingContext*">ctxt</arg>
|
|
<desc>
|
|
<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>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="GSMimeDocument*">
|
|
<sel>document</sel>
|
|
<desc>
|
|
Returns the object into which raw mime data is being parsed.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>isComplete</sel>
|
|
<desc>
|
|
Returns YES if the document parsing is known to be completed.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>isInBody</sel>
|
|
<desc>
|
|
Returns YES if all the document headers have been parsed but
|
|
the document body parsing may not yet be complete.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>isInHeaders</sel>
|
|
<desc>
|
|
Returns YES if parsing of the document headers has not yet
|
|
been completed.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>parse:</sel>
|
|
<arg type="NSData*">rawData</arg>
|
|
<desc>
|
|
<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>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>parseHeader:</sel>
|
|
<arg type="NSString*">aRawHeader</arg>
|
|
<desc>
|
|
<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>
|
|
<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>
|
|
<deflist>
|
|
<term>HttpMajorVersion</term>
|
|
<desc>The first part of the version number</desc>
|
|
<term>HttpMinorVersion</term>
|
|
<desc>The second part of the version number</desc>
|
|
<term>NSHTTPPropertyServerHTTPVersionKey</term>
|
|
<desc>The full HTTP protocol version number</desc>
|
|
<term>NSHTTPPropertyStatusCodeKey</term>
|
|
<desc>The HTTP status code</desc>
|
|
<term>NSHTTPPropertyStatusReasonKey</term>
|
|
<desc>The text message (if any) after the status code</desc>
|
|
</deflist>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>parsingHeaders</sel>
|
|
<desc>
|
|
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
|
|
the mime message (or has been passed all data).
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>scanHeader:</sel>
|
|
<arg type="NSScanner*">aScanner</arg>
|
|
<sel>named:</sel>
|
|
<arg type="NSString*">aName</arg>
|
|
<sel>inTo:</sel>
|
|
<arg type="NSMutableDictionary*">info</arg>
|
|
<desc>
|
|
<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>
|
|
<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>
|
|
<deflist>
|
|
|
|
<term>content-disposition</term>
|
|
<desc>
|
|
<deflist>
|
|
<term>Parameters</term>
|
|
<desc>
|
|
A dictionary containing parameters as key-value pairs
|
|
in lowercase
|
|
</desc>
|
|
<term>Value</term>
|
|
<desc>
|
|
The content disposition (excluding parameters) as a
|
|
lowercase string.
|
|
</desc>
|
|
</deflist>
|
|
</desc>
|
|
|
|
<term>content-type</term>
|
|
<desc>
|
|
<deflist>
|
|
<term>Parameters</term>
|
|
<desc>
|
|
A dictionary containing parameters as key-value pairs
|
|
in lowercase.
|
|
</desc>
|
|
<term>SubType</term>
|
|
<desc>The MIME subtype lowercase</desc>
|
|
<term>Type</term>
|
|
<desc>The MIME type lowercase</desc>
|
|
<term>value</term>
|
|
<desc>The full MIME type (xxx/yyy) in lowercase</desc>
|
|
</deflist>
|
|
</desc>
|
|
|
|
<term>content-transfer-encoding</term>
|
|
<desc>
|
|
<deflist>
|
|
<term>Value</term>
|
|
<desc>The transfer encoding type in lowercase</desc>
|
|
</deflist>
|
|
</desc>
|
|
|
|
<term>http</term>
|
|
<desc>
|
|
<deflist>
|
|
<term>HttpVersion</term>
|
|
<desc>The HTTP protocol version number</desc>
|
|
<term>HttpMajorVersion</term>
|
|
<desc>The first component of the version number</desc>
|
|
<term>HttpMinorVersion</term>
|
|
<desc>The second component of the version number</desc>
|
|
<term>HttpStatus</term>
|
|
<desc>The response status value (numeric code)</desc>
|
|
<term>Value</term>
|
|
<desc>The text message (if any)</desc>
|
|
</deflist>
|
|
</desc>
|
|
|
|
<term>transfer-encoding</term>
|
|
<desc>
|
|
<deflist>
|
|
<term>Value</term>
|
|
<desc>The transfer encoding type in lowercase</desc>
|
|
</deflist>
|
|
</desc>
|
|
</deflist>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>scanSpace:</sel>
|
|
<arg type="NSScanner*">aScanner</arg>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSString*">
|
|
<sel>scanSpecial:</sel>
|
|
<arg type="NSScanner*">aScanner</arg>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSString*">
|
|
<sel>scanToken:</sel>
|
|
<arg type="NSScanner*">aScanner</arg>
|
|
<desc>
|
|
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.
|
|
<list>
|
|
<item>Leading whitespace is ignored.</item>
|
|
<item>Backslash escapes in quoted text are converted</item>
|
|
</list>
|
|
</desc>
|
|
</method>
|
|
|
|
</class>
|
|
</chapter>
|
|
</body>
|
|
</gsdoc>
|