kmime_headers.h

Go to the documentation of this file.

/*  -*- c++ -*-
    kmime_headers.h

    KMime, the KDE Internet mail/usenet news message library.
    Copyright (c) 2001-2002 the KMime authors.
    See file AUTHORS for details
    Copyright (c) 2006 Volker Krause <vkrause@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/
#ifndef __KMIME_HEADERS_H__
#define __KMIME_HEADERS_H__

#include "kmime_export.h"
#include "kmime_header_parsing.h"

#include <QtCore/QString>
#include <QtCore/QStringList>
#include <QtCore/QRegExp>
#include <QtCore/QDateTime>
#include <QtCore/QMap>
#include <QtCore/QList>
#include <QtCore/QByteArray>

#include <kdatetime.h>

namespace KMime {

class Content;

namespace Headers {

class BasePrivate;

enum contentCategory {
  CCsingle,
  CCcontainer,
  CCmixedPart,
  CCalternativePart
};

enum contentEncoding {
  CE7Bit,              
  CE8Bit,              
  CEquPr,              
  CEbase64,            
  CEuuenc,             
  CEbinary             
};

enum contentDisposition {
  CDInvalid,           
  CDinline,            
  CDattachment,        
  CDparallel           
};

//often used charset
// TODO: get rid of this!
static const QByteArray Latin1( "ISO-8859-1" );

//@cond PRIVATE
// internal macro to generate default constructors
#define kmime_mk_trivial_ctor( subclass )                               \
  public:                                                               \
    explicit subclass( Content *parent = 0 );                           \
    subclass( Content *parent, const QByteArray &s );                   \
    subclass( Content *parent, const QString &s, const QByteArray &charset ); \
    ~subclass();

#define kmime_mk_dptr_ctor( subclass ) \
  protected: \
    explicit subclass( subclass##Private *d, KMime::Content *parent = 0 );

#define kmime_mk_trivial_ctor_with_name( subclass )     \
  kmime_mk_trivial_ctor( subclass )                     \
    const char *type() const;                           \
    static const char *staticType();
//@endcond

//
//
// HEADER'S BASE CLASS. DEFINES THE COMMON INTERFACE
//
//

class KMIME_EXPORT Base
{
  public:
    typedef QList<KMime::Headers::Base*> List;

    explicit Base( KMime::Content *parent = 0 );

    virtual ~Base();

    KMime::Content *parent() const;

    void setParent( KMime::Content *parent );

    virtual void from7BitString( const QByteArray &s ) = 0;

    virtual QByteArray as7BitString( bool withHeaderType = true ) const = 0;

    QByteArray rfc2047Charset() const;

    void setRFC2047Charset( const QByteArray &cs );

    QByteArray defaultCharset() const;

    bool forceDefaultCharset() const;

    virtual void fromUnicodeString( const QString &s, const QByteArray &b ) = 0;

    virtual QString asUnicodeString() const = 0;

    virtual void clear() = 0;

    virtual bool isEmpty() const = 0;

    virtual const char *type() const;

    bool is( const char *t ) const;

    bool isMimeHeader() const;

    bool isXHeader() const;

  protected:
    QByteArray typeIntro() const;

    //@cond PRIVATE
    BasePrivate *d_ptr;
    kmime_mk_dptr_ctor( Base )
    //@endcond

  private:
    Q_DECLARE_PRIVATE( Base )
    Q_DISABLE_COPY( Base )
};

//
//
// GENERIC BASE CLASSES FOR DIFFERENT TYPES OF FIELDS
//
//

namespace Generics {

class UnstructuredPrivate;

// known issues:
// - uses old decodeRFC2047String function, instead of our own...

class KMIME_EXPORT Unstructured : public Base
{
  //@cond PRIVATE
  kmime_mk_dptr_ctor( Unstructured )
  //@endcond
  public:
    explicit Unstructured( Content *p = 0 );
    Unstructured( Content *p, const QByteArray &s );
    Unstructured( Content *p, const QString &s, const QByteArray &cs );
    ~Unstructured();

    virtual void from7BitString( const QByteArray &s );
    virtual QByteArray as7BitString( bool withHeaderType=true ) const;

    virtual void fromUnicodeString( const QString &s,
                                  const QByteArray &b );
    virtual QString asUnicodeString() const;

    virtual void clear();

    virtual bool isEmpty() const;

  private:
    Q_DECLARE_PRIVATE( Unstructured )
};


class StructuredPrivate;

class KMIME_EXPORT Structured : public Base
{
  public:
    explicit Structured( Content *p = 0 );
    Structured( Content *p, const QByteArray &s );
    Structured( Content *p, const QString &s, const QByteArray &cs );
    ~Structured();

    virtual void from7BitString( const QByteArray &s );
    virtual QString asUnicodeString() const;
    virtual void fromUnicodeString( const QString &s, const QByteArray &b );

  protected:
    virtual bool parse( const char* &scursor, const char *const send,
                        bool isCRLF = false ) = 0;

    //@cond PRIVATE
    kmime_mk_dptr_ctor( Structured )
    //@endcond

  private:
    Q_DECLARE_PRIVATE( Structured )
};

class AddressPrivate;

class KMIME_EXPORT Address : public Structured
{
  public:
    explicit Address( Content *p = 0 );
    Address( Content *p, const QByteArray &s );
    Address( Content *p, const QString &s, const QByteArray &cs );
    ~Address();
  protected:
    //@cond PRIVATE
    kmime_mk_dptr_ctor( Address )
    //@endcond
  private:
    Q_DECLARE_PRIVATE( Address )
};

class MailboxListPrivate;

class KMIME_EXPORT MailboxList : public Address
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( MailboxList )
  kmime_mk_dptr_ctor( MailboxList )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void fromUnicodeString( const QString &s, const QByteArray &b );
    virtual QString asUnicodeString() const;

    virtual void clear();
    virtual bool isEmpty() const;

    void addAddress( const Types::Mailbox &mbox );

    void addAddress( const QByteArray &address,
                     const QString &displayName = QString() );

    QList<QByteArray> addresses() const;

    QStringList displayNames() const;

    QStringList prettyAddresses() const;

    Types::Mailbox::List mailboxes() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( MailboxList )
};

class SingleMailboxPrivate;

class KMIME_EXPORT SingleMailbox : public MailboxList
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( SingleMailbox )
  //@endcond
  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );
  private:
    Q_DECLARE_PRIVATE( SingleMailbox )
};

class AddressListPrivate;

class KMIME_EXPORT AddressList : public Address
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( AddressList )
  kmime_mk_dptr_ctor( AddressList )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void fromUnicodeString( const QString &s, const QByteArray &b );
    virtual QString asUnicodeString() const;

    virtual void clear();
    virtual bool isEmpty() const;

    void addAddress( const Types::Mailbox &mbox );

    void addAddress( const QByteArray &address, const QString &displayName = QString() );

    QList<QByteArray> addresses() const;

    QStringList displayNames() const;

    QStringList prettyAddresses() const;

    Types::Mailbox::List mailboxes() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( AddressList )
};

class IdentPrivate;

class KMIME_EXPORT Ident : public Address
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( Ident )
  kmime_mk_dptr_ctor( Ident )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void clear();
    virtual bool isEmpty() const;

    QList<QByteArray> identifiers() const;

    void appendIdentifier( const QByteArray &id );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( Ident )
};

class SingleIdentPrivate;

class KMIME_EXPORT SingleIdent : public Ident
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( SingleIdent )
  kmime_mk_dptr_ctor( SingleIdent )
  //@endcond
  public:
    QByteArray identifier() const;

    void setIdentifier( const QByteArray &id );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( SingleIdent )
};

class TokenPrivate;

class KMIME_EXPORT Token : public Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( Token )
  kmime_mk_dptr_ctor( Token )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void clear();
    virtual bool isEmpty() const;

    QByteArray token() const;

    void setToken( const QByteArray &t );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( Token )
};

class PhraseListPrivate;

class KMIME_EXPORT PhraseList : public Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( PhraseList )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual QString asUnicodeString() const;
    virtual void clear();
    virtual bool isEmpty() const;

    QStringList phrases() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( PhraseList )
};

class DotAtomPrivate;

class KMIME_EXPORT DotAtom : public Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( DotAtom )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual QString asUnicodeString() const;
    virtual void clear();
    virtual bool isEmpty() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( DotAtom )
};

class ParametrizedPrivate;

class KMIME_EXPORT Parametrized : public Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor( Parametrized )
  kmime_mk_dptr_ctor( Parametrized )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;

    virtual bool isEmpty() const;
    virtual void clear();

    //FIXME: Shouldn't the parameter keys be QByteArray and not QStrings? Only the values can be
    //       non-ascii!

    QString parameter( const QString &key ) const;

    bool hasParameter( const QString &key ) const;

    void setParameter( const QString &key, const QString &value );

  protected:
    virtual bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( Parametrized )
};

} // namespace Generics

//
//
// INCOMPATIBLE, GSTRUCTURED-BASED FIELDS:
//
//

class ReturnPathPrivate;

class KMIME_EXPORT ReturnPath : public Generics::Address
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( ReturnPath )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void clear();
    virtual bool isEmpty() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( ReturnPath )
};

// Address et al.:

// rfc(2)822 headers:
class KMIME_EXPORT From : public Generics::MailboxList
{
  kmime_mk_trivial_ctor_with_name( From )
};

class KMIME_EXPORT Sender : public Generics::SingleMailbox
{
  kmime_mk_trivial_ctor_with_name( Sender )
};

class KMIME_EXPORT To : public Generics::AddressList
{
  kmime_mk_trivial_ctor_with_name( To )
};

class KMIME_EXPORT Cc : public Generics::AddressList
{
  kmime_mk_trivial_ctor_with_name( Cc )
};

class KMIME_EXPORT Bcc : public Generics::AddressList
{
  kmime_mk_trivial_ctor_with_name( Bcc )
};

class KMIME_EXPORT ReplyTo : public Generics::AddressList
{
  kmime_mk_trivial_ctor_with_name( ReplyTo )
};


class MailCopiesToPrivate;

class KMIME_EXPORT MailCopiesTo : public Generics::AddressList
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( MailCopiesTo )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual QString asUnicodeString() const;

    virtual void clear();
    virtual bool isEmpty() const;

    bool alwaysCopy() const;

    void setAlwaysCopy();

    bool neverCopy() const;

    void setNeverCopy();

  protected:
    virtual bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( MailCopiesTo )
};

class ContentTransferEncodingPrivate;

class KMIME_EXPORT ContentTransferEncoding : public Generics::Token
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( ContentTransferEncoding )
  //@endcond
  public:
    virtual void clear();

    contentEncoding encoding() const;

    void setEncoding( contentEncoding e );

    // KDE5: rename to isDecoded().
    bool decoded() const;

    void setDecoded( bool decoded = true );

    bool needToEncode() const;

  protected:
    virtual bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( ContentTransferEncoding )
};

class KMIME_EXPORT Keywords : public Generics::PhraseList
{
  kmime_mk_trivial_ctor_with_name( Keywords )
};

// DotAtom:

class KMIME_EXPORT MIMEVersion : public Generics::DotAtom
{
  kmime_mk_trivial_ctor_with_name( MIMEVersion )
};

// Ident:

class KMIME_EXPORT MessageID : public Generics::SingleIdent
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( MessageID )
  //@endcond
  public:
    void generate( const QByteArray &fqdn );
};

class ContentIDPrivate;

class KMIME_EXPORT ContentID : public Generics::SingleIdent
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( ContentID )
  kmime_mk_dptr_ctor( ContentID )
  //@endcond

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );
  private:
    Q_DECLARE_PRIVATE( ContentID )
};

class KMIME_EXPORT Supersedes : public Generics::SingleIdent
{
  kmime_mk_trivial_ctor_with_name( Supersedes )
};

class KMIME_EXPORT InReplyTo : public Generics::Ident
{
  kmime_mk_trivial_ctor_with_name( InReplyTo )
};

class KMIME_EXPORT References : public Generics::Ident
{
  kmime_mk_trivial_ctor_with_name( References )
};


class ContentTypePrivate;

class KMIME_EXPORT ContentType : public Generics::Parametrized
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( ContentType )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void clear();
    virtual bool isEmpty() const;

    QByteArray mimeType() const;

    QByteArray mediaType() const;

    QByteArray subType() const;

    void setMimeType( const QByteArray &mimeType );

    bool isMediatype( const char *mediatype ) const;

    bool isSubtype( const char *subtype ) const;

    bool isText() const;

    bool isPlainText() const;

    bool isHTMLText() const;

    bool isImage() const;

    bool isMultipart() const;

    bool isPartial() const;

    QByteArray charset() const;

    void setCharset( const QByteArray &s );

    QByteArray boundary() const;

    void setBoundary( const QByteArray &s );

    QString name() const;

    void setName( const QString &s, const QByteArray &cs );

    QByteArray id() const;

    void setId( const QByteArray &s );

    int partialNumber() const;

    int partialCount() const;

    void setPartialParams( int total, int number );

    // TODO: document
    contentCategory category() const;

    void setCategory( contentCategory c );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( ContentType )
};

class ContentDispositionPrivate;

class KMIME_EXPORT ContentDisposition : public Generics::Parametrized
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( ContentDisposition )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual bool isEmpty() const;
    virtual void clear();

    contentDisposition disposition() const;

    void setDisposition( contentDisposition disp );

    QString filename() const;

    void setFilename( const QString &filename );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF=false );

  private:
    Q_DECLARE_PRIVATE( ContentDisposition )
};

//
//
// COMPATIBLE GUNSTRUCTURED-BASED FIELDS:
//
//


class GenericPrivate;

class KMIME_EXPORT Generic : public Generics::Unstructured
{
  public:
    Generic();
    Generic( const char *t );
    Generic( const char *t, Content *p );
    Generic( const char *t, Content *p, const QByteArray &s );
    Generic( const char *t, Content *p, const QString &s, const QByteArray &cs );
    ~Generic();

    virtual void clear();

    virtual bool isEmpty() const;

    virtual const char *type() const;

    void setType( const char *type );

  private:
    Q_DECLARE_PRIVATE( Generic )
};

class KMIME_EXPORT Subject : public Generics::Unstructured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( Subject )
  //@endcond
  public:
    bool isReply() const;
};

class KMIME_EXPORT Organization : public Generics::Unstructured
{
  kmime_mk_trivial_ctor_with_name( Organization )
};

class KMIME_EXPORT ContentDescription : public Generics::Unstructured
{
  kmime_mk_trivial_ctor_with_name( ContentDescription )
};

class KMIME_EXPORT ContentLocation : public Generics::Unstructured
{
  kmime_mk_trivial_ctor_with_name( ContentLocation )
};

class ControlPrivate;

class KMIME_EXPORT Control : public Generics::Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( Control )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void clear();
    virtual bool isEmpty() const;

    QByteArray controlType() const;

    QByteArray parameter() const;

    bool isCancel() const;

    void setCancel( const QByteArray &msgid );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF = false );

  private:
    Q_DECLARE_PRIVATE( Control )
};

class DatePrivate;

class KMIME_EXPORT Date : public Generics::Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( Date )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void clear();
    virtual bool isEmpty() const;

    KDateTime dateTime() const;

    void setDateTime( const KDateTime &dt );

    int ageInDays() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF = false );

  private:
    Q_DECLARE_PRIVATE( Date )
};


class NewsgroupsPrivate;

class KMIME_EXPORT Newsgroups : public Generics::Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( Newsgroups )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual void fromUnicodeString( const QString &s, const QByteArray &b );
    virtual QString asUnicodeString() const;
    virtual void clear();
    virtual bool isEmpty() const;

    QList<QByteArray> groups() const;

    void setGroups( const QList<QByteArray> &groups );

    bool isCrossposted() const;

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF = false );

  private:
    Q_DECLARE_PRIVATE( Newsgroups )
};

class KMIME_EXPORT FollowUpTo : public Newsgroups
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( FollowUpTo )
  //@endcond
};


class LinesPrivate;

class KMIME_EXPORT Lines : public Generics::Structured
{
  //@cond PRIVATE
  kmime_mk_trivial_ctor_with_name( Lines )
  //@endcond
  public:
    virtual QByteArray as7BitString( bool withHeaderType = true ) const;
    virtual QString asUnicodeString() const;
    virtual void clear();
    virtual bool isEmpty() const;

    int numberOfLines() const;

    void setNumberOfLines( int lines );

  protected:
    bool parse( const char* &scursor, const char *const send, bool isCRLF = false );

  private:
    Q_DECLARE_PRIVATE( Lines )
};

class KMIME_EXPORT UserAgent : public Generics::Unstructured
{
  kmime_mk_trivial_ctor_with_name( UserAgent )
};

KMIME_EXPORT Base *createHeader( const QByteArray& type );

}  //namespace Headers

}  //namespace KMime

// undefine code generation macros again
#undef kmime_mk_trivial_ctor
#undef kmime_mk_dptr_ctor
#undef kmime_mk_trivial_ctor_with_name

#endif // __KMIME_HEADERS_H__