KMime

headers.h
Go to the documentation of this file.
1/* -*- c++ -*-
2 kmime_headers.h
3
4 KMime, the KDE Internet mail/usenet news message library.
5 SPDX-FileCopyrightText: 2001-2002 the KMime authors.
6 See file AUTHORS for details
7 SPDX-FileCopyrightText: 2006 Volker Krause <vkrause@kde.org>
8
9 SPDX-License-Identifier: LGPL-2.0-or-later
10*/
11/**
12 @file
13 This file is part of the API for handling @ref MIME data and
14 defines the various header classes:
15 - header's base class defining the common interface
16 - generic base classes for different types of fields
17 - incompatible, Structured-based field classes
18 - compatible, Unstructured-based field classes
19
20 @brief
21 Defines the various headers classes.
22
23 @authors the KMime authors (see AUTHORS file),
24 Volker Krause <vkrause@kde.org>
25*/
26
27#pragma once
28
29#include "kmime_export.h"
30#include "headerparsing.h"
31
32#include <QByteArray>
33#include <QDateTime>
34#include <QList>
35#include <QMetaType>
36#include <QString>
37#include <QStringList>
38
39namespace KMime
40{
41
42class Content;
43
44namespace Headers
45{
46
47class BasePrivate;
48
49/**
50 Various possible values for the "Content-Transfer-Encoding" header.
51*/
53 CE7Bit, ///< 7bit
54 CE8Bit, ///< 8bit
55 CEquPr, ///< quoted-printable
56 CEbase64, ///< base64
57 CEuuenc, ///< uuencode
58 CEbinary ///< binary
59};
60
61/**
62 Various possible values for the "Content-Disposition" header.
63*/
65 CDInvalid, ///< Default, invalid value
66 CDinline, ///< inline
67 CDattachment, ///< attachment
68 CDparallel ///< parallel (invalid, do not use)
69};
70
71//@cond PRIVATE
72// internal macro to generate default constructors
73#define kmime_mk_trivial_ctor( subclass ) \
74 public: \
75 subclass(); \
76 ~subclass() override;
77
78#define kmime_mk_dptr_ctor( subclass ) \
79 protected: \
80 explicit subclass( subclass##Private *d );
81
82#define kmime_mk_trivial_ctor_with_name( subclass ) \
83 kmime_mk_trivial_ctor( subclass ) \
84 [[nodiscard]] const char *type() const override; \
85 [[nodiscard]] static const char *staticType();
86//@endcond
87
88//
89//
90// HEADER'S BASE CLASS. DEFINES THE COMMON INTERFACE
91//
92//
93
94/** Baseclass of all header-classes. It represents a
95 header-field as described in RFC-822. */
96class KMIME_EXPORT Base
97{
98public:
99 /**
100 A vector of headers.
101 */
103
104 /**
105 Creates an empty header.
106 */
107 Base();
108
109 /**
110 Destructor.
111 */
112 virtual ~Base();
113
114 /**
115 Parses the given string. Take care of RFC2047-encoded strings.
116 @param s The encoded header data.
117 */
118 virtual void from7BitString(QByteArrayView s) = 0;
119
120 /**
121 Returns the encoded header.
122 @param withHeaderType Specifies whether the header-type should be included.
123 */
124 [[nodiscard]] virtual QByteArray
125 as7BitString(bool withHeaderType = true) const = 0;
126
127 /**
128 Returns the charset that is used for RFC2047-encoding.
129 */
130 [[nodiscard]] QByteArray rfc2047Charset() const;
131
132 /**
133 Sets the charset for RFC2047-encoding.
134 @param cs The new charset used for RFC2047 encoding.
135 */
136 void setRFC2047Charset(const QByteArray &cs);
137
138 /**
139 Parses the given Unicode representation of the header content.
140 @param s The header data as Unicode string.
141 */
142 virtual void fromUnicodeString(const QString &s) = 0;
143 [[deprecated("call setRFC2047Charset for the second argument if different from UTF-8, otherwise remove second argument")]]
144 inline void fromUnicodeString(const QString &s, const QByteArray &b)
145 {
146 setRFC2047Charset(b);
147 fromUnicodeString(s);
148 }
149
150 /**
151 Returns the decoded content of the header without the header-type.
152
153 @note The return value of this method should only be used when showing an
154 address to the user. It is not guaranteed that fromUnicodeString(
155 asUnicodeString(), ... ) will return the original string.
156 */
157 [[nodiscard]] virtual QString asUnicodeString() const = 0;
158
159 /**
160 Checks if this header contains any data.
161 */
162 [[nodiscard]] virtual bool isEmpty() const = 0;
163
164 /**
165 Returns the type of this header (e.g. "From").
166 */
167 [[nodiscard]] virtual const char *type() const;
168
169 /**
170 Checks if this header is of type @p t.
171 */
172 [[nodiscard]] bool is(QByteArrayView t) const;
173
174protected:
175 /**
176 Helper method, returns the header prefix including ":".
177 */
178 [[nodiscard]] QByteArray typeIntro() const;
179
180 //@cond PRIVATE
181 BasePrivate *d_ptr;
182 kmime_mk_dptr_ctor(Base)
183 //@endcond
184
185private:
186 Q_DECLARE_PRIVATE(Base)
187 Q_DISABLE_COPY(Base)
188};
189
190//
191//
192// GENERIC BASE CLASSES FOR DIFFERENT TYPES OF FIELDS
193//
194//
195
196namespace Generics
197{
198
199class UnstructuredPrivate;
200
201/**
202 Abstract base class for unstructured header fields
203 (e.g. "Subject", "Comment", "Content-description").
204
205 Features: Decodes the header according to RFC2047, incl. RFC2231
206 extensions to encoded-words.
207
208 Subclasses need only re-implement @p const @p char* @p type().
209*/
210
211// known issues:
212// - uses old decodeRFC2047String function, instead of our own...
213
214class KMIME_EXPORT Unstructured : public Base
215{
216 //@cond PRIVATE
217 kmime_mk_dptr_ctor(Unstructured)
218 //@endcond
219public:
220 Unstructured();
221 ~Unstructured() override;
222
223 void from7BitString(QByteArrayView s) override;
224 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
225
226 void fromUnicodeString(const QString &s) override;
227 using Base::fromUnicodeString;
228 [[nodiscard]] QString asUnicodeString() const override;
229
230 [[nodiscard]] bool isEmpty() const override;
231
232private:
233 Q_DECLARE_PRIVATE(Unstructured)
234};
235
236class StructuredPrivate;
237
238/**
239 @brief
240 Base class for structured header fields.
241
242 This is the base class for all structured header fields.
243 It contains parsing methods for all basic token types found in rfc2822.
244
245 @section Parsing
246
247 At the basic level, there are tokens & tspecials (rfc2045),
248 atoms & specials, quoted-strings, domain-literals (all rfc822) and
249 encoded-words (rfc2047).
250
251 As a special token, we have the comment. It is one of the basic
252 tokens defined in rfc822, but it's parsing relies in part on the
253 basic token parsers (e.g. comments may contain encoded-words).
254 Also, most upper-level parsers (notably those for phrase and
255 dot-atom) choose to ignore any comment when parsing.
256
257 Then there are the real composite tokens, which are made up of one
258 or more of the basic tokens (and semantically invisible comments):
259 phrases (rfc822 with rfc2047) and dot-atoms (rfc2822).
260
261 This finishes the list of supported token types. Subclasses will
262 provide support for more higher-level tokens, where necessary,
263 using these parsers.
264
265 @author Marc Mutz <mutz@kde.org>
266*/
267
268class KMIME_EXPORT Structured : public Base
269{
270public:
271 Structured();
272 ~Structured() override;
273
274 void from7BitString(QByteArrayView s) override;
275 [[nodiscard]] QString asUnicodeString() const override;
276 void fromUnicodeString(const QString &s) override;
277 using Base::fromUnicodeString;
278
279protected:
280 /**
281 This method parses the raw header and needs to be implemented in
282 every sub-class.
283
284 @param scursor Pointer to the start of the data still to parse.
285 @param send Pointer to the end of the data.
286 @param isCRLF true if input string is terminated with a CRLF.
287 */
288 virtual bool parse(const char *&scursor, const char *const send,
289 bool isCRLF = false) = 0;
290
291 //@cond PRIVATE
292 kmime_mk_dptr_ctor(Structured)
293 //@endcond
294
295private:
296 Q_DECLARE_PRIVATE(Structured)
297};
298
299class AddressPrivate;
300
301/**
302 Base class for all address related headers.
303*/
304class KMIME_EXPORT Address : public Structured
305{
306public:
307 Address();
308 ~Address() override;
309protected:
310 //@cond PRIVATE
311 kmime_mk_dptr_ctor(Address)
312 //@endcond
313private:
314 Q_DECLARE_PRIVATE(Address)
315};
316
317class MailboxListPrivate;
318
319/**
320 Base class for headers that deal with (possibly multiple)
321 addresses, but don't allow groups.
322
323 @see RFC 2822, section 3.4
324*/
325class KMIME_EXPORT MailboxList : public Address
326{
327 //@cond PRIVATE
328 kmime_mk_trivial_ctor(MailboxList)
329 kmime_mk_dptr_ctor(MailboxList)
330 //@endcond
331public:
332 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
333 void fromUnicodeString(const QString &s) override;
334 using Base::fromUnicodeString;
335 [[nodiscard]] QString asUnicodeString() const override;
336
337 [[nodiscard]] bool isEmpty() const override;
338
339 /**
340 Adds an address to this header.
341
342 @param mbox A Mailbox object specifying the address.
343 */
344 void addAddress(const Types::Mailbox &mbox);
345
346 /**
347 Adds an address to this header.
348 @param address The actual email address, with or without angle brackets.
349 @param displayName An optional name associated with the address.
350 */
351 void addAddress(const QByteArray &address,
352 const QString &displayName = QString());
353
354 /**
355 Returns a list of all addresses in this header, regardless of groups.
356 */
357 [[nodiscard]] QList<QByteArray> addresses() const;
358
359 /**
360 Returns a list of all display names associated with the addresses in
361 this header. The address is added for addresses that do not have
362 a display name.
363 */
364 [[nodiscard]] QStringList displayNames() const;
365
366 /**
367 Returns a single string for user-facing display of this mailbox list.
368 This is equivalent to displayNames().join(", ").
369 @since 5.14
370 */
371 [[nodiscard]] QString displayString() const;
372
373 /**
374 Returns a list of mailboxes listed in this header.
375 */
376 [[nodiscard]] Types::Mailbox::List mailboxes() const;
377
378 /**
379 Sets the mailboxes listed in this header, replacing the current content.
380 @since 24.12
381 */
382 void setMailboxes(const Types::Mailbox::List &mailboxes);
383
384protected:
385 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
386
387private:
388 Q_DECLARE_PRIVATE(MailboxList)
389};
390
391class SingleMailboxPrivate;
392
393/**
394 Base class for headers that deal with exactly one mailbox
395 (e.g. Sender).
396*/
397class KMIME_EXPORT SingleMailbox : public MailboxList
398{
399 //@cond PRIVATE
400 kmime_mk_trivial_ctor(SingleMailbox)
401 //@endcond
402protected:
403 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
404private:
405 Q_DECLARE_PRIVATE(SingleMailbox)
406};
407
408class AddressListPrivate;
409
410/**
411 Base class for headers that deal with (possibly multiple)
412 addresses, allowing groups.
413
414 Note: Groups are parsed but not represented in the API yet. All addresses in
415 groups are listed as if they would not be part of a group.
416
417 @todo Add API for groups?
418
419 @see RFC 2822, section 3.4
420*/
421class KMIME_EXPORT AddressList : public Address
422{
423 //@cond PRIVATE
424 kmime_mk_trivial_ctor(AddressList)
425 kmime_mk_dptr_ctor(AddressList)
426 //@endcond
427public:
428 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
429 void fromUnicodeString(const QString &s) override;
430 using Base::fromUnicodeString;
431 [[nodiscard]] QString asUnicodeString() const override;
432
433 [[nodiscard]] bool isEmpty() const override;
434
435 /**
436 Adds an address to this header.
437
438 @param mbox A Mailbox object specifying the address.
439 */
440 void addAddress(const Types::Mailbox &mbox);
441
442 /**
443 Adds an address to this header.
444 @param address The actual email address, with or without angle brackets.
445 @param displayName An optional name associated with the address.
446 */
447 void addAddress(const QByteArray &address, const QString &displayName = QString());
448
449 /**
450 Returns a list of all addresses in this header, regardless of groups.
451 */
452 [[nodiscard]] QList<QByteArray> addresses() const;
453
454 /**
455 Returns a list of all display names associated with the addresses in this header.
456 The address is added for addresses that don't have a display name.
457 */
458 [[nodiscard]] QStringList displayNames() const;
459
460 /**
461 Returns a single string for user-facing display of this address list.
462 This is equivalent to displayNames().join(", ").
463 @since 5.14
464 */
465 [[nodiscard]] QString displayString() const;
466
467 /**
468 Returns a list of mailboxes listed in this header.
469 */
470 [[nodiscard]] Types::Mailbox::List mailboxes() const;
471
472 /**
473 Sets the list of addresses listed in this header, replacing the existing content.
474 @since 24.12
475 */
476 void setAddressList(const Types::AddressList &addresses);
477
478protected:
479 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
480
481private:
482 Q_DECLARE_PRIVATE(AddressList)
483};
484
485class IdentPrivate;
486
487/**
488 Base class for headers which deal with a list of msg-id's.
489
490 @see RFC 2822, section 3.6.4
491*/
492class KMIME_EXPORT Ident : public Address
493{
494 //@cond PRIVATE
495 kmime_mk_trivial_ctor(Ident)
496 kmime_mk_dptr_ctor(Ident)
497 //@endcond
498public:
499 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
500 [[nodiscard]] bool isEmpty() const override;
501
502 /**
503 Initialize this identifier Copy the data from
504 */
505 void fromIdent(const Ident* ident);
506
507 /**
508 Returns the list of identifiers contained in this header.
509 Note:
510 - Identifiers are not enclosed in angle-brackets.
511 - Identifiers are listed in the same order as in the header.
512 */
513 [[nodiscard]] QList<QByteArray> identifiers() const;
514
515 /**
516 Appends a new identifier to this header.
517 @param id The identifier to append, with or without angle-brackets.
518 */
519 void appendIdentifier(const QByteArray &id);
520
521protected:
522 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
523
524private:
525 Q_DECLARE_PRIVATE(Ident)
526};
527
528class SingleIdentPrivate;
529
530/**
531 Base class for headers which deal with a single msg-id.
532
533 @see RFC 2822, section 3.6.4
534*/
535class KMIME_EXPORT SingleIdent : public Ident
536{
537 //@cond PRIVATE
538 kmime_mk_trivial_ctor(SingleIdent)
539 kmime_mk_dptr_ctor(SingleIdent)
540 //@endcond
541public:
542 /**
543 Returns the identifier contained in this header.
544 Note: The identifiers is not enclosed in angle-brackets.
545 */
546 [[nodiscard]] QByteArray identifier() const;
547
548 /**
549 Sets the identifier.
550 @param id The new identifier with or without angle-brackets.
551 */
552 void setIdentifier(const QByteArray &id);
553
554protected:
555 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
556
557private:
558 Q_DECLARE_PRIVATE(SingleIdent)
559};
560
561class TokenPrivate;
562
563/**
564 Base class for headers which deal with a single atom.
565*/
566class KMIME_EXPORT Token : public Structured
567{
568 //@cond PRIVATE
569 kmime_mk_trivial_ctor(Token)
570 kmime_mk_dptr_ctor(Token)
571 //@endcond
572public:
573 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
574 [[nodiscard]] bool isEmpty() const override;
575
576 /**
577 Returns the token.
578 */
579 [[nodiscard]] QByteArray token() const;
580
581 /**
582 Sets the token to @p t,
583 */
584 void setToken(const QByteArray &t);
585
586protected:
587 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
588
589private:
590 Q_DECLARE_PRIVATE(Token)
591};
592
593class PhraseListPrivate;
594
595/**
596 Base class for headers containing a list of phrases.
597*/
598class KMIME_EXPORT PhraseList : public Structured
599{
600 //@cond PRIVATE
601 kmime_mk_trivial_ctor(PhraseList)
602 //@endcond
603public:
604 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
605 [[nodiscard]] QString asUnicodeString() const override;
606 [[nodiscard]] bool isEmpty() const override;
607
608 /**
609 Returns the list of phrases contained in this header.
610 */
611 [[nodiscard]] QStringList phrases() const;
612
613protected:
614 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
615
616private:
617 Q_DECLARE_PRIVATE(PhraseList)
618};
619
620class DotAtomPrivate;
621
622/**
623 Base class for headers containing a dot atom.
624*/
625class KMIME_EXPORT DotAtom : public Structured
626{
627 //@cond PRIVATE
628 kmime_mk_trivial_ctor(DotAtom)
629 //@endcond
630public:
631 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
632 [[nodiscard]] QString asUnicodeString() const override;
633 [[nodiscard]] bool isEmpty() const override;
634
635protected:
636 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
637
638private:
639 Q_DECLARE_PRIVATE(DotAtom)
640};
641
642class ParametrizedPrivate;
643
644/**
645 Base class for headers containing a parameter list such as "Content-Type".
646*/
647class KMIME_EXPORT Parametrized : public Structured
648{
649 //@cond PRIVATE
650 kmime_mk_trivial_ctor(Parametrized)
651 kmime_mk_dptr_ctor(Parametrized)
652 //@endcond
653public:
654 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
655
656 [[nodiscard]] bool isEmpty() const override;
657
658 /**
659 Returns the value of the specified parameter.
660 @param key The parameter name.
661 */
662 [[nodiscard]] QString parameter(QByteArrayView key) const;
663 [[deprecated("use QByteArrayView as argument")]] [[nodiscard]] inline QString parameter(const QString &key) const
664 {
665 return parameter(QByteArrayView(key.toUtf8()));
666 }
667 [[deprecated("use QByteArrayView as argument")]] [[nodiscard]] inline QString parameter(QLatin1StringView key) const
668 {
669 return parameter(QByteArrayView(key));
670 }
671 // overload resolution helper, remove once the above deprecated overloads are removed
672 template <std::size_t N>
673 [[nodiscard]] inline QString parameter(const char (&key)[N]) const
674 {
675 return parameter(QByteArrayView(key, N));
676 }
677
678 /**
679 @param key the key of the parameter to check for
680 @return true if a parameter with the given @p key exists.
681 @since 4.5
682 */
683 [[nodiscard]] bool hasParameter(QByteArrayView key) const;
684 [[deprecated("use QByteArrayView as argument")]] [[nodiscard]] inline bool hasParameter(const QString &key) const
685 {
686 return hasParameter(QByteArrayView(key.toUtf8()));
687 }
688 [[deprecated("use QByteArrayView as argument")]] [[nodiscard]] inline bool hasParameter(QLatin1StringView key) const
689 {
690 return hasParameter(QByteArrayView(key));
691 }
692 // overload resolution helper, remove once the above deprecated overloads are removed
693 template <std::size_t N>
694 [[nodiscard]] inline bool hasParameter(const char (&key)[N]) const {
695 return hasParameter(QByteArrayView(key, N));
696 }
697
698 /**
699 Sets the parameter @p key to @p value.
700 @param key The parameter name.
701 @param value The new value for @p key.
702 */
703 void setParameter(const QByteArray &key, const QString &value);
704 [[deprecated("use a QByteArray[Literal] key")]] inline void setParameter(const QString &key, const QString &value)
705 {
706 return setParameter(key.toUtf8(), value);
707 }
708
709protected:
710 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
711
712private:
713 Q_DECLARE_PRIVATE(Parametrized)
714};
715
716} // namespace Generics
717
718//
719//
720// INCOMPATIBLE, GSTRUCTURED-BASED FIELDS:
721//
722//
723
724class ReturnPathPrivate;
725
726/**
727 Represents the Return-Path header field.
728
729 @see RFC 2822, section 3.6.7
730*/
731class KMIME_EXPORT ReturnPath : public Generics::Address
732{
733 //@cond PRIVATE
734 kmime_mk_trivial_ctor_with_name(ReturnPath)
735 //@endcond
736public:
737 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
738 [[nodiscard]] bool isEmpty() const override;
739
740protected:
741 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
742
743private:
744 Q_DECLARE_PRIVATE(ReturnPath)
745};
746
747// Address et al.:
748
749// rfc(2)822 headers:
750/**
751 Represent a "From" header.
752
753 @see RFC 2822, section 3.6.2.
754*/
755class KMIME_EXPORT From : public Generics::MailboxList
756{
757 kmime_mk_trivial_ctor_with_name(From)
758};
759
760/**
761 Represents a "Sender" header.
762
763 @see RFC 2822, section 3.6.2.
764*/
765class KMIME_EXPORT Sender : public Generics::SingleMailbox
766{
767 kmime_mk_trivial_ctor_with_name(Sender)
768};
769
770/**
771 Represents a "To" header.
772
773 @see RFC 2822, section 3.6.3.
774*/
775class KMIME_EXPORT To : public Generics::AddressList
776{
777 kmime_mk_trivial_ctor_with_name(To)
778};
779
780/**
781 Represents a "Cc" header.
782
783 @see RFC 2822, section 3.6.3.
784*/
785class KMIME_EXPORT Cc : public Generics::AddressList
786{
787 kmime_mk_trivial_ctor_with_name(Cc)
788};
789
790/**
791 Represents a "Bcc" header.
792
793 @see RFC 2822, section 3.6.3.
794*/
795class KMIME_EXPORT Bcc : public Generics::AddressList
796{
797 kmime_mk_trivial_ctor_with_name(Bcc)
798};
799
800/**
801 Represents a "ReplyTo" header.
802
803 @see RFC 2822, section 3.6.2.
804*/
805class KMIME_EXPORT ReplyTo : public Generics::AddressList
806{
807 kmime_mk_trivial_ctor_with_name(ReplyTo)
808};
809
810class MailCopiesToPrivate;
811
812/**
813 Represents a "Mail-Copies-To" header.
814
815 @see http://www.newsreaders.com/misc/mail-copies-to.html
816*/
817class KMIME_EXPORT MailCopiesTo : public Generics::AddressList
818{
819 //@cond PRIVATE
820 kmime_mk_trivial_ctor_with_name(MailCopiesTo)
821 //@endcond
822public:
823 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
824 [[nodiscard]] QString asUnicodeString() const override;
825
826 [[nodiscard]] bool isEmpty() const override;
827
828 /**
829 Returns true if a mail copy was explicitly requested.
830 */
831 [[nodiscard]] bool alwaysCopy() const;
832
833 /**
834 Sets the header to "poster".
835 */
836 void setAlwaysCopy();
837
838 /**
839 Returns true if a mail copy was explicitly denied.
840 */
841 [[nodiscard]] bool neverCopy() const;
842
843 /**
844 Sets the header to "never".
845 */
846 void setNeverCopy();
847
848protected:
849 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
850
851private:
852 Q_DECLARE_PRIVATE(MailCopiesTo)
853};
854
855class ContentTransferEncodingPrivate;
856
857/**
858 Represents a "Content-Transfer-Encoding" header.
859
860 @see RFC 2045, section 6.
861*/
862class KMIME_EXPORT ContentTransferEncoding : public Generics::Token
863{
864 //@cond PRIVATE
865 kmime_mk_trivial_ctor_with_name(ContentTransferEncoding)
866 //@endcond
867public:
868 [[nodiscard]] bool isEmpty() const override;
869 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
870
871 /**
872 Returns the encoding specified in this header.
873 */
874 [[nodiscard]] contentEncoding encoding() const;
875
876 /**
877 Sets the encoding to @p e.
878 */
879 void setEncoding(contentEncoding e);
880
881protected:
882 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
883
884private:
885 Q_DECLARE_PRIVATE(ContentTransferEncoding)
886};
887
888/**
889 Represents a "Keywords" header.
890
891 @see RFC 2822, section 3.6.5.
892*/
893class KMIME_EXPORT Keywords : public Generics::PhraseList
894{
895 kmime_mk_trivial_ctor_with_name(Keywords)
896};
897
898// DotAtom:
899
900/**
901 Represents a "MIME-Version" header.
902
903 @see RFC 2045, section 4.
904*/
905class KMIME_EXPORT MIMEVersion : public Generics::DotAtom
906{
907 kmime_mk_trivial_ctor_with_name(MIMEVersion)
908};
909
910// Ident:
911
912/**
913 Represents a "Message-ID" header.
914
915 @see RFC 2822, section 3.6.4.
916*/
917class KMIME_EXPORT MessageID : public Generics::SingleIdent
918{
919 //@cond PRIVATE
920 kmime_mk_trivial_ctor_with_name(MessageID)
921 //@endcond
922public:
923 /**
924 Generate a message identifier.
925 @param fqdn A fully qualified domain name.
926 */
927 void generate(const QByteArray &fqdn);
928};
929
930class ContentIDPrivate;
931
932/**
933 Represents a "Content-ID" header.
934*/
935class KMIME_EXPORT ContentID : public Generics::SingleIdent
936{
937 //@cond PRIVATE
938 kmime_mk_trivial_ctor_with_name(ContentID)
939 kmime_mk_dptr_ctor(ContentID)
940 //@endcond
941
942protected:
943 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
944private:
945 Q_DECLARE_PRIVATE(ContentID)
946};
947
948/**
949 Represents a "Supersedes" header.
950*/
951class KMIME_EXPORT Supersedes : public Generics::SingleIdent
952{
953 kmime_mk_trivial_ctor_with_name(Supersedes)
954};
955
956/**
957 Represents a "In-Reply-To" header.
958
959 @see RFC 2822, section 3.6.4.
960*/
961class KMIME_EXPORT InReplyTo : public Generics::Ident
962{
963 kmime_mk_trivial_ctor_with_name(InReplyTo)
964};
965
966/**
967 Represents a "References" header.
968
969 @see RFC 2822, section 3.6.4.
970*/
971class KMIME_EXPORT References : public Generics::Ident
972{
973 kmime_mk_trivial_ctor_with_name(References)
974};
975
976class ContentTypePrivate;
977
978/**
979 Represents a "Content-Type" header.
980
981 @see RFC 2045, section 5.
982*/
983class KMIME_EXPORT ContentType : public Generics::Parametrized
984{
985 //@cond PRIVATE
986 kmime_mk_trivial_ctor_with_name(ContentType)
987 //@endcond
988public:
989 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
990 [[nodiscard]] bool isEmpty() const override;
991
992 /**
993 Returns the mimetype.
994 */
995 [[nodiscard]] QByteArray mimeType() const;
996
997 /**
998 Returns the media type (first part of the mimetype).
999 */
1000
1001 [[nodiscard]] QByteArray mediaType() const;
1002
1003 /**
1004 Returns the mime sub-type (second part of the mimetype).
1005 */
1006 [[nodiscard]] QByteArray subType() const;
1007
1008 /**
1009 Sets the mimetype.
1010 @param mimeType The new mimetype.
1011 */
1012 void setMimeType(const QByteArray &mimeType);
1013
1014 /**
1015 Tests if the media type equals @p mediatype.
1016 */
1017 [[nodiscard]] bool isMediatype(const char *mediatype) const;
1018
1019 /**
1020 Tests if the mime sub-type equals @p subtype.
1021 */
1022 [[nodiscard]] bool isSubtype(const char *subtype) const;
1023
1024 /**
1025 Tests if the mime type is @p mimeType.
1026 */
1027 [[nodiscard]] bool isMimeType(const char *mimeType) const;
1028
1029 /**
1030 Returns true if the associated MIME entity is a text.
1031 */
1032 [[nodiscard]] bool isText() const;
1033
1034 /**
1035 Returns true if the associated MIME entity is a plain text.
1036 */
1037 [[nodiscard]] bool isPlainText() const;
1038
1039 /**
1040 Returns true if the associated MIME entity is a HTML file.
1041 */
1042 [[nodiscard]] bool isHTMLText() const;
1043
1044 /**
1045 Returns true if the associated MIME entity is an image.
1046 */
1047 [[nodiscard]] bool isImage() const;
1048
1049 /**
1050 Returns true if the associated MIME entity is a multipart container.
1051 */
1052 [[nodiscard]] bool isMultipart() const;
1053
1054 /**
1055 Returns true if the associated MIME entity contains partial data.
1056 @see partialNumber(), partialCount()
1057 */
1058 [[nodiscard]] bool isPartial() const;
1059
1060 /**
1061 Returns the charset for the associated MIME entity.
1062 */
1063 [[nodiscard]] QByteArray charset() const;
1064
1065 /**
1066 Sets the charset.
1067 */
1068 void setCharset(const QByteArray &s);
1069
1070 /**
1071 Returns the boundary (for multipart containers).
1072 */
1073 [[nodiscard]] QByteArray boundary() const;
1074
1075 /**
1076 Sets the multipart container boundary.
1077 */
1078 void setBoundary(const QByteArray &s);
1079
1080 /**
1081 Returns the name of the associated MIME entity.
1082 */
1083 [[nodiscard]] QString name() const;
1084
1085 /**
1086 Sets the name to @p s.
1087 */
1088 void setName(const QString &s);
1089 [[deprecated("call setRFC2047Charset for the second argument if different from UTF-8, otherwise remove second argument")]]
1090 inline void setName(const QString &s, const QByteArray &cs)
1091 {
1092 setRFC2047Charset(cs);
1093 setName(s);
1094 }
1095
1096 /**
1097 Returns the identifier of the associated MIME entity.
1098 */
1099 [[nodiscard]] QByteArray id() const;
1100
1101 /**
1102 Sets the identifier.
1103 */
1104 void setId(const QByteArray &s);
1105
1106 /**
1107 Returns the position of this part in a multi-part set.
1108 @see isPartial(), partialCount()
1109 */
1110 [[nodiscard]] int partialNumber() const;
1111
1112 /**
1113 Returns the total number of parts in a multi-part set.
1114 @see isPartial(), partialNumber()
1115 */
1116 [[nodiscard]] int partialCount() const;
1117
1118 /**
1119 Sets parameters of a partial MIME entity.
1120 @param total The total number of entities in the multi-part set.
1121 @param number The number of this entity in a multi-part set.
1122 */
1123 void setPartialParams(int total, int number);
1124
1125protected:
1126 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1127
1128private:
1129 Q_DECLARE_PRIVATE(ContentType)
1130};
1131
1132class ContentDispositionPrivate;
1133
1134/**
1135 Represents a "Content-Disposition" header.
1136
1137 @see RFC 2183
1138*/
1140{
1141 //@cond PRIVATE
1142 kmime_mk_trivial_ctor_with_name(ContentDisposition)
1143 //@endcond
1144public:
1145 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
1146 [[nodiscard]] bool isEmpty() const override;
1147
1148 /**
1149 Returns the content disposition.
1150 */
1151 [[nodiscard]] contentDisposition disposition() const;
1152
1153 /**
1154 Sets the content disposition.
1155 @param disp The new content disposition.
1156 */
1157 void setDisposition(contentDisposition disp);
1158
1159 /**
1160 Returns the suggested filename for the associated MIME part.
1161 This is just a convenience function, it is equivalent to calling
1162 parameter( "filename" );
1163 */
1164 [[nodiscard]] QString filename() const;
1165
1166 /**
1167 Sets the suggested filename for the associated MIME part.
1168 This is just a convenience function, it is equivalent to calling
1169 setParameter( "filename", filename );
1170 @param filename The filename.
1171 */
1172 void setFilename(const QString &filename);
1173
1174protected:
1175 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1176
1177private:
1178 Q_DECLARE_PRIVATE(ContentDisposition)
1179};
1180
1181//
1182//
1183// COMPATIBLE GUNSTRUCTURED-BASED FIELDS:
1184//
1185//
1186
1187class GenericPrivate;
1188
1189/**
1190 Represents an arbitrary header, that can contain any header-field.
1191 Adds a type over Unstructured.
1192 @see Unstructured
1193*/
1194class KMIME_EXPORT Generic : public Generics::Unstructured
1195{
1196public:
1197 Generic();
1198 Generic(const char *t, qsizetype len = -1);
1199 ~Generic() override;
1200
1201 [[nodiscard]] bool isEmpty() const override;
1202
1203 [[nodiscard]] const char *type() const override;
1204
1205 void setType(const char *type, qsizetype len = -1);
1206
1207private:
1208 Q_DECLARE_PRIVATE(Generic)
1209};
1210
1211/**
1212 Represents a "Subject" header.
1213
1214 @see RFC 2822, section 3.6.5.
1215*/
1216class KMIME_EXPORT Subject : public Generics::Unstructured
1217{
1218 //@cond PRIVATE
1219 kmime_mk_trivial_ctor_with_name(Subject)
1220 //@endcond
1221};
1222
1223/**
1224 Represents a "Organization" header.
1225*/
1226class KMIME_EXPORT Organization : public Generics::Unstructured
1227{
1228 kmime_mk_trivial_ctor_with_name(Organization)
1229};
1230
1231/**
1232 Represents a "Content-Description" header.
1233*/
1235{
1236 kmime_mk_trivial_ctor_with_name(ContentDescription)
1237};
1238
1239/**
1240 Represents a "Content-Location" header.
1241 @since 4.2
1242*/
1243class KMIME_EXPORT ContentLocation : public Generics::Unstructured
1244{
1245 kmime_mk_trivial_ctor_with_name(ContentLocation)
1246};
1247
1248class ControlPrivate;
1249
1250/**
1251 Represents a "Control" header.
1252
1253 @see RFC 1036, section 3.
1254*/
1255class KMIME_EXPORT Control : public Generics::Structured
1256{
1257 //@cond PRIVATE
1258 kmime_mk_trivial_ctor_with_name(Control)
1259 //@endcond
1260public:
1261 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
1262 [[nodiscard]] bool isEmpty() const override;
1263
1264 /**
1265 Returns the control message type.
1266 */
1267 [[nodiscard]] QByteArray controlType() const;
1268
1269 /**
1270 Returns the control message parameter.
1271 */
1272 [[nodiscard]] QByteArray parameter() const;
1273
1274 /**
1275 Returns true if this is a cancel control message.
1276 @see RFC 1036, section 3.1.
1277 */
1278 [[nodiscard]] bool isCancel() const;
1279
1280 /**
1281 Changes this header into a cancel control message for the given message-id.
1282 @param msgid The message-id of the article that should be canceled.
1283 */
1284 void setCancel(const QByteArray &msgid);
1285
1286protected:
1287 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1288
1289private:
1290 Q_DECLARE_PRIVATE(Control)
1291};
1292
1293class DatePrivate;
1294
1295/**
1296 Represents a "Date" header.
1297
1298 @see RFC 2822, section 3.3.
1299*/
1300class KMIME_EXPORT Date : public Generics::Structured
1301{
1302 //@cond PRIVATE
1303 kmime_mk_trivial_ctor_with_name(Date)
1304 //@endcond
1305public:
1306 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
1307 [[nodiscard]] bool isEmpty() const override;
1308
1309 /**
1310 Returns the date contained in this header.
1311 */
1312 [[nodiscard]] QDateTime dateTime() const;
1313
1314 /**
1315 Sets the date.
1316 */
1317 void setDateTime(const QDateTime &dt);
1318
1319protected:
1320 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1321
1322private:
1323 Q_DECLARE_PRIVATE(Date)
1324};
1325
1326class NewsgroupsPrivate;
1327
1328/**
1329 Represents a "Newsgroups" header.
1330
1331 @see RFC 1036, section 2.1.3.
1332*/
1333class KMIME_EXPORT Newsgroups : public Generics::Structured
1334{
1335 //@cond PRIVATE
1336 kmime_mk_trivial_ctor_with_name(Newsgroups)
1337 //@endcond
1338public:
1339 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
1340 void fromUnicodeString(const QString &s) override;
1341 using Base::fromUnicodeString;
1342 [[nodiscard]] QString asUnicodeString() const override;
1343 [[nodiscard]] bool isEmpty() const override;
1344
1345 /**
1346 Returns the list of newsgroups.
1347 */
1348 [[nodiscard]] QList<QByteArray> groups() const;
1349
1350 /**
1351 Sets the newsgroup list.
1352 */
1353 void setGroups(const QList<QByteArray> &groups);
1354
1355 /**
1356 Returns true if this message has been cross-posted, i.e. if it has been
1357 posted to multiple groups.
1358 */
1359 [[nodiscard]] bool isCrossposted() const;
1360
1361protected:
1362 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1363
1364private:
1365 Q_DECLARE_PRIVATE(Newsgroups)
1366};
1367
1368/**
1369 Represents a "Followup-To" header.
1370
1371 @see RFC 1036, section 2.2.3.
1372*/
1373class KMIME_EXPORT FollowUpTo : public Newsgroups
1374{
1375 //@cond PRIVATE
1376 kmime_mk_trivial_ctor_with_name(FollowUpTo)
1377 //@endcond
1378};
1379
1380class LinesPrivate;
1381
1382/**
1383 Represents a "Lines" header.
1384
1385 @see RFC 1036, section 2.2.12.
1386*/
1387class KMIME_EXPORT Lines : public Generics::Structured
1388{
1389 //@cond PRIVATE
1390 kmime_mk_trivial_ctor_with_name(Lines)
1391 //@endcond
1392public:
1393 [[nodiscard]] QByteArray as7BitString(bool withHeaderType = true) const override;
1394 [[nodiscard]] QString asUnicodeString() const override;
1395 [[nodiscard]] bool isEmpty() const override;
1396
1397 /**
1398 Returns the number of lines, undefined if isEmpty() returns true.
1399 */
1400 [[nodiscard]] int numberOfLines() const;
1401
1402 /**
1403 Sets the number of lines to @p lines.
1404 */
1405 void setNumberOfLines(int lines);
1406
1407protected:
1408 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1409
1410private:
1411 Q_DECLARE_PRIVATE(Lines)
1412};
1413
1414/**
1415 Represents a "User-Agent" header.
1416*/
1417class KMIME_EXPORT UserAgent : public Generics::Unstructured
1418{
1419 kmime_mk_trivial_ctor_with_name(UserAgent)
1420};
1421
1422/** Creates a header based on @param type. If @param type is a known header type,
1423 * the right object type will be created, otherwise a null pointer is returned. */
1424[[nodiscard]] KMIME_EXPORT Base *createHeader(QByteArrayView type);
1425
1426} //namespace Headers
1427
1428} //namespace KMime
1429
1430// undefine code generation macros again
1431#undef kmime_mk_trivial_ctor
1432#undef kmime_mk_dptr_ctor
1433#undef kmime_mk_trivial_ctor_with_name
1434
1435Q_DECLARE_METATYPE(KMime::Headers::To*)
1436Q_DECLARE_METATYPE(KMime::Headers::Cc*)
1437Q_DECLARE_METATYPE(KMime::Headers::Bcc*)
1438
Baseclass of all header-classes.
Definition headers.h:97
virtual QByteArray as7BitString(bool withHeaderType=true) const =0
Returns the encoded header.
QList< KMime::Headers::Base * > List
A vector of headers.
Definition headers.h:102
virtual void from7BitString(QByteArrayView s)=0
Parses the given string.
virtual void fromUnicodeString(const QString &s)=0
Parses the given Unicode representation of the header content.
virtual QString asUnicodeString() const =0
Returns the decoded content of the header without the header-type.
virtual bool isEmpty() const =0
Checks if this header contains any data.
Represents a "Bcc" header.
Definition headers.h:796
Represents a "Cc" header.
Definition headers.h:786
Represents a "Content-Description" header.
Definition headers.h:1235
Represents a "Content-Disposition" header.
Definition headers.h:1140
Represents a "Content-ID" header.
Definition headers.h:936
Represents a "Content-Location" header.
Definition headers.h:1244
Represents a "Content-Transfer-Encoding" header.
Definition headers.h:863
Represents a "Content-Type" header.
Definition headers.h:984
Represents a "Control" header.
Definition headers.h:1256
Represents a "Date" header.
Definition headers.h:1301
Represents a "Followup-To" header.
Definition headers.h:1374
Represent a "From" header.
Definition headers.h:756
Represents an arbitrary header, that can contain any header-field.
Definition headers.h:1195
Base class for headers that deal with (possibly multiple) addresses, allowing groups.
Definition headers.h:422
Base class for all address related headers.
Definition headers.h:305
Base class for headers containing a dot atom.
Definition headers.h:626
Base class for headers which deal with a list of msg-id's.
Definition headers.h:493
Base class for headers that deal with (possibly multiple) addresses, but don't allow groups.
Definition headers.h:326
Base class for headers containing a parameter list such as "Content-Type".
Definition headers.h:648
Base class for headers containing a list of phrases.
Definition headers.h:599
Base class for headers which deal with a single msg-id.
Definition headers.h:536
Base class for headers that deal with exactly one mailbox (e.g.
Definition headers.h:398
Base class for structured header fields.
Definition headers.h:269
virtual bool parse(const char *&scursor, const char *const send, bool isCRLF=false)=0
This method parses the raw header and needs to be implemented in every sub-class.
Base class for headers which deal with a single atom.
Definition headers.h:567
Abstract base class for unstructured header fields (e.g.
Definition headers.h:215
Represents a "In-Reply-To" header.
Definition headers.h:962
Represents a "Keywords" header.
Definition headers.h:894
Represents a "Lines" header.
Definition headers.h:1388
Represents a "MIME-Version" header.
Definition headers.h:906
Represents a "Mail-Copies-To" header.
Definition headers.h:818
Represents a "Message-ID" header.
Definition headers.h:918
Represents a "Newsgroups" header.
Definition headers.h:1334
Represents a "Organization" header.
Definition headers.h:1227
Represents a "References" header.
Definition headers.h:972
Represents a "ReplyTo" header.
Definition headers.h:806
Represents the Return-Path header field.
Definition headers.h:732
Represents a "Sender" header.
Definition headers.h:766
Represents a "Subject" header.
Definition headers.h:1217
Represents a "Supersedes" header.
Definition headers.h:952
Represents a "To" header.
Definition headers.h:776
Represents a "User-Agent" header.
Definition headers.h:1418
Represents an (email address, display name) pair according RFC 2822, section 3.4.
Definition types.h:38
Base * createHeader(QByteArrayView type)
Creates a header based on.
Definition headers.cpp:1983
contentEncoding
Various possible values for the "Content-Transfer-Encoding" header.
Definition headers.h:52
@ CE8Bit
8bit
Definition headers.h:54
@ CEbase64
base64
Definition headers.h:56
@ CE7Bit
7bit
Definition headers.h:53
@ CEbinary
binary
Definition headers.h:58
@ CEquPr
quoted-printable
Definition headers.h:55
@ CEuuenc
uuencode
Definition headers.h:57
contentDisposition
Various possible values for the "Content-Disposition" header.
Definition headers.h:64
@ CDInvalid
Default, invalid value.
Definition headers.h:65
@ CDattachment
attachment
Definition headers.h:67
@ CDinline
inline
Definition headers.h:66
@ CDparallel
parallel (invalid, do not use)
Definition headers.h:68
QByteArray toUtf8() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:30:05 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.