QMailMessageHeaderField Class Reference
[QtMessagingModule, QtPimModule]

Detailed Description

The QMailMessageHeaderField class encapsulates the parsing of message header fields.

QMailMessageHeaderField provides simplified access to the various components of the header field, and allows the field content to be extracted in a standardized form.

The content of a header field may be formed of unstructured text, or it may have an internal structure. If a structured field is specified, QMailMessageHeaderField assumes that the contained header field is structured in a format equivalent to that used for the RFC 2045 'Content-Type' and RFC 2183 'Content-Disposition' header fields. If the field is unstructured, or conforms to a different structure, then the parameter() and parameters() functions will return empty results, and the setParameter() function will have no effect.

QMailMessageHeaderField contains static functions to assist in creating correct header field content, and presenting header field content. The encodeWord() and decodeWord() functions translate between plain text and the encoded-word specification defined in RFC 2045. The encodeParameter() and decodeParameter() functions translate between plain text and the encoded-parameter format defined in RFC 2231.

The removeWhitespace() function can be used to remove irrelevant whitespace characters from a string, and the removeComments() function can remove any comment sequences present, encododed according to the RFC 2822 specification.

Member Type Documentation

enum QMailMessageHeaderField::FieldType

This enum type is used to describe the formatting of field content.

Member Function Documentation

QMailMessageHeaderField::QMailMessageHeaderField ()

Creates an uninitialised message header field object.

QMailMessageHeaderField::QMailMessageHeaderField ( const QByteArray & text, FieldType fieldType = StructuredField )

Creates a message header field object from the data in text. If fieldType is QMailMessageHeaderField::StructuredField, then text will be parsed assuming a format equivalent to that used for the RFC 2045 'Content-Type' and RFC 2183 'Content-Disposition' header fields.

QMailMessageHeaderField::QMailMessageHeaderField ( const QByteArray & id, const QByteArray & text, FieldType fieldType = StructuredField )

Creates a message header field object with the field id id and the content data in text. If fieldType is QMailMessageHeaderField::StructuredField, then text will be parsed assuming a format equivalent to that used for the RFC 2045 'Content-Type' and RFC 2183 'Content-Disposition' header fields.

QByteArray QMailMessageHeaderField::content () const

Returns the content of the header field, without any associated parameters.

See also setContent().

QString QMailMessageHeaderField::decodeContent ( const QByteArray & input )   [static]

Returns the content of input, decoding any encountered RFC 2045 'encoded-word' format tokens to unicode.

QString QMailMessageHeaderField::decodeParameter ( const QByteArray & input )   [static]

Returns the content of input decoded from RFC 2231 'extended-parameter' format.

QString QMailMessageHeaderField::decodeWord ( const QByteArray & input )   [static]

Returns the content of input decoded from RFC 2045 'encoded-word' format.

QString QMailMessageHeaderField::decodedContent () const   [virtual]

Returns the content of the header field as unicode text. If the content of the field contains any encoded-word or encoded-parameter values, they will be decoded on output.

QByteArray QMailMessageHeaderField::encodeContent ( const QString & input, const QByteArray & charset = "" )   [static]

Returns the content of the string input encoded into a sequence of RFC 2045 'encoded-word' format tokens. The encoding used can be specified in charset, or can be deduced for each token read from input if charset is empty.

QByteArray QMailMessageHeaderField::encodeParameter ( const QString & input, const QByteArray & charset = "", const QByteArray & language = "" )   [static]

Returns the content of the string input encoded into RFC 2231 'extended-parameter' format. The encoding used can be specified in charset, or can be deduced from the content of input if charset is empty. If language is non-empty, it will be included in the encoded output; otherwise the language component will be extracted from charset, if it contains a trailing language specifier as defined in RFC 2231.

QByteArray QMailMessageHeaderField::encodeWord ( const QString & input, const QByteArray & charset = "" )   [static]

Returns the content of the string input encoded into a series of RFC 2045 'encoded-word' format tokens, each no longer than 75 characters. The encoding used can be specified in charset, or can be deduced from the content of input if charset is empty.

QByteArray QMailMessageHeaderField::id () const

Returns the ID of the header field.

See also setId().

bool QMailMessageHeaderField::isNull () const

Returns true if the header field has not been initialized.

bool QMailMessageHeaderField::isParameterEncoded ( const QByteArray & name ) const

Returns true if the parameter with name name exists and is marked as encoded according to RFC 2231; otherwise returns false. Name comparisons are case-insensitive.

QByteArray QMailMessageHeaderField::parameter ( const QByteArray & name ) const

Returns the value of the parameter with the name name. Name comparisons are case-insensitive.

See also setParameter().

QList<ParameterType> QMailMessageHeaderField::parameters () const

Returns the list of parameters from the header field. For each parameter, the member first contains the name text, and the member second contains the value text.

QByteArray QMailMessageHeaderField::removeComments ( const QByteArray & input )   [static]

Returns the content of input with any comment sections removed.

QByteArray QMailMessageHeaderField::removeWhitespace ( const QByteArray & input )   [static]

Returns the content of input with any whitespace characters removed. Whitespace inside double quotes is preserved.

void QMailMessageHeaderField::setContent ( const QByteArray & text )

Sets the content of the header field to text.

See also content().

void QMailMessageHeaderField::setId ( const QByteArray & id )

Sets the ID of the header field to id.

See also id().

void QMailMessageHeaderField::setParameter ( const QByteArray & name, const QByteArray & value )

Sets the parameter with the name name to have the value value, if present; otherwise a new parameter is appended with the supplied properties. If name ends with a single asterisk, the parameter will be flagged as encoded.

See also parameter() and setParameterEncoded().

void QMailMessageHeaderField::setParameterEncoded ( const QByteArray & name )

Sets any parameters with the name name to be marked as encoded. Name comparisons are case-insensitive.

See also isParameterEncoded().

QByteArray QMailMessageHeaderField::toString ( bool includeName = true, bool presentable = true ) const   [virtual]

Returns the entire header field text as a formatted string, with the name of the field included if includeName is true. If presentable is true, artifacts of RFC 2822 transmission format such as parameter folding will be removed. For example:

    QMailMessageHeaderField hdr;
    hdr.setId("Content-Type");
    hdr.setContent("text/plain");
    hdr.setParameter("charset", "us-ascii");

    QString s = hdr.toString();  // s: "Content-Type: text/plain; charset=us-ascii"