KMime

kmime_content.h
Go to the documentation of this file.
1 /*
2  kmime_content.h
3 
4  KMime, the KDE Internet mail/usenet news message library.
5  SPDX-FileCopyrightText: 2001 the KMime authors.
6  See file AUTHORS for details
7  SPDX-FileCopyrightText: 2006 Volker Krause <[email protected]>
8  SPDX-FileCopyrightText: 2009 Constantin Berzan <[email protected]>
9 
10  SPDX-License-Identifier: LGPL-2.0-or-later
11 */
12 /**
13  @file
14  This file is part of the API for handling @ref MIME data and
15  defines the Content class.
16 
17  @brief
18  Defines the Content class.
19 
20  @authors the KMime authors (see AUTHORS file),
21  Volker Krause <[email protected]>
22 
23 TODO: possible glossary terms:
24  content
25  encoding, transfer type, disposition, description
26  header
27  body
28  attachment
29  charset
30  article
31  string representation
32  broken-down object representation
33 */
34 
35 #pragma once
36 
37 #include "kmime_export.h"
38 #include "kmime_contentindex.h"
39 #include "kmime_util.h"
40 #include "kmime_headers.h"
41 
42 #include <QByteArray>
43 #include <QVector>
44 #include <QSharedPointer>
45 #include <QMetaType>
46 
47 
48 namespace KMime
49 {
50 
51 class ContentPrivate;
52 class Message;
53 
54 /**
55  @brief
56  A class that encapsulates @ref MIME encoded Content.
57 
58  A Content object holds two representations of a content:
59  - the string representation: This is the content encoded as a string ready
60  for transport. Accessible through the encodedContent() method.
61  - the broken-down representation: This is the tree of objects (headers,
62  sub-Contents and (if present) the encapsulated message) that this Content is made of.
63  Accessible through methods like header(), contents() and bodyAsMessage().
64 
65  The parse() function updates the broken-down representation of the Content
66  from its string representation. Calling it is necessary to access the
67  headers, sub-Contents or the encapsulated message of this Content.
68 
69  The assemble() function updates the string representation of the Content
70  from its broken-down representation. Calling it is necessary for
71  encodedContent() to reflect any changes made to the broken-down representation of the Content.
72 
73  There are two basic types of a Content:
74  - A leaf Content: This is a content that is neither a multipart content nor an encapsulated
75  message. Because of this, it will not have any children, it has no sub-contents
76  and is therefore a leaf content.
77  Only leaf contents have a body that is not empty, i.e. functions that operate
78  on the body, such as body(), size() and decodedContent(), will work only on
79  leaf contents.
80  - A non-leaf Content: This is a content that itself doesn't have any body, but that does have
81  sub-contents.
82  This is the case for contents that are of mimetype multipart/ or of mimetype
83  message/rfc822. In case of a multipart content, contents() will return the
84  multipart child contents. In case of an encapsulated message, the message
85  can be accessed with bodyAsMessage(), and contents() will have one entry
86  that is the message as well.
87  On a non-leaf content, body() will have an empty return value and other
88  functions working on the body will not work.
89  A call to parse() is required before the child multipart contents or the
90  encapsulated message is created.
91 */
92 /*
93  KDE5:
94  * Do not convert singlepart <-> multipart automatically.
95  * A bunch of methods probably don't need to be virtual (since they're not needed
96  in either Message or NewsArticle).
97 */
98 class KMIME_EXPORT Content
99 {
100 public:
101 
102  /**
103  Describes a list of Content objects.
104  */
106 
107  /**
108  Creates an empty Content object with a specified parent.
109  @param parent the parent Content object
110  @since 4.3
111  */
112  explicit Content(Content *parent = nullptr);
113 
114  /**
115  Destroys this Content object.
116  */
117  virtual ~Content();
118 
119  /**
120  Returns true if this Content object is not empty.
121  */
122  Q_REQUIRED_RESULT bool hasContent() const;
123 
124  /**
125  Sets the Content to the given raw data, containing the Content head and
126  body separated by two linefeeds.
127 
128  This method operates on the string representation of the Content. Call
129  parse() if you want to access individual headers, sub-Contents or the
130  encapsulated message.
131 
132  @note The passed data must not contain any CRLF sequences, only LF.
133  Use CRLFtoLF for conversion before passing in the data.
134 
135  @param s is a QByteArray containing the raw Content data.
136  */
137  void setContent(const QByteArray &s);
138 
139  /**
140  * Parses the Content.
141  *
142  * This means the broken-down object representation of the Content is
143  * updated from the string representation of the Content.
144  *
145  * Call this if you want to access or change headers, sub-Contents or the encapsulated
146  * message.
147  *
148  * @note Calling parse() twice will not work for multipart contents or for contents of which
149  * the body is an encapsulated message. The reason is that the first parse() will delete
150  * the body, so there is no body to work on for the second call of parse().
151  *
152  * @note Calling this will reset the message returned by bodyAsMessage(), as
153  * the message is re-parsed as well.
154  * Also, all old sub-contents will be deleted, so any old Content pointer will become
155  * invalid.
156  */
157  void parse();
158 
159  /**
160  Returns whether this Content is frozen.
161  A frozen content is immutable, i.e. calling assemble() will never modify
162  its head or body, and encodedContent() will return the same data before
163  and after parsing.
164 
165  @since 4.4.
166  @see setFrozen().
167  */
168  Q_REQUIRED_RESULT bool isFrozen() const;
169 
170  /**
171  Freezes this Content if @p frozen is true; otherwise unfreezes it.
172  @param frozen freeze content if @c true, otherwise unfreeze
173  @since 4.4
174  @see isFrozen().
175  */
176  void setFrozen(bool frozen = true);
177 
178  /**
179  Generates the MIME content.
180  This means the string representation of this Content is updated from the
181  broken-down object representation.
182  Call this if you have made changes to the content, and want
183  encodedContent() to reflect those changes.
184 
185  @note assemble() has no effect if the Content isFrozen(). You may want
186  to freeze, for instance, signed sub-Contents, to make sure they are kept
187  unmodified.
188 
189  @note If this content is an encapsulated message, i.e. bodyIsMessage() returns true,
190  then calling assemble() will also assemble the message returned by bodyAsMessage().
191 
192  @warning assemble() may change the order of the headers, and other
193  details such as where folding occurs. This may break things like
194  signature verification, so you should *ONLY* call assemble() when you
195  have actually modified the content.
196  */
197  void assemble();
198 
199  /**
200  Clears the content, deleting all headers and sub-Contents.
201  */
202  void clear();
203 
204  /**
205  Removes all sub-Contents from this content. Deletes them if @p del is true.
206  This is different from calling removeContent() on each sub-Content, because
207  removeContent() will convert this to a single-part Content if only one
208  sub-Content is left. Calling clearContents() does NOT make this Content
209  single-part.
210 
211  @param del Whether to delete the sub-Contents.
212  @see removeContent()
213  @since 4.4
214  */
215  void clearContents(bool del = true);
216 
217  /**
218  Returns the Content header raw data.
219 
220  @see setHead().
221  */
222  Q_REQUIRED_RESULT QByteArray head() const;
223 
224  /**
225  Sets the Content header raw data.
226 
227  This method operates on the string representation of the Content. Call
228  parse() if you want to access individual headers.
229 
230  @param head is a QByteArray containing the header data.
231 
232  @see head().
233  */
234  void setHead(const QByteArray &head);
235 
236  /**
237  * Returns all headers.
238  * @since 5.7
239  */
240  Q_REQUIRED_RESULT QVector<Headers::Base*> headers() const;
241 
242  /**
243  Returns the first header of type @p type, if it exists. Otherwise returns 0.
244  Note that the returned header may be empty.
245  @param type the header type to find
246  @since 4.2
247  */
248  Headers::Base *headerByType(const char *type) const;
249 
250  /**
251  Returns the first header of type T, if it exists.
252  If the header does not exist and @p create is true, creates an empty header
253  and returns it. Otherwise returns 0.
254  Note that the returned header may be empty.
255  @param create Whether to create the header if it does not exist.
256  @since 4.4.
257 
258  KDE5: BIC: FIXME: Why is the default argument false here? That is inconsistent with the
259  methods in KMime::Message!
260  */
261  template <typename T> T *header(bool create = false);
262 
263  /**
264  Returns all @p type headers in the Content.
265  Take care that this result is not cached, so could be slow.
266  @param type the header type to find
267  @since 4.2
268  */
269  Q_REQUIRED_RESULT QVector<Headers::Base*> headersByType(const char *type) const;
270 
271  /**
272  Sets the specified header to this Content.
273  Any previous header of the same type is removed.
274  If you need multiple headers of the same type, use appendHeader() or
275  prependHeader().
276 
277  @param h The header to set.
278  @see appendHeader()
279  @see removeHeader()
280  @since 4.4
281  */
282  void setHeader(Headers::Base *h);
283 
284  /**
285  Appends the specified header to the headers of this Content.
286  @param h The header to append.
287  @since 4.4
288  */
289  void appendHeader(Headers::Base *h);
290 
291  /**
292  Searches for the first header of type @p type, and deletes it, removing
293  it from this Content.
294  @param type The type of the header to look for.
295  @return true if a header was found and removed.
296  */
297  bool removeHeader(const char *type);
298 
299  /**
300  Searches for the first header of type @p T, and deletes it, removing
301  it from this Content.
302  @tparam T The type of the header to look for.
303  @return true if a header was found and removed.
304  */
305  template <typename T> bool removeHeader();
306 
307 
308  /**
309  @return true if this Content has a header of type @p type.
310  @param type The type of the header to look for.
311  */
312  // TODO probably provide hasHeader<T>() too.
313  Q_REQUIRED_RESULT bool hasHeader(const char *type) const;
314 
315  /**
316  Returns the Content-Type header.
317 
318  @param create If true, create the header if it doesn't exist yet.
319  */
320  Headers::ContentType *contentType(bool create = true);
321 
322  /**
323  Returns the Content-Transfer-Encoding header.
324 
325  @param create If true, create the header if it doesn't exist yet.
326  */
327  Headers::ContentTransferEncoding *contentTransferEncoding(bool create = true);
328 
329  /**
330  Returns the Content-Disposition header.
331 
332  @param create If true, create the header if it doesn't exist yet.
333  */
334  Headers::ContentDisposition *contentDisposition(bool create = true);
335 
336  /**
337  Returns the Content-Description header.
338 
339  @param create If true, create the header if it doesn't exist yet.
340  */
341  Headers::ContentDescription *contentDescription(bool create = true);
342 
343  /**
344  Returns the Content-Location header.
345 
346  @param create If true, create the header if it doesn't exist yet.
347  @since 4.2
348  */
349  Headers::ContentLocation *contentLocation(bool create = true);
350 
351  /**
352  Returns the Content-ID header.
353  @param create if true, create the header if it does not exist yet.
354  @since 4.4
355  */
356  Headers::ContentID *contentID(bool create = true);
357 
358  /**
359  Returns the size of the Content body after encoding.
360  (If the encoding is quoted-printable, this is only an approximate size.)
361  This will return 0 for multipart contents or for encapsulated messages.
362  */
363  Q_REQUIRED_RESULT int size();
364 
365  /**
366  Returns the size of this Content and all sub-Contents.
367  */
368  Q_REQUIRED_RESULT int storageSize() const;
369 
370  /**
371  Line count of this Content and all sub-Contents.
372  */
373  Q_REQUIRED_RESULT int lineCount() const;
374 
375  /**
376  Returns the Content body raw data.
377 
378  Note that this will be empty for multipart contents or for encapsulated messages,
379  after parse() has been called.
380 
381  @see setBody().
382  */
383  Q_REQUIRED_RESULT QByteArray body() const;
384 
385  /**
386  Sets the Content body raw data.
387 
388  This method operates on the string representation of the Content. Call
389  parse() if you want to access individual sub-Contents or the encapsulated message.
390 
391  @param body is a QByteArray containing the body data.
392 
393  @see body().
394  */
395  void setBody(const QByteArray &body);
396 
397  /**
398  Returns the MIME preamble.
399 
400  @return a QByteArray containing the MIME preamble.
401 
402  @since 4.9
403  */
404  Q_REQUIRED_RESULT QByteArray preamble() const;
405 
406  /**
407  Sets the MIME preamble.
408 
409  @param preamble a QByteArray containing what will be used as the
410  MIME preamble.
411 
412  @since 4.9
413  */
414 
415  void setPreamble(const QByteArray &preamble);
416 
417  /**
418  Returns the MIME preamble.
419 
420  @return a QByteArray containing the MIME epilogue.
421 
422  @since 4.9
423  */
424  Q_REQUIRED_RESULT QByteArray epilogue() const;
425 
426  /**
427  Sets the MIME preamble.
428 
429  @param epilogue a QByteArray containing what will be used as the
430  MIME epilogue.
431 
432  @since 4.9
433  */
434  void setEpilogue(const QByteArray &epilogue);
435 
436  /**
437  Returns a QByteArray containing the encoded Content, including the
438  Content header and all sub-Contents.
439 
440  If you make changes to the broken-down representation of the message, be
441  sure to first call assemble() before calling encodedContent(), otherwise
442  the result will not be up-to-date.
443 
444  If this content is an encapsulated message, i.e. bodyIsMessage() returns true,
445  then encodedContent() will use the message returned by bodyAsMessage() as the
446  body of the result, calling encodedContent() on the message.
447 
448  @param useCrLf If true, use @ref CRLF instead of @ref LF for linefeeds.
449  */
450  Q_REQUIRED_RESULT QByteArray encodedContent(bool useCrLf = false);
451 
452  /**
453  * Like encodedContent(), with the difference that only the body will be returned, i.e. the
454  * headers are excluded.
455  *
456  * @since 4.6
457  */
458  Q_REQUIRED_RESULT QByteArray encodedBody();
459 
460  /**
461  * Returns the decoded Content body.
462  *
463  * Note that this will be empty for multipart contents or for encapsulated messages,
464  * after parse() has been called.
465  */
466  // TODO: KDE5: BIC: Rename this to decodedBody(), since only the body is returned.
467  // In contrast, setContent() sets the head and the body!
468  // Also, try to make this const.
469  Q_REQUIRED_RESULT QByteArray decodedContent();
470 
471  /**
472  Returns the decoded text. Additional to decodedContent(), this also
473  applies charset decoding. If this is not a text Content, decodedText()
474  returns an empty QString.
475 
476  @param trimText If true, then the decoded text will have all trailing
477  whitespace removed.
478  @param removeTrailingNewlines If true, then the decoded text will have
479  all consecutive trailing newlines removed.
480 
481  The last trailing new line of the decoded text is always removed.
482 
483  */
484  // TODO: KDE5: BIC: Convert to enums. Also, what if trimText = true but removeTrailingNewlines
485  // is false?
486  Q_REQUIRED_RESULT QString decodedText(bool trimText = false,
487  bool removeTrailingNewlines = false);
488 
489  /**
490  Sets the Content body to the given string using charset of the content type.
491 
492  If the charset can not be found, the system charset is taken and the content type header is
493  changed to that charset.
494  The charset of the content type header should be set to a charset that can encode the given
495  string before calling this method.
496 
497  This method does not set the content transfer encoding automatically, it needs to be set
498  to a suitable value that can encode the given string before calling this method.
499 
500  This method only makes sense for single-part contents, do not try to pass a multipart body
501  or an encapsulated message here, that wouldn't work.
502 
503  @param s Unicode-encoded string.
504  */
505  void fromUnicodeString(const QString &s);
506 
507  /**
508  Returns the first Content with mimetype text/.
509  */
510  Content *textContent();
511 
512  /**
513  * Returns all attachments below this node, recursively.
514  * This does not include crypto parts, nodes of alternative or related multipart nodes, or
515  * the primary body part (see textContent()).
516  * @see KMime::isAttachment(), KMime::hasAttachment()
517  */
518  Q_REQUIRED_RESULT QVector<Content*> attachments();
519 
520  /**
521  * For multipart contents, this will return a list of all multipart child contents.
522  * For contents that are of mimetype message/rfc822, this will return a list with one entry,
523  * and that entry is the encapsulated message, as it would be returned by bodyAsMessage().
524  */
525  Q_REQUIRED_RESULT QVector<Content*> contents() const;
526 
527  /**
528  Adds a new sub-Content. If the sub-Content is already part of another
529  Content object, it is removed from there and its parent is updated.
530  If the current Content object is single-part, it is converted to
531  multipart/mixed first.
532 
533  @warning If the single-part to multipart conversion happens, all
534  pointers you may have into this object (such as headers) will become
535  invalid!
536 
537  @param content The new sub-Content.
538  @param prepend If true, prepend to the Content list; otherwise append.
539  to the Content list.
540 
541  @see removeContent().
542  */
543  // KDE5: Do not convert single-part->multipart automatically.
544  void addContent(Content *content, bool prepend = false);
545 
546  void replaceContent(Content *oldContent, Content *newContent);
547  /**
548  Removes the given sub-Content. If only one sub-Content is left, the
549  current Content object is converted into a single-part Content.
550 
551  @warning If the multipart to single-part conversion happens, the head
552  and body of the single remaining sub-Content are copied over, and the
553  sub-Content is deleted. All pointers to it or into it (such as headers)
554  will become invalid!
555 
556  @param content The Content to remove.
557  @param del If true, delete the removed Content object. Otherwise set its
558  parent to 0.
559 
560  @see addContent().
561  @see clearContents().
562  */
563  // KDE5: Do not convert multipart->single-part automatically.
564  void removeContent(Content *content, bool del = false);
565 
566  /**
567  Changes the encoding of this Content to @p e. If the Content is binary,
568  this actually re-encodes the data to use the new encoding.
569 
570  @param e The new encoding to use.
571  */
572  void changeEncoding(Headers::contentEncoding e);
573 
574  /**
575  Returns the charset that is used to decode RFC2047 strings in all headers and to decode
576  the body if the charset is not declared explicitly.
577  It is also used as the charset when encoding RFC2047 strings in headers.
578  */
579  // TODO: Split this up into a charset for encoding and one for decoding, and make the one for
580  // encoding UTF-8 by default.
581  static QByteArray defaultCharset();
582 
583  /**
584  Returns the Content specified by the given index.
585  If the index does not point to a Content, 0 is returned. If the index
586  is invalid (empty), this Content is returned.
587 
588  @param index The Content index.
589  */
590  Content *content(const ContentIndex &index) const;
591 
592  /**
593  Returns the ContentIndex for the given Content, or an invalid index
594  if the Content is not found within the hierarchy.
595  @param content the Content object to search.
596  */
597  Q_REQUIRED_RESULT ContentIndex indexForContent(Content *content) const;
598 
599  /**
600  Returns true if this is the top-level node in the MIME tree. The top-level node is always
601  a Message or NewsArticle. However, a node can be a Message without being a top-level node when
602  it is an encapsulated message.
603  */
604  Q_REQUIRED_RESULT bool isTopLevel() const;
605 
606  /**
607  * Sets a new parent to the Content and add to its contents list. If it already had a parent, it is removed from the
608  * old parents contents list.
609  * @param parent the new parent
610  * @since 4.3
611  */
612  void setParent(Content *parent);
613 
614  /**
615  * Returns the parent content object, or 0 if the content doesn't have a parent.
616  * @since 4.3
617  */
618  Content *parent() const;
619 
620  /**
621  * Returns the toplevel content object, 0 if there is no such object.
622  * @since 4.3
623  */
624  Content *topLevel() const;
625 
626  /**
627  * Returns the index of this Content based on the topLevel() object.
628  * @since 4.3
629  */
630  Q_REQUIRED_RESULT ContentIndex index() const;
631 
632  /**
633  * @return true if this content is an encapsulated message, i.e. if it has the mimetype
634  * message/rfc822.
635  *
636  * @since 4.5
637  */
638  //AK_REVIEW: move to MessageViewer/ObjectTreeParser
639  Q_REQUIRED_RESULT bool bodyIsMessage() const;
640 
641  /**
642  * If this content is an encapsulated message, in which case bodyIsMessage() will return
643  * true, the message represented by the body of this content will be returned.
644  * The returned message is already fully parsed.
645  * Calling this method is the aquivalent of calling contents().first() and casting the result
646  * to a KMime::Message*. bodyAsMessage() has the advantage that it will return a shared pointer
647  * that will not be destroyed when the container message is destroyed or re-parsed.
648  *
649  * The message that is returned here is created when calling parse(), so make sure to call
650  * parse() first. Since each parse() creates a new message object, a different message object
651  * will be returned each time you call parse().
652  *
653  * If you make changes to the returned message, you need to call assemble() on this content
654  * or on the message if you want that encodedContent() reflects these changes. This also means
655  * that calling assemble() on this content will assemble the returned message.
656  *
657  * @since 4.5
658  */
659  //AK_REVIEW: move to MessageViewer/ObjectTreeParser
660  Q_REQUIRED_RESULT QSharedPointer<Message> bodyAsMessage() const;
661 
662 protected:
663  /**
664  Reimplement this method if you need to assemble additional headers in a
665  derived class. Don't forget to call the implementation of the base class.
666  @return The raw, assembled headers.
667  */
668  virtual QByteArray assembleHeaders();
669 
670  //@cond PRIVATE
671  ContentPrivate *d_ptr;
672  //@endcond
673 
674 private:
675  Q_DECLARE_PRIVATE(Content)
676  Q_DISABLE_COPY(Content)
677 };
678 
679 template <typename T> T *Content::header(bool create)
680 {
681  Headers::Base *h = headerByType(T::staticType());
682  if (h) {
683  // Make sure the header is actually of the right type.
684  Q_ASSERT(dynamic_cast<T *>(h));
685  } else if (create) {
686  h = new T;
687  appendHeader(h); // we already know the header doesn't exist yet
688  }
689  return static_cast<T *>(h);
690 }
691 
692 template <typename T> bool Content::removeHeader()
693 {
694  return removeHeader(T::staticType());
695 }
696 
697 } // namespace KMime
698 
699 Q_DECLARE_METATYPE(KMime::Content*)
700 
Represents a "Content-Disposition" header.
bool removeHeader()
Searches for the first header of type T, and deletes it, removing it from this Content.
Represents a "Content-ID" header.
Baseclass of all header-classes.
This file is part of the API for handling MIME data and defines the various header classes: ...
Represents a "Content-Location" header.
Represents a "Content-Description" header.
A class that encapsulates MIME encoded Content.
Definition: kmime_content.h:98
Represents a "Content-Transfer-Encoding" header.
Represents a "Content-Type" header.
QVector< KMime::Content * > List
Describes a list of Content objects.
contentEncoding
Various possible values for the "Content-Transfer-Encoding" header.
Definition: kmime_headers.h:59
This file is part of the API for handling MIME data and defines the ContentIndex class.
A class to uniquely identify message parts (Content) in a hierarchy.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Sep 20 2021 23:14:43 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.