GSMimeParser $Revision$ $Date$ GSMimeParser Foundation/GSMime.h NSObject

This class provides support for parsing MIME messages into GSMimeDocument objects. Each parser object maintains an associated document into which data is stored.

You supply the document to be parsed as one or more data items passed to the Parse: method, and (if the method always returns YES, you give it a final nil argument to mark the end of the document.

On completion of parsing a valid document, the document method returns the resulting parsed document.

mimeParser Create a parser. contextFor: headerInfo Return a coding context object to be used for decoding data according to the scheme specified in the header.

The default implementation supports the following transfer encodings specified in either a transfer-encoding of content-transfer-encoding header -

base64 quoted-printable binary 7bit 8bit chunked (for HTTP/1.1) data 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. decodeData: sourceData fromRange: aRange intoData: destinationData withContext: ctxt

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.

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.

You may override this method in order to implement additional coding schemes.

document Returns the object into which raw mime data is being parsed. isComplete Returns YES if the document parsing is known to be completed. isInBody Returns YES if all the document headers have been parsed but the document body parsing may not yet be complete. isInHeaders Returns YES if parsing of the document headers has not yet been completed. parse: rawData

This method is called repeatedly to pass raw mime data into the parser. It returns YES as long as it wants more data to complete parsing of a document, and NO if parsing is complete, either due to having reached the end of a document or due to an error.

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.

parseHeader: aRawHeader

This method is called to parse a header line for the current document, split its contents into an info dictionary, and add that information to the document.

The standard implementation of this method scans basic information and then calls scanHeaders:named:into: to complete the parsing of the header.

This method also performs consistency checks on headers scanned so it is recommended that it is not overridden, but that subclasses override scanHeaders:named:into: to implement custom scanning.

As a special case, for HTTP support, this method also parses lines in the format of HTTP responses as if they were headers named http. The resulting header info dictionary contains -

HttpMajorVersion The first part of the version number HttpMinorVersion The second part of the version number NSHTTPPropertyServerHTTPVersionKey The full HTTP protocol version number NSHTTPPropertyStatusCodeKey The HTTP status code NSHTTPPropertyStatusReasonKey The text message (if any) after the status code parsingHeaders 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). scanHeader: aScanner named: aName inTo: info

This method is called to parse a header line and split its contents into an info dictionary.

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.

If the header is parsed successfully, the method should return YES, otherwise NO.

You should not call this method directly yourself, but may override it to support parsing of new headers.

You should be aware of the parsing that the standard implementation performs, and that needs to be done for certain headers in order to permit the parser to work generally -

content-disposition Parameters A dictionary containing parameters as key-value pairs in lowercase Value The content disposition (excluding parameters) as a lowercase string. content-type Parameters A dictionary containing parameters as key-value pairs in lowercase. SubType The MIME subtype lowercase Type The MIME type lowercase value The full MIME type (xxx/yyy) in lowercase content-transfer-encoding Value The transfer encoding type in lowercase http HttpVersion The HTTP protocol version number HttpMajorVersion The first component of the version number HttpMinorVersion The second component of the version number HttpStatus The response status value (numeric code) Value The text message (if any) transfer-encoding Value The transfer encoding type in lowercase scanSpace: aScanner 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. scanSpecial: aScanner 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. scanToken: aScanner 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. Leading whitespace is ignored. Backslash escapes in quoted text are converted