• Skip to content
  • Skip to link menu
KDE 4.4 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • Sitemap
  • Contact Us
 

KMIME Library

KMime::Content

KMime::Content Class Reference

A class that encapsulates MIME encoded Content. More...

#include <kmime_content.h>

Inheritance diagram for KMime::Content:
Inheritance graph
[legend]

List of all members.

Public Types

typedef QList< KMime::Content * > List

Public Member Functions

 Content (const QByteArray &head, const QByteArray &body, Content *parent)
 Content (const QByteArray &head, const QByteArray &body)
 Content (Content *parent)
 Content ()
virtual ~Content ()
void addContent (Content *content, bool prepend=false)
void appendHeader (Headers::Base *h)
virtual void assemble ()
List attachments (bool incAlternatives=false)
QByteArray body () const
void changeEncoding (Headers::contentEncoding e)
virtual void clear ()
void clearContents (bool del=true)
Content * content (const ContentIndex &index) const
Headers::ContentDescription * contentDescription (bool create=true)
Headers::ContentDisposition * contentDisposition (bool create=true)
Headers::ContentID * contentID (bool create=true)
Headers::ContentLocation * contentLocation (bool create=true)
List contents () const
Headers::ContentTransferEncoding * contentTransferEncoding (bool create=true)
Headers::ContentType * contentType (bool create=true)
QByteArray decodedContent ()
QString decodedText (bool trimText=false, bool removeTrailingNewlines=false)
QByteArray defaultCharset () const
QByteArray encodedContent (bool useCrLf=false)
bool forceDefaultCharset () const
void fromUnicodeString (const QString &s)
virtual Headers::Base * getHeaderByType (const char *type)
Headers::Generic * getNextHeader (QByteArray &head)
bool hasContent () const
bool hasHeader (const char *type)
QByteArray head () const
template<typename T >
T * header (bool create=false)
virtual Headers::Base * headerByType (const char *type)
virtual QList< Headers::Base * > headersByType (const char *type)
ContentIndex index () const
ContentIndex indexForContent (Content *content) const
bool isFrozen () const
virtual bool isTopLevel () const
int lineCount () const
Headers::Generic * nextHeader (QByteArray &head)
Content * parent () const
virtual void parse ()
void prependHeader (Headers::Base *h)
void removeContent (Content *content, bool del=false)
virtual bool removeHeader (const char *type)
void setBody (const QByteArray &body)
void setContent (const QByteArray &s)
void setContent (const QList< QByteArray > &l)
void setDefaultCharset (const QByteArray &cs)
virtual void setForceDefaultCharset (bool b)
void setFrozen (bool frozen=true)
void setHead (const QByteArray &head)
virtual void setHeader (Headers::Base *h)
void setParent (Content *parent)
int size ()
int storageSize () const
Content * textContent ()
Content * topLevel () const
void toStream (QTextStream &ts, bool scrambleFromLines=false)

Protected Member Functions

virtual QByteArray assembleHeaders ()
bool decodeText ()
template<class T >
T * headerInstance (T *ptr, bool create)
QByteArray rawHeader (const char *name) const
QList< QByteArray > rawHeaders (const char *name) const

Protected Attributes

Headers::Base::List h_eaders

Detailed Description

A class that encapsulates MIME encoded Content.

A Content object holds two representations of a content:

  • the string representation: This is the content encoded as a string ready for transport. Accessible through the encodedContent() method.
  • the broken-down representation: This is the tree of objects (headers, sub-Contents) that this Content is made of. Accessible through methods like header() and contents(). The parse() function updates the broken-down representation of the Content from its string representation. Calling it is necessary to access the headers or sub-Contents of this Content. The assemble() function updates the string representation of the Content from its broken-down representation. Calling it is necessary for encodedContent() to reflect any changes made to the Content.

Definition at line 87 of file kmime_content.h.


Member Typedef Documentation

typedef QList<KMime::Content*> KMime::Content::List

Describes a list of Content objects.

Reimplemented in KMime::Message.

Definition at line 94 of file kmime_content.h.


Constructor & Destructor Documentation

KMime::Content::Content (  ) 

Creates an empty Content object.

Definition at line 58 of file kmime_content.cpp.

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

Creates an empty Content object with a specified parent.

Parameters:
parent the parent Content object
Since:
4.3

Definition at line 63 of file kmime_content.cpp.

KMime::Content::Content ( const QByteArray &  head,
const QByteArray &  body 
)

Creates a Content object containing the given raw data.

Parameters:
head is a QByteArray containing the header data.
body is a QByteArray containing the body data.

Definition at line 69 of file kmime_content.cpp.

KMime::Content::Content ( const QByteArray &  head,
const QByteArray &  body,
Content *  parent 
)

Creates a Content object containing the given raw data.

Parameters:
head is a QByteArray containing the header data.
body is a QByteArray containing the body data.
parent the parent Content object
Since:
4.3

Definition at line 76 of file kmime_content.cpp.

KMime::Content::~Content (  )  [virtual]

Destroys this Content object.

Definition at line 89 of file kmime_content.cpp.


Member Function Documentation

void KMime::Content::addContent ( Content *  content,
bool  prepend = false 
)

Adds 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. If the current Content object is single-part, it is converted to multipart/mixed first.

Warning:
If the single-part to multipart conversion happens, all pointers you may have into this object (such as headers) will become invalid!
Parameters:
content The new sub-Content.
prepend If true, prepend to the Content list; otherwise append. to the Content list.
See also:
removeContent().

Definition at line 477 of file kmime_content.cpp.

void KMime::Content::appendHeader ( Headers::Base *  h  ) 

Appends the specified header to the headers of this Content.

Parameters:
h The header to append.
Since:
4.4

Definition at line 660 of file kmime_content.cpp.

void KMime::Content::assemble (  )  [virtual]

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.
Warning:
assemble() may change the order of the headers, and other details such as where folding occurs. This may break things like signature verification, so you should *ONLY* call assemble() when you have actually modified the content.

Definition at line 231 of file kmime_content.cpp.

QByteArray KMime::Content::assembleHeaders (  )  [protected, virtual]

Reimplement this method if you need to assemble additional headers in a derived class.

Don't forget to call the implementation of the base class.

Returns:
The raw, assembled headers.

Reimplemented in KMime::Message.

Definition at line 244 of file kmime_content.cpp.

Content::List KMime::Content::attachments ( bool  incAlternatives = false  ) 

Returns a list of attachments.

Parameters:
incAlternatives If true, include multipart/alternative parts.

Definition at line 447 of file kmime_content.cpp.

QByteArray KMime::Content::body (  )  const

Returns the Content body raw data.

See also:
setBody().

Definition at line 164 of file kmime_content.cpp.

void KMime::Content::changeEncoding ( 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.

Parameters:
e The new encoding to use.

Definition at line 564 of file kmime_content.cpp.

void KMime::Content::clear (  )  [virtual]

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

Reimplemented in KMime::Message.

Definition at line 256 of file kmime_content.cpp.

void KMime::Content::clearContents ( bool  del = true  ) 

Removes all sub-Contents from this content.

Deletes them if del is true. This is different from calling removeContent() on each sub-Content, because removeContent() will convert this to a single-part Content if only one sub-Content is left. Calling clearContents() does NOT make this Content single-part.

Parameters:
del Whether to delete the sub-Contents.
See also:
removeContent()
Since:
4.4

Definition at line 266 of file kmime_content.cpp.

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

Returns the Content specified by the given index.

If the index does not point to a Content, 0 is returned. If the index is invalid (empty), this Content is returned.

Parameters:
index The Content index.

Definition at line 819 of file kmime_content.cpp.

Headers::ContentDescription* KMime::Content::contentDescription ( bool  create = true  ) 

Returns the Content-Description header.

Parameters:
create If true, create the header if it doesn't exist yet.
Headers::ContentDisposition* KMime::Content::contentDisposition ( bool  create = true  ) 

Returns the Content-Disposition header.

Parameters:
create If true, create the header if it doesn't exist yet.
Headers::ContentID* KMime::Content::contentID ( bool  create = true  ) 

Returns the Content-ID header.

Parameters:
create if true, create the header if it does not exist yet.
Since:
4.4
Headers::ContentLocation* KMime::Content::contentLocation ( bool  create = true  ) 

Returns the Content-Location header.

Parameters:
create If true, create the header if it doesn't exist yet.
Since:
4.2
Content::List KMime::Content::contents (  )  const

Returns a list of sub-Contents.

Definition at line 472 of file kmime_content.cpp.

Headers::ContentTransferEncoding* KMime::Content::contentTransferEncoding ( bool  create = true  ) 

Returns the Content-Transfer-Encoding header.

Parameters:
create If true, create the header if it doesn't exist yet.
Headers::ContentType* KMime::Content::contentType ( bool  create = true  ) 

Returns the Content-Type header.

Parameters:
create If true, create the header if it doesn't exist yet.
QByteArray KMime::Content::decodedContent (  ) 

Returns the decoded Content body.

Definition at line 331 of file kmime_content.cpp.

QString KMime::Content::decodedText ( bool  trimText = false,
bool  removeTrailingNewlines = false 
)

Returns the decoded text.

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

Parameters:
trimText If true, then the decoded text will have all trailing whitespace removed.
removeTrailingNewlines If true, then the decoded text will have all consecutive trailing newlines removed.

The last trailing new line of the decoded text is always removed.

Definition at line 378 of file kmime_content.cpp.

bool KMime::Content::decodeText (  )  [protected]

Returns whether this object holds text content.

Definition at line 747 of file kmime_content.cpp.

QByteArray KMime::Content::defaultCharset (  )  const

Returns the charset that is used for all headers and the body if the charset is not declared explictly.

See also:
setDefaultCharset()

Definition at line 783 of file kmime_content.cpp.

QByteArray KMime::Content::encodedContent ( bool  useCrLf = false  ) 

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

Parameters:
useCrLf If true, use CRLF instead of LF for linefeeds.

Definition at line 275 of file kmime_content.cpp.

bool KMime::Content::forceDefaultCharset (  )  const

Use the default charset even if a different charset is declared in the article.

See also:
setForceDefaultCharset().

Definition at line 801 of file kmime_content.cpp.

void KMime::Content::fromUnicodeString ( const QString &  s  ) 

Sets the Content body to the given string using the current charset.

Parameters:
s Unicode-encoded string.

Definition at line 414 of file kmime_content.cpp.

Headers::Base * KMime::Content::getHeaderByType ( const char *  type  )  [virtual]

Tries to find a type header in the Content and returns it.

Deprecated:
Use headerByType( const char * )

Reimplemented in KMime::Message.

Definition at line 620 of file kmime_content.cpp.

Headers::Generic * KMime::Content::getNextHeader ( QByteArray &  head  ) 

Extracts and removes the next header from head.

The caller is responsible for deleting the returned header.

Deprecated:
Use nextHeader( QByteArray )
Parameters:
head is a QByteArray containing the header data.

Definition at line 603 of file kmime_content.cpp.

bool KMime::Content::hasContent (  )  const

Returns true if this Content object is not empty.

Definition at line 97 of file kmime_content.cpp.

bool KMime::Content::hasHeader ( const char *  type  ) 
Returns:
true if this Content has a header of type type.
Parameters:
type The type of the header to look for.

Definition at line 685 of file kmime_content.cpp.

QByteArray KMime::Content::head (  )  const

Returns the Content header raw data.

See also:
setHead().

Definition at line 152 of file kmime_content.cpp.

template<typename T >
T * KMime::Content::header ( bool  create = false  )  [inline]

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

If the header does not exist and create is true, creates an empty header and returns it. Otherwise returns 0. Note that the returned header may be empty.

Parameters:
create Whether to create the header if it does not exist.
Since:
4.4.

Definition at line 673 of file kmime_content.h.

Headers::Base * KMime::Content::headerByType ( const char *  type  )  [virtual]

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

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

Since:
4.2

Reimplemented in KMime::Message.

Definition at line 625 of file kmime_content.cpp.

template<class T >
T * KMime::Content::headerInstance ( T *  ptr,
bool  create 
) [inline, protected]

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

Deprecated:
Use header() instead.

Definition at line 668 of file kmime_content.h.

Headers::Base::List KMime::Content::headersByType ( const char *  type  )  [virtual]

Returns all type headers in the Content.

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

Since:
4.2

Definition at line 638 of file kmime_content.cpp.

ContentIndex KMime::Content::index (  )  const

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

Since:
4.3

Definition at line 889 of file kmime_content.cpp.

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

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

Parameters:
content the Content object to search.

Definition at line 833 of file kmime_content.cpp.

bool KMime::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.

Since:
4.4.
See also:
setFrozen().

Definition at line 221 of file kmime_content.cpp.

bool KMime::Content::isTopLevel (  )  const [virtual]

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

if this is actually a Message or NewsArticle.

Reimplemented in KMime::Message.

Definition at line 853 of file kmime_content.cpp.

int KMime::Content::lineCount (  )  const

Line count of this Content and all sub-Contents.

Definition at line 721 of file kmime_content.cpp.

Headers::Generic * KMime::Content::nextHeader ( QByteArray &  head  ) 

Extracts and removes the next header from head.

The caller is responsible for deleting the returned header.

Since:
4.2
Deprecated:
Use KMime::extractFirstHeader().
Parameters:
head is a QByteArray containing the header data.

Definition at line 608 of file kmime_content.cpp.

Content * KMime::Content::parent (  )  const

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

Since:
4.3

Definition at line 872 of file kmime_content.cpp.

void KMime::Content::parse (  )  [virtual]

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 or sub-Contents.

Reimplemented in KMime::Message.

Definition at line 174 of file kmime_content.cpp.

void KMime::Content::prependHeader ( Headers::Base *  h  ) 

Prepends the specified header to the headers of this Content.

Parameters:
h The header to prepend.
Since:
4.4

Definition at line 666 of file kmime_content.cpp.

QByteArray KMime::Content::rawHeader ( const char *  name  )  const [protected]

Returns the raw string representing the header of type name.

Deprecated:
Use KMime::extractHeader() directly instead.

Definition at line 737 of file kmime_content.cpp.

QList< QByteArray > KMime::Content::rawHeaders ( const char *  name  )  const [protected]

Returns a list of raw strings representing all header of type name.

Deprecated:
Use KMime::extractHeaders() directly instead.

Definition at line 742 of file kmime_content.cpp.

void KMime::Content::removeContent ( Content *  content,
bool  del = false 
)

Removes the given sub-Content.

If only one sub-Content is left, the current Content object is converted into a single-part Content.

Warning:
If the multipart to single-part conversion happens, the head and body of the single remaining sub-Content are copied over, and the sub-Content is deleted. All pointers to it or into it (such as headers) will become invalid!
Parameters:
content The Content to remove.
del If true, delete the removed Content object. Otherwise set its parent to 0.
See also:
addContent().
clearContents().

Definition at line 532 of file kmime_content.cpp.

bool KMime::Content::removeHeader ( const char *  type  )  [virtual]

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

Parameters:
type The type of the header to look for.
Returns:
true if a header was found and removed.

Reimplemented in KMime::Message.

Definition at line 672 of file kmime_content.cpp.

void KMime::Content::setBody ( const QByteArray &  body  ) 

Sets the Content body raw data.

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

Parameters:
body is a QByteArray containing the body data.
See also:
body().

Definition at line 169 of file kmime_content.cpp.

void KMime::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 or sub-Contents.

Parameters:
s is a QByteArray containing the raw Content data.

Definition at line 131 of file kmime_content.cpp.

void KMime::Content::setContent ( const QList< QByteArray > &  l  ) 

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 or sub-Contents.

Parameters:
l is a line-splitted list of the raw Content data.

Definition at line 102 of file kmime_content.cpp.

void KMime::Content::setDefaultCharset ( const QByteArray &  cs  ) 

Sets the default charset.

Parameters:
cs is a QByteArray containing the new default charset.
See also:
defaultCharset().

Definition at line 788 of file kmime_content.cpp.

void KMime::Content::setForceDefaultCharset ( bool  b  )  [virtual]

Enables/disables the force mode, housekeeping.

works correctly only when the article is completely empty or completely loaded.

Parameters:
b If true, force the default charset to be used.
See also:
forceDefaultCharset().

Definition at line 806 of file kmime_content.cpp.

void KMime::Content::setFrozen ( bool  frozen = true  ) 

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

Since:
4.4
See also:
isFrozen().

Definition at line 226 of file kmime_content.cpp.

void KMime::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.

Parameters:
head is a QByteArray containing the header data.
See also:
head().

Definition at line 157 of file kmime_content.cpp.

void KMime::Content::setHeader ( Headers::Base *  h  )  [virtual]

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().

Parameters:
h The header to set.
See also:
appendHeader()
removeHeader()
Since:
4.4

Reimplemented in KMime::Message.

Definition at line 653 of file kmime_content.cpp.

void KMime::Content::setParent ( 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.

Parameters:
parent the new parent
Since:
4.3

Definition at line 858 of file kmime_content.cpp.

int KMime::Content::size (  ) 

Returns the size of the Content body after encoding.

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

Definition at line 690 of file kmime_content.cpp.

int KMime::Content::storageSize (  )  const

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

Definition at line 705 of file kmime_content.cpp.

Content * KMime::Content::textContent (  ) 

Returns the first Content with mimetype text/.

Definition at line 430 of file kmime_content.cpp.

Content * KMime::Content::topLevel (  )  const

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

Since:
4.3

Definition at line 877 of file kmime_content.cpp.

void KMime::Content::toStream ( QTextStream &  ts,
bool  scrambleFromLines = false 
)

Saves the encoded Content to the given textstream.

Parameters:
ts is the stream where the Content should be written to.
scrambleFromLines,: If true, replace "\nFrom " with "\n>From " in the stream. This is needed to avoid problem with mbox-files

Definition at line 590 of file kmime_content.cpp.


Member Data Documentation

Headers::Base::List KMime::Content::h_eaders [protected]

The list of headers in this Content.

Do not use this directly.

Definition at line 653 of file kmime_content.h.


The documentation for this class was generated from the following files:
  • kmime_content.h
  • kmime_content.cpp

KMIME Library

Skip menu "KMIME Library"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kblog
  • kcal
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal