KMime

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

KDE's Doxygen guidelines are available online.