KMime::Content Class

Member Function Documentation

[explicit] Content::Content(KMime::Content *parent = nullptr)

Creates an empty Content object with a specified parent. parent the parent Content object

See also setContent().

[since 6.0 (took a raw pointer until 26.04)] void Content::appendContent(std::unique_ptr<KMime::Content> &&content)

Appends a new sub-Content. If the sub-Content is already part of another Content object, it is removed from there and its parent is updated.

content The new sub-Content.

This function was introduced in 6.0 (took a raw pointer until 26.04).

See also prependContent() and takeContent().

[since 4.4 (took a raw pointer before 26.04)] void Content::appendHeader(std::unique_ptr<KMime::Headers::Base> &&h)

Appends the specified header to the headers of this Content.

h The header to append.

This function was introduced in 4.4 (took a raw pointer before 26.04).

[virtual] void Content::assemble()

Generates the MIME content.

This means the string representation of this Content is updated from the broken-down object representation. Call this if you have made changes to the content, and want encodedContent() to reflect those changes.

Note assemble() has no effect if the Content isFrozen(). You may want to freeze, for instance, signed sub-Contents, to make sure they are kept unmodified.

Note If this content is an encapsulated message, i.e. bodyIsMessage() returns true, then calling assemble() will also assemble the message returned by bodyAsMessage().

QList<KMime::Content *> Content::attachments()

Returns all attachments below this node, recursively.

This does not include crypto parts, nodes of alternative or related multipart nodes, or the primary body part (see textContent()).

See also KMime::isAttachment() and KMime::hasAttachment().

QByteArray Content::body() const

Returns the Content body raw data.

Note that this will be empty for multipart contents or for encapsulated messages, after parse() has been called.

See also setBody().

std::shared_ptr<KMime::Message> Content::bodyAsMessage()

If this content is an encapsulated message, in which case bodyIsMessage() will return true, the message represented by the body of this content will be returned.

The returned message is already fully parsed. Calling this method is the aquivalent of calling contents().first() and casting the result to a KMime::Message*. bodyAsMessage() has the advantage that it will return a shared pointer that will not be destroyed when the container message is destroyed or re-parsed.

The message that is returned here is created when calling parse(), so make sure to call parse() first. Since each parse() creates a new message object, a different message object will be returned each time you call parse().

If you make changes to the returned message, you need to call assemble() on this content or on the message if you want that encodedContent() reflects these changes. This also means that calling assemble() on this content will assemble the returned message.

bool Content::bodyIsMessage() const

Returns true if this content is an encapsulated message, i.e. if it has the mimetype message/rfc822.

void Content::changeEncoding(KMime::Headers::contentEncoding e)

Changes the encoding of this Content to e. If the Content is binary, this actually re-encodes the data to use the new encoding.

e The new encoding to use.

void Content::clear()

Clears the content, deleting all headers and sub-Contents.

void Content::clearContents()

Removes all sub-Contents from this content.

sub-Contents will be deleted.

Calling clearContents() does NOT make this Content single-part.

[virtual, since 26.04] std::unique_ptr<KMime::Content> Content::clone() const

Create a copy of this content object.

This is recursive, ie. all child content objects are also cloned. Prefer this over serializing and deserializing conetent as this is is more efficient due to making use of copy-on-write.

This function was introduced in 26.04.

KMime::Content *Content::content(const KMime::ContentIndex &index) const

Returns the Content specified by the given index.

If the index does not point to a Content, nullptr is returned.

If the index is invalid (empty), this Content is returned.

index The Content index.

See also setContent().

[since 24.08] const KMime::Headers::ContentDescription *Content::contentDescription() const

Returns the Content-Description header.

Can be nullptr if the header doesn't exist.

This function was introduced in 24.08.

KMime::Headers::ContentDescription *Content::contentDescription(KMime::CreatePolicy create = Create)

Returns the Content-Description header.

create Whether to create the header if it doesn't exist yet.

[since 24.08] const KMime::Headers::ContentDisposition *Content::contentDisposition() const

Returns the Content-Disposition header.

Can be nullptr if the header doesn't exist.

This function was introduced in 24.08.

KMime::Headers::ContentDisposition *Content::contentDisposition(KMime::CreatePolicy create = Create)

Returns the Content-Disposition header.

create Whether to create the header if it doesn't exist yet.

[since 24.08] const KMime::Headers::ContentID *Content::contentID() const

Returns the Content-ID header.

Can be nullptr if the header doesn't exist.

This function was introduced in 24.08.

KMime::Headers::ContentID *Content::contentID(KMime::CreatePolicy create = Create)

Returns the Content-ID header. create Whether to create the header if it doesn't exist yet.

[since 24.08] const KMime::Headers::ContentLocation *Content::contentLocation() const

Returns the Content-Location header.

Can be nullptr if the header doesn't exist.

This function was introduced in 24.08.

KMime::Headers::ContentLocation *Content::contentLocation(KMime::CreatePolicy create = Create)

Returns the Content-Location header.

create Whether to create the header if it doesn't exist yet.

[since 24.08] const KMime::Headers::ContentTransferEncoding *Content::contentTransferEncoding() const

Returns the Content-Transfer-Encoding header.

Can be nullptr if the header doesn't exist.

This function was introduced in 24.08.

KMime::Headers::ContentTransferEncoding *Content::contentTransferEncoding(KMime::CreatePolicy create = Create)

Returns the Content-Transfer-Encoding header.

create Whether to create the header if it doesn't exist yet.

[since 24.08] const KMime::Headers::ContentType *Content::contentType() const

Returns the Content-Type header.

Can be nullptr if the header doesn't exist.

This function was introduced in 24.08.

KMime::Headers::ContentType *Content::contentType(KMime::CreatePolicy create = Create)

Returns the Content-Type header.

create Whether to create the header if it doesn't exist yet.

QList<KMime::Content *> Content::contents()

For multipart contents, this will return a list of all multipart child contents.

For contents that are of mimetype message/rfc822, this will return a list with one entry, and that entry is the encapsulated message, as it would be returned by bodyAsMessage().

[since 25.12 (previously decodedContent())] QByteArray Content::decodedBody() const

Returns the decoded Content body.

Note that this will be empty for multipart contents or for encapsulated messages, after parse() has been called.

This function was introduced in 25.12 (previously decodedContent()).

[since 24.12] QString Content::decodedText(KMime::Content::DecodedTextTrimOption trimOption = NoTrim) const

Returns the decoded text. Additional to decodedBody(), this also applies charset decoding. If this is not a text Content, decodedText() returns an empty QString.

trimOption Control how to trim trailing white spaces. The last trailing new line of the decoded text is always removed.

This function was introduced in 24.12.

QByteArray Content::encodedBody() const

Like encodedContent(), with the difference that only the body will be returned, i.e. the headers are excluded.

See also setEncodedBody().

QByteArray Content::encodedContent(KMime::NewlineType newline = NewlineType::LF) const

Returns a QByteArray containing the encoded Content, including the Content header and all sub-Contents.

If you make changes to the broken-down representation of the message, be sure to first call assemble() before calling encodedContent(), otherwise the result will not be up-to-date.

If this content is an encapsulated message, i.e. bodyIsMessage() returns true, then encodedContent() will use the message returned by bodyAsMessage() as the body of the result, calling encodedContent() on the message.

newline whether to use CRLF for linefeeds, or LF (default is LF).

QByteArray Content::epilogue() const

Returns the MIME epilogue.

Returns a QByteArray containing the MIME epilogue.

See also setEpilogue().

void Content::fromUnicodeString(const QString &s)

Sets the Content body to the given string using charset of the content type.

If the charset can not be found, the system charset is taken and the content type header is changed to that charset. The charset of the content type header should be set to a charset that can encode the given string before calling this method.

This method does not set the content transfer encoding automatically, it needs to be set to a suitable value that can encode the given string before calling this method.

This method only makes sense for single-part contents, do not try to pass a multipart body or an encapsulated message here, that wouldn't work.

s Unicode-encoded string.

bool Content::hasContent() const

Returns true if this Content object is not empty.

bool Content::hasHeader(QByteArrayView type) const

Returns true if this Content has a header of type type.

QByteArray Content::head() const

Returns the Content header raw data.

See also setHead().

[since 24.08] template <typename T> const std::remove_cv_t<T> *Content::header() const

Returns the first header of type T.

Can be nullptr if such a header doesn't exist.

This function was introduced in 24.08.

See also setHeader().

[since 4.4 (took a bool before 26.04)] template <typename T> T *Content::header(KMime::CreatePolicy create = Create)

Returns the first header of type T, if it exists.

If the header does not exist and create is Create, creates an empty header and returns it. Otherwise returns nullptr.

Note that the returned header may be empty.

create Whether to create the header if it does not exist.

This function was introduced in 4.4 (took a bool before 26.04).

KMime::Headers::Base *Content::headerByType(QByteArrayView type) const

Returns the first header of type type, if it exists.

Otherwise returns nullptr. Note that the returned header may be empty.

type the header type to find

QList<KMime::Headers::Base *> Content::headers()

Returns all headers.

QList<KMime::Headers::Base *> Content::headersByType(QByteArrayView type) const

Returns all type headers in the Content.

Take care that this result is not cached, so could be slow.

type the header type to find

KMime::ContentIndex Content::index() const

Returns the index of this Content based on the topLevel() object.

KMime::ContentIndex Content::indexForContent(const KMime::Content *content) const

Returns the ContentIndex for the given Content, or an invalid index if the Content is not found within the hierarchy.

content the Content object to search.

bool Content::isFrozen() const

Returns whether this Content is frozen.

A frozen content is immutable, i.e. calling assemble() will never modify its head or body, and encodedContent() will return the same data before and after parsing.

See also setFrozen().

bool Content::isTopLevel() const

Returns true if this is the top-level node in the MIME tree.

The top-level node is always a Message or NewsArticle.

However, a node can be a Message without being a top-level node when it is an encapsulated message.

KMime::Content *Content::parent()

Returns the parent content object, or 0 if the content doesn't have a parent.

See also setParent().

void Content::parse()

Parses the Content.

This means the broken-down object representation of the Content is updated from the string representation of the Content.

Call this if you want to access or change headers, sub-Contents or the encapsulated message.

Note Calling parse() twice will not work for multipart contents or for contents of which the body is an encapsulated message. The reason is that the first parse() will delete the body, so there is no body to work on for the second call of parse().

QByteArray Content::preamble() const

Returns the MIME preamble.

See also setPreamble().

[since 6.0 (took a raw pointer until 26.04)] void Content::prependContent(std::unique_ptr<KMime::Content> &&content)

Prepends a new sub-Content. If the sub-Content is already part of another Content object, it is removed from there and its parent is updated.

content The new sub-Content.

This function was introduced in 6.0 (took a raw pointer until 26.04).

See also appendContent() and takeContent().

template <typename T> bool Content::removeHeader()

Searches for the first header of type T, and deletes it, removing it from this Content.

T The type of the header to look for.

Returns true if a header was found and removed.

bool Content::removeHeader(QByteArrayView type)

Searches for the first header of type type, and deletes it, removing it from this Content.

type The type of the header to look for.

Returns true if a header was found and removed.

void Content::setBody(const QByteArray &body)

Sets the Content decoded body raw data.

This method operates on the string representation of the Content. Call parse() if you want to access individual sub-Contents or the encapsulated message.

body is a QByteArray containing the body data.

Note body is assumed to be decoded as far as the content transfer encoding is concerned.

See also body() and setEncodedBody().

void Content::setContent(const QByteArray &s)

Sets the Content to the given raw data, containing the Content head and body separated by two linefeeds.

This method operates on the string representation of the Content. Call parse() if you want to access individual headers, sub-Contents or the encapsulated message.

s is a QByteArray containing the raw Content data.

See also content().

[since 24.08] void Content::setEncodedBody(const QByteArray &body)

Sets the Content body raw data encoded according to the content transfer encoding.

This method operates on the string representation of the Content. Call parse() if you want to access individual sub-Contents or the encapsulated message.

body is a QByteArray containing the body data.

Note body is assumed to be encoded as far as the content transfer encoding is concerned.

This function was introduced in 24.08.

See also encodedBody() and setBody().

void Content::setEpilogue(const QByteArray &epilogue)

Sets the MIME epilogue.

epilogue a QByteArray containing what will be used as the MIME epilogue.

See also epilogue().

void Content::setFrozen(bool frozen = true)

Freezes this Content if frozen is true; otherwise unfreezes it.

frozen freeze content if true, otherwise unfreeze

See also isFrozen().

void Content::setHead(const QByteArray &head)

Sets the Content header raw data.

This method operates on the string representation of the Content. Call parse() if you want to access individual headers.

head is a QByteArray containing the header data.

See also head().

[since 4.4 (took a raw pointer before 26.04)] void Content::setHeader(std::unique_ptr<KMime::Headers::Base> &&h)

Sets the specified header to this Content.

Any previous header of the same type is removed.

If you need multiple headers of the same type, use appendHeader() or prependHeader().

h The header to set.

This function was introduced in 4.4 (took a raw pointer before 26.04).

See also header(), appendHeader(), and removeHeader().

void Content::setParent(KMime::Content *parent)

Sets a new parent to the Content and add to its contents list.

If it already had a parent, it is removed from the old parents contents list.

parent the new parent

See also parent().

void Content::setPreamble(const QByteArray &preamble)

Sets the MIME preamble.

preamble a QByteArray containing what will be used as the MIME preamble.

See also preamble().

qsizetype Content::size() const

Returns the size of the Content body after encoding.

(If the encoding is quoted-printable, this is only an approximate size.)

This will return 0 for multipart contents or for encapsulated messages.

qsizetype Content::storageSize() const

Returns the size of this Content and all sub-Contents.

[since 6.0 (returned a raw pointer until 26.04)] std::unique_ptr<KMime::Content> Content::takeContent(KMime::Content *content)

Removes the given sub-Content and, if that actually was a sub-content returns that.

content The Content to remove. It is not deleted, ownership goes back to the caller.

This function was introduced in 6.0 (returned a raw pointer until 26.04).

See also appendContent(), prependContent(), and clearContents().

KMime::Content *Content::textContent()

Returns the first Content with mimetype text/.

[since 24.08] const KMime::Content *Content::textContent() const

Returns the first Content with MIME type text/.

Const overload of the above, the returned Content cannot be modified.

This function was introduced in 24.08.

KMime::Content *Content::topLevel()

Returns the toplevel content object, 0 if there is no such object.