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