Messagelib
objecttreeparser.h
6 SPDX-FileCopyrightText: 2002-2003, 2009 Klarälvdalens Datakonsult AB, a KDAB Group company, [email protected]
78 First, have a look at the documentation in Mainpage.dox and at the documentation of ViewerPrivate
87 extracting the plainTextContent() for situations where only the message text is needed, for example
88 when inline forwarding a message. The mode depends on the Interface::ObjectTreeSource passed to the
89 constructor: If Interface::ObjectTreeSource::htmlWriter() is not 0, then the HTML code generation mode is
92 Basically, all the ObjectTreeParser does is going through the tree of MIME parts and operating on
95 of the current root node. For each of those subnodes, we try to find a BodyPartFormatter that can
97 processMultiPartAlternativeSubtype() or processTextHtmlSubtype(), or it can be an external plugin.
104 processed normally, the processMultipartXXX() functions call stdChildHandling() for the node that
105 should be handled normally. stdChildHandling() creates its own ObjectTreeParser, which is a clone
106 of the current ObjectTreeParser, and processes the node. stdChildHandling() is not called for all
107 children of the multipart node, for example processMultiPartAlternativeSubtype() only calls it on
109 processMultiPartSignedSubtype() doesn't call stdChildHandling() for the signature node, only for the
114 When a BodyPartFormatter has finished processing a node, it is processed. Nodes are set to being
115 not processed at the beginning of parseObjectTree(). The processed state of a node is saved in a
116 list in NodeHelper, see NodeHelper::setNodeProcessed(), NodeHelper::nodeProcessed() and the other
120 related functions. This is important so that processing the same node twice can be prevented. The
123 An example where duplicate processing would happen if we didn't check for it is in stdChildHandling(),
124 which is for example called from processMultiPartAlternativeSubtype(). Let's say the setting is to
127 parseObjectTree() on it. parseObjectTree() processes the node and all its siblings, and one of the
133 Various nodes have plain text that should be displayed. This plain text is usually processed though
134 writeBodyString() first. That method checks if the provided text is an inline PGP text and decrypts
135 it if necessary. It also pushes the text through quotedHTML(), which does a number of things like
141 before displaying. This is for example the case when displaying a decrypted message: The original
142 message only contains a binary blob of crypto data, and processMultiPartEncryptedSubtype() decrypts
143 that blob. After decryption, the current node is replaced with the decrypted node, which happens
148 For signature and decryption handling, there are functions which help with generating the HTML code
149 for the signature header and footer. These are writeDeferredDecryptionBlock(), writeSigstatFooter()
150 and writeSigstatHeader(). As the name writeDeferredDecryptionBlock() suggests, a setting can cause
152 decrypted or not can be controlled by Interface::ObjectTreeSource::decryptMessage(). When the user clicks the
153 decryption link, the URLHandler for 'kmail:' URLs sets that variable to true and triggers an update
158 The above case describes decryption the message in place. However, decryption and also verifying of
159 the signature can take a long time, so synchronous decryption and verifying would cause the Viewer to
161 In the first run of the async mode, all the ObjectTreeParser does is starting the decrypt or the
163 writeDecryptionInProgressBlock() or with writeSigstatHeader(). Then, it creates and associates a
164 BodyPartMemento with the current node, for example a VerifyDetachedBodyPartMemento. Each node can
168 retrieve these mementos. A memento is basically a thin wrapper around the crypto job, it stores the
169 job pointer, the job input data and the job result. Mementos can be used for any async situation,
177 At some point, the crypto jobs then finish, which will cause slotResult() of the BodyPartMemento
180 will, in ViewerPrivate::parseMsg(), create a new ObjectTreeParser and call parseObjectTree() on it.
184 processMultiPartEncryptedSubtype() will look if they find a BodyPartMemento that is associated with
185 the current node. Now it finds that memento, since it was created in the first run. It checks if the
186 memento's job has finished, and if so, the result can be written out (either the decrypted data or
189 When dealing with encrypted nodes, new nodes are created with the decrypted data. It is important to
190 note that the original MIME tree is never modified, and remains the same as the original one. The method
191 createAndParseTempNode is called with the newly decrypted data, and it generates a new temporary node to
192 store the decrypted data. When these nodes are created, it is important to keep track of them as otherwise
193 some mementos that are added to the newly created temporary nodes will be constantly regenerated. As the
194 regeneration triggers a viewer update when complete, it results in an infinite refresh loop. The function
195 NodeHelper::linkAsPermanentDecrypted will create a link between the newly created node and the original parent.
196 Conversely, the function NodeHelper::attachExtraContent will create a link in the other direction, from the parent
199 When generating some mementos for nodes that may be temporary nodes (for example, contact photo mementos), the
200 function NodeHelper::setBodyPartMementoForPermanentParent is used. This will save the given body part memento for
201 the closest found permanent parent node, rather than the transient node itself. Then when checking for the existence
202 of a certain memento in a node, NodeHelper::findPermanentParentBodyPartMemento will check to see if any parent of the
203 given temporary node is a permanent (encrypted) node that has been used to generate the asked-for node.
206 crypto operation and creates the BodyPartMemento, the second calls sees that the BodyPartMemento is
211 For crypto operations, the class PartMetaData is used a lot, mainly to pass around info about the
213 NodeHelper::setPartMetaData(). The only user of that however is MessageAnalyzer::processPart() of
216 You'll notice that a ProcessResult is passed to each formatter. The formatter is supposed to modify
217 the ProcessResult to tell the callers something about the state of the nodes that were processed.
222 As mentioned way earlier, BodyPartFormatter can either be plugins or be internal. bodypartformatter.cpp
226 The BodyPartFormatter code is work in progress, it was supposed to be refactored, but that has not
229 External plugins are loaded with loadPlugins() in bodypartformatterfactory.cpp. External plugins
232 external plugins have powerful capabilities, which are needed for example in the iCal formatter or
237 As also mentioned in the documentation of ViewerPrivate, the ObjectTreeParser writes out special
240 example a div with the id 'attachmentInjectionPoint', or a div with the id 'attachmentDiv', which
241 is used to mark an attachment in the body with a yellow border when the user clicks the attachment
242 in the header. Finally, parseObjectTree() creates an anchor with the id 'att%1', which is used in
249 * Copies the context of @p other, but not it's rawDecryptedBody, plainTextContent or htmlContent.
254 explicit ObjectTreeParser(Interface::ObjectTreeSource *source, NodeHelper *nodeHelper = nullptr);
304 MessagePartPtr processType(KMime::Content *node, MimeTreeParser::ProcessResult &processResult, const QByteArray &mimeType);
The HtmlMessagePart class.
Definition: mimetreeparser/src/messagepart.h:236
The EncryptedMessagePart class.
Definition: mimetreeparser/src/messagepart.h:332
Parses messages and generates HTML display code out of them.
Definition: objecttreeparser.h:245
Interface for object tree sources.
Definition: objecttreesource.h:32
an implementation of the BodyPart interface using KMime::Content's
Definition: partnodebodypart.h:31
The TextMessagePart class.
Definition: mimetreeparser/src/messagepart.h:186
The SignedMessagePart class.
Definition: mimetreeparser/src/messagepart.h:401
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Dec 1 2023 03:57:06 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Dec 1 2023 03:57:06 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.