MimeTreeParser::ObjectTreeParser Class Reference

#include <objecttreeparser.h>

Public Member Functions
	ObjectTreeParser (const ObjectTreeParser *topLevelParser)
	ObjectTreeParser (Interface::ObjectTreeSource *source, NodeHelper *nodeHelper=nullptr)
bool	allowAsync () const
bool	hasPendingAsyncJobs () const
QString	htmlContent () const
NodeHelper *	nodeHelper () const
MessagePartPtr	parsedPart () const
void	parseObjectTree (KMime::Content *node, bool parseOnlySingleNode=false)
QString	plainTextContent () const
void	setAllowAsync (bool allow)

Detailed Description

Parses messages and generates HTML display code out of them.

Introduction

First, have a look at the documentation in Mainpage.dox and at the documentation of ViewerPrivate to understand the broader picture.

Just a note on the terminology: 'Node' refers to a MIME part here, which in KMime is a KMime::Content.

Basics

The ObjectTreeParser basically has two modes: Generating the HTML code for the Viewer, or only extracting the plainTextContent() for situations where only the message text is needed, for example when inline forwarding a message. The mode depends on the Interface::ObjectTreeSource passed to the constructor: If Interface::ObjectTreeSource::htmlWriter() is not 0, then the HTML code generation mode is used.

Basically, all the ObjectTreeParser does is going through the tree of MIME parts and operating on those nodes. Operating here means creating the HTML code for the node or extracting the textual content from it. This process is started with parseObjectTree(), where we loop over the subnodes of the current root node. For each of those subnodes, we try to find a BodyPartFormatter that can handle the type of the node. This can either be an internal function, such as processMultiPartAlternativeSubtype() or processTextHtmlSubtype(), or it can be an external plugin. More on external plugins later. When no matching formatter is found, defaultHandling() is called for that node.

Multipart Nodes

Those nodes that are of type multipart have subnodes. If one of those children needs to be processed normally, the processMultipartXXX() functions call stdChildHandling() for the node that should be handled normally. stdChildHandling() creates its own ObjectTreeParser, which is a clone of the current ObjectTreeParser, and processes the node. stdChildHandling() is not called for all children of the multipart node, for example processMultiPartAlternativeSubtype() only calls it on one of the children, as the other one doesn't need to be displayed. Similarly, processMultiPartSignedSubtype() doesn't call stdChildHandling() for the signature node, only for the signed node.

Processed and Unprocessed Nodes

When a BodyPartFormatter has finished processing a node, it is processed. Nodes are set to being not processed at the beginning of parseObjectTree(). The processed state of a node is saved in a list in NodeHelper, see NodeHelper::setNodeProcessed(), NodeHelper::nodeProcessed() and the other related helper functions.

It is the responsibility of the BodyPartFormatter to correctly call setNodeProcessed() and the related functions. This is important so that processing the same node twice can be prevented. The check that prevents duplicate processing is in parseObjectTree().

An example where duplicate processing would happen if we didn't check for it is in stdChildHandling(), which is for example called from processMultiPartAlternativeSubtype(). Let's say the setting is to prefer HTML over plain text. In this case, processMultiPartAlternativeSubtype() would call stdChildHandling() on the HTML node, which would create a new ObjectTreeParser and call parseObjectTree() on it. parseObjectTree() processes the node and all its siblings, and one of the siblings is the plain text node, which shouldn't be processed! Therefore processMultiPartAlternativeSubtype() sets the plain text node as been processed already.

Plain Text Output

Various nodes have plain text that should be displayed. This plain text is usually processed though writeBodyString() first. That method checks if the provided text is an inline PGP text and decrypts it if necessary. It also pushes the text through quotedHTML(), which does a number of things like coloring quoted lines or detecting links and creating real link tags for them.

Modifying the Message

The ObjectTreeParser does not only parse its message, in some circumstances it also modifies it before displaying. This is for example the case when displaying a decrypted message: The original message only contains a binary blob of crypto data, and processMultiPartEncryptedSubtype() decrypts that blob. After decryption, the current node is replaced with the decrypted node, which happens in insertAndParseNewChildNode().

Crypto Operations

For signature and decryption handling, there are functions which help with generating the HTML code for the signature header and footer. These are writeDeferredDecryptionBlock(), writeSigstatFooter() and writeSigstatHeader(). As the name writeDeferredDecryptionBlock() suggests, a setting can cause the message to not be decrypted unless the user clicks a link. Whether the message should be decrypted or not can be controlled by Interface::ObjectTreeSource::decryptMessage(). When the user clicks the decryption link, the URLHandler for 'kmail:' URLs sets that variable to true and triggers an update of the Viewer, which will cause parseObjectTree() to be called again.

Async Crypto Operations

The above case describes decryption the message in place. However, decryption and also verifying of the signature can take a long time, so synchronous decryption and verifying would cause the Viewer to block. Therefore it is possible to run these operations in async mode, see allowAsync(). In the first run of the async mode, all the ObjectTreeParser does is starting the decrypt or the verify job, and informing the user that the operation is in progress with writeDecryptionInProgressBlock() or with writeSigstatHeader(). Then, it creates and associates a BodyPartMemento with the current node, for example a VerifyDetachedBodyPartMemento. Each node can have multiple mementos associated with it, which are differeniated by name.

NodeHelper::setBodyPartMemento() and NodeHelper::bodyPartMemento() provide means to store and retrieve these mementos. A memento is basically a thin wrapper around the crypto job, it stores the job pointer, the job input data and the job result. Mementos can be used for any async situation, not just for crypto jobs, but I'll describe crypto jobs here.

So in the first run of decrypting or verifying a message, the BodyPartFormatter only starts the crypto job, creates the BodyPartMemento and writes the HTML code that tells the user that the operation is in progress. parseObjectTree() thus finishes without waiting for anything, and the message is displayed.

At some point, the crypto jobs then finish, which will cause slotResult() of the BodyPartMemento to be called. slotResult() then saves the result to some member variable and calls BodyPartMemento::notify(), which in the end will trigger an update of the Viewer. That update will, in ViewerPrivate::parseMsg(), create a new ObjectTreeParser and call parseObjectTree() on it. This is where the second run begins.

The functions that deal with decrypting of verifying, like processMultiPartSignedSubtype() or processMultiPartEncryptedSubtype() will look if they find a BodyPartMemento that is associated with the current node. Now it finds that memento, since it was created in the first run. It checks if the memento's job has finished, and if so, the result can be written out (either the decrypted data or the verified signature).

When dealing with encrypted nodes, new nodes are created with the decrypted data. It is important to note that the original MIME tree is never modified, and remains the same as the original one. The method createAndParseTempNode is called with the newly decrypted data, and it generates a new temporary node to store the decrypted data. When these nodes are created, it is important to keep track of them as otherwise some mementos that are added to the newly created temporary nodes will be constantly regenerated. As the regeneration triggers a viewer update when complete, it results in an infinite refresh loop. The function NodeHelper::linkAsPermanentDecrypted will create a link between the newly created node and the original parent. Conversely, the function NodeHelper::attachExtraContent will create a link in the other direction, from the parent node to the newly created temporary node.

When generating some mementos for nodes that may be temporary nodes (for example, contact photo mementos), the function NodeHelper::setBodyPartMementoForPermanentParent is used. This will save the given body part memento for the closest found permanent parent node, rather than the transient node itself. Then when checking for the existence of a certain memento in a node, NodeHelper::findPermanentParentBodyPartMemento will check to see if any parent of the given temporary node is a permanent (encrypted) node that has been used to generate the asked-for node.

To conclude: For async operations, parseObjectTree() is called twice: The first call starts the crypto operation and creates the BodyPartMemento, the second calls sees that the BodyPartMemento is there and can use its result for writing out the HTML.

PartMetaData and ProcessResult

For crypto operations, the class PartMetaData is used a lot, mainly to pass around info about the crypto state of a node. A PartMetaData can also be associated with a node by using NodeHelper::setPartMetaData(). The only user of that however is MessageAnalyzer::processPart() of the Nepomuk E-Mail Feeder, which also uses the ObjectTreeParser to analyze the message.

You'll notice that a ProcessResult is passed to each formatter. The formatter is supposed to modify the ProcessResult to tell the callers something about the state of the nodes that were processed. One example for its use is to tell the caller about the crypto state of the node.

BodyPartFormatter Plugins

As mentioned way earlier, BodyPartFormatter can either be plugins or be internal. bodypartformatter.cpp contains some trickery so that the processXXX() methods of the ObjectTreeParser are called from a BodyPartFormatter associated with them, see the CREATE_BODY_PART_FORMATTER macro.

The BodyPartFormatter code is work in progress, it was supposed to be refactored, but that has not yet happened at the time of writing. Therefore the code can seem a bit chaotic.

External plugins are loaded with loadPlugins() in bodypartformatterfactory.cpp. External plugins can only use the classes in the interfaces/ directory, they include BodyPart, BodyPartMemento, BodyPartFormatterPlugin, BodyPartFormatter, BodyPartURLHandler and URLHandler. Therefore external plugins have powerful capabilities, which are needed for example in the iCal formatter or in the vCard formatter.

Special HTML tags

As also mentioned in the documentation of ViewerPrivate, the ObjectTreeParser writes out special links that are only understood by the viewer, for example 'kmail:' URLs or 'attachment:' URLs. Also, some special HTML tags are created, which the Viewer later uses for post-processing. For example a div with the id 'attachmentInjectionPoint', or a div with the id 'attachmentDiv', which is used to mark an attachment in the body with a yellow border when the user clicks the attachment in the header. Finally, parseObjectTree() creates an anchor with the id 'att%1', which is used in the Viewer to scroll to the attachment.

Definition at line 245 of file objecttreeparser.h.

Constructor & Destructor Documentation

ObjectTreeParser() [1/2]

ObjectTreeParser::ObjectTreeParser ( Interface::ObjectTreeSource * source, MimeTreeParser::NodeHelper * nodeHelper = nullptr )

explicit

Definition at line 43 of file objecttreeparser.cpp.

ObjectTreeParser() [2/2]

ObjectTreeParser::ObjectTreeParser ( const ObjectTreeParser * topLevelParser )

explicit

Definition at line 34 of file objecttreeparser.cpp.

~ObjectTreeParser()

ObjectTreeParser::~ObjectTreeParser ( )

virtual

Definition at line 74 of file objecttreeparser.cpp.

Member Function Documentation

allowAsync()

bool ObjectTreeParser::allowAsync ( ) const

nodiscard

Definition at line 88 of file objecttreeparser.cpp.

hasPendingAsyncJobs()

bool ObjectTreeParser::hasPendingAsyncJobs ( ) const

nodiscard

Definition at line 93 of file objecttreeparser.cpp.

htmlContent()

QString ObjectTreeParser::htmlContent ( ) const

nodiscard

Similar to plainTextContent(), but returns the HTML source of the first text/html MIME part.

Not to be confused with the HTML code that the message viewer widget displays, that HTML is written out by htmlWriter() and a totally different pair of shoes.

Definition at line 103 of file objecttreeparser.cpp.

nodeHelper()

MimeTreeParser::NodeHelper * ObjectTreeParser::nodeHelper ( ) const

nodiscard

Definition at line 285 of file objecttreeparser.cpp.

parsedPart()

MessagePartPtr ObjectTreeParser::parsedPart ( ) const

nodiscard

Definition at line 130 of file objecttreeparser.cpp.

parseObjectTree()

void ObjectTreeParser::parseObjectTree	(	KMime::Content *	node,
		bool	parseOnlySingleNode = false )

Parse beginning at a given node and recursively parsing the children of that node and it's next sibling.

Definition at line 110 of file objecttreeparser.cpp.

plainTextContent()

QString ObjectTreeParser::plainTextContent ( ) const

nodiscard

The text of the message, ie.

what would appear in the composer's text editor if this was edited or replied to. This is usually the content of the first text/plain MIME part.

Definition at line 98 of file objecttreeparser.cpp.

setAllowAsync()

void ObjectTreeParser::setAllowAsync

(

bool

allow

)

Definition at line 82 of file objecttreeparser.cpp.

---

The documentation for this class was generated from the following files:

• objecttreeparser.h
• objecttreeparser.cpp