messagecomposer/messagefactory.h

   1 /* -*- mode: C++; c-file-style: "gnu" -*-
   2   Copyright (C) 2010 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com
   3   Copyright (c) 2010 Leo Franchi <lfranchi@kde.org>
   4
   5   This program is free software; you can redistribute it and/or modify
   6   it under the terms of the GNU General Public License as published by
   7   the Free Software Foundation; either version 2 of the License, or
   8   (at your option) any later version.
   9
  10   This program is distributed in the hope that it will be useful,
  11   but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13   GNU General Public License for more details.
  14
  15   You should have received a copy of the GNU General Public License along
  16   with this program; if not, write to the Free Software Foundation, Inc.,
  17   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18 */
  19
  20 #ifndef MESSAGECOMPOSER_MESSAGE_FACTORY_H
  21 #define MESSAGECOMPOSER_MESSAGE_FACTORY_H
  22
  23 #include "messagecomposer_export.h"
  24
  25 #include <kmime/kmime_message.h>
  26 #include <kmime/kmime_mdn.h>
  27 #include <akonadi/entity.h>
  28 #include <akonadi/item.h>
  29
  30 #include "messagecore/messagestatus.h"
  31
  32 namespace KPIMIdentities {
  33   class IdentityManager;
  34 }
  35
  36 namespace MessageComposer {
  37   /**
  38    * Enumeration that defines the available reply "modes"
  39    */
  40   enum ReplyStrategy {
  41     ReplySmart = 0,    //< Attempt to automatically guess the best recipient for the reply
  42     ReplyAuthor,       //< Reply to the author of the message (possibly NOT the mailing list, if any)
  43     ReplyList,         //< Reply to the mailing list (and not the author of the message)
  44     ReplyAll,          //< Reply to author and all the recipients in CC
  45     ReplyNone          //< Don't set reply addresses: they will be set manually
  46   };
  47
  48   enum MDNAdvice {
  49     MDNIgnore,
  50     MDNSendDenied,
  51     MDNSend
  52   };
  53
  54 /**
  55  * Contains various factory methods for creating new messages such as replies, MDNs, forwards, etc.
  56  */
  57 class MESSAGECOMPOSER_EXPORT MessageFactory
  58 {
  59 public:
  60
  61   /// Small helper structure which encapsulates the KMime::Message created when creating a reply, and
  62   /// the reply mode
  63   struct MessageReply
  64   {
  65     KMime::Message::Ptr msg;  ///< The actual reply message
  66     bool replyAll;   ///< If true, the "reply all" template was used, otherwise the normal reply
  67                      ///  template
  68   };
  69
  70   explicit MessageFactory( const KMime::Message::Ptr& origMsg, Akonadi::Item::Id id );
  71   virtual ~MessageFactory();
  72
  73   /**
  74    * Create a new message that is a reply to this message, filling all
  75    * required header fields with the proper values. The returned message
  76    * is not stored in any folder. Marks this message as replied.
  77    *
  78    * @return the reply created, including the reply mode
  79    */
  80   MessageReply createReply();
  81
  82   /** Create a new message that is a forward of this message, filling all
  83     required header fields with the proper values. The returned message
  84     is not stored in any folder. Marks this message as forwarded. */
  85   KMime::Message::Ptr createForward();
  86
  87   /**
  88    * Create a forward from the given list of messages, attaching each
  89    *  message to be forwarded to the new forwarded message.
  90    *
  91    * If no list is passed, use the original message passed in the MessageFactory
  92    *  constructor.
  93    */
  94   QPair< KMime::Message::Ptr, QList< KMime::Content* > > createAttachedForward( QList<KMime::Message::Ptr> msgs = QList<KMime::Message::Ptr>() );
  95
  96   /** Create a new message that is a redirect to this message, filling all
  97     required header fields with the proper values. The returned message
  98     is not stored in any folder. Marks this message as replied.
  99     Redirects differ from forwards so they are forwarded to some other
 100     user, mail is not changed and the reply-to field is set to
 101     the email address of the original sender.
 102    */
 103   KMime::Message::Ptr createRedirect( const QString &toStr );
 104
 105   KMime::Message::Ptr createResend();
 106
 107
 108   /** Create a new message that is a delivery receipt of this message,
 109       filling required header fileds with the proper values. The
 110       returned message is not stored in any folder. */
 111   KMime::Message::Ptr createDeliveryReceipt();
 112
 113   /** Create a new message that is a MDN for this message, filling all
 114       required fields with proper values. The returned message is not
 115       stored in any folder.
 116
 117       @param a Use AutomaticAction for filtering and ManualAction for
 118                user-induced events.
 119       @param d See docs for KMime::MDN::DispositionType
 120       @param s See docs for KMime::MDN::SendingMode (in KMail, use MDNAdvideDialog to ask the user for this parameter)
 121       @param m See docs for KMime::MDN::DispositionModifier
 122
 123       @return The notification message or 0, if none should be sent.
 124    **/
 125   KMime::Message::Ptr createMDN( KMime::MDN::ActionMode a,
 126                                   KMime::MDN::DispositionType d,
 127                                   KMime::MDN::SendingMode s,
 128                                   int mdnQuoteOriginal = 0,
 129                                   QList<KMime::MDN::DispositionModifier> m=QList<KMime::MDN::DispositionModifier>() );
 130
 131   /**
 132    * Create a new forwarded MIME digest. If the user is trying to forward multiple messages
 133    *  at once all inline, they can choose to have them be compiled into a single digest
 134    *  message.
 135    *
 136    * This will return a header message and individual message parts to be set as
 137    *  attachments.
 138    *
 139    * @param msgs List of messages to be composed into a digest
 140    */
 141   QPair< KMime::Message::Ptr, KMime::Content* > createForwardDigestMIME( QList<KMime::Message::Ptr> msgs );
 142
 143   /**
 144    * Set the identity manager to be used when creating messages.
 145    * Required to be set before create* is called, otherwise the created messages
 146    *  might have the wrong identity data.
 147    */
 148   void setIdentityManager( KPIMIdentities::IdentityManager* ident );
 149
 150   /**
 151    * Required to link created messages properly with original message.
 152    */
 153   void setMessageItemID( Akonadi::Entity::Id id );
 154
 155   /**
 156    * Set the reply strategy to use. Default is ReplySmart.
 157    */
 158   void setReplyStrategy( MessageComposer::ReplyStrategy replyStrategy );
 159
 160   /**
 161    * Set the selection to be used to  base the reply on.
 162    */
 163   void setSelection( const QString& selection );
 164
 165   /**
 166    * Whether to quote the original message in the reply.
 167    *  Default is to quote.
 168    */
 169   void setQuote( bool quote );
 170
 171   /**
 172    * Decrypt a message if required during message processing. Default is true.
 173    */
 174   void setAllowDecryption( bool allowD );
 175
 176   /**
 177    * Set the template to be used when creating the reply. Default is to not
 178    *  use any template at all.
 179    */
 180   void setTemplate( const QString& templ );
 181
 182   /**
 183    * Set extra mailinglist addresses to send the created message to.
 184    *    Any mailing-list addresses specifed in the original message
 185    *    itself will be added by MessageFactory, so no need to add those manually.
 186    */
 187   void setMailingListAddresses( const QStringList& listAddresses );
 188
 189   /**
 190    *  Set the identity that is set for the folder in which the given message is.
 191    *   It is used as a fallback when finding the identity if it can't be found in
 192    *   any other way.
 193    *  Also used if putRepliesInSameFolder is set to true.
 194    */
 195   void setFolderIdentity( Akonadi::Item::Id folderIdentityId );
 196
 197   /**
 198    * Whether or not to put the reply to a message in the same folder as the message itself.
 199    *  If so, specify the folder id in which to put them. Default is -1, which means to not put
 200    *  replies in the same folder at all.
 201    */
 202   void putRepliesInSameFolder( Akonadi::Item::Id parentColId = -1 );
 203
 204   /**
 205    * When creating MDNs, the user needs to be asked for confirmation in specific
 206    *  cases according to RFC 2298.
 207    */
 208   static bool MDNRequested( KMime::Message::Ptr msg );
 209
 210   /**
 211    * If sending an MDN requires confirmation due to multiple addresses.
 212    *
 213    * RFC 2298: [ Confirmation from the user SHOULD be obtained (or no
 214    * MDN sent) ] if there is more than one distinct address in the
 215    * Disposition-Notification-To header.
 216    */
 217   static bool MDNConfirmMultipleRecipients( KMime::Message::Ptr msg );
 218
 219   /**
 220   *
 221   * If sending an MDN requires confirmation due to discrepancy between MDN
 222   *  header and Return-Path header.
 223   *
 224   * RFC 2298: MDNs SHOULD NOT be sent automatically if the address in
 225   * the Disposition-Notification-To header differs from the address
 226   * in the Return-Path header. [...] Confirmation from the user
 227   * SHOULD be obtained (or no MDN sent) if there is no Return-Path
 228   * header in the message [...]
 229   */
 230   static bool MDNReturnPathEmpty( KMime::Message::Ptr msg );
 231   static bool MDNReturnPathNotInRecieptTo( KMime::Message::Ptr msg );
 232
 233   /**
 234   * If the MDN headers contain options that KMail can't parse
 235   */
 236   static bool MDNMDNUnknownOption( KMime::Message::Ptr msg );
 237
 238   static void link( const KMime::Message::Ptr &msg, Akonadi::Item::Id id, const KPIM::MessageStatus& aStatus );
 239
 240 private:
 241     /** @return the UOID of the identity for this message.
 242       Searches the "x-kmail-identity" header and if that fails,
 243       searches with KPIMIdentities::IdentityManager::identityForAddress()
 244    **/
 245   uint identityUoid(const KMime::Message::Ptr &msg );
 246
 247   QString replaceHeadersInString( const KMime::Message::Ptr &msg, const QString & s );
 248
 249   /*
 250    * If force charset option is enabled, try to set the original charset
 251    *  in the newly created message. If unable to encode, fall back to
 252    *  preferred charsets, and if all fail, use UTF-8.
 253    */
 254   void applyCharset( const KMime::Message::Ptr msg );
 255
 256   QByteArray getRefStr( const KMime::Message::Ptr &msg );
 257
 258   // TODO move IdentityManager used in KMail to kdepimlibs when not in freeze
 259   KPIMIdentities::IdentityManager* m_identityManager;
 260   // Required parts to create messages
 261   KMime::Message::Ptr m_origMsg;
 262   Akonadi::Entity::Id m_origId;
 263   Akonadi::Item::Id m_folderId;
 264   Akonadi::Item::Id m_parentFolderId;
 265
 266   // Optional settings the calling class may set
 267   MessageComposer::ReplyStrategy m_replyStrategy;
 268   QString m_selection, m_template;
 269   bool m_quote, m_allowDecryption;
 270   QStringList m_mailingListAddresses;
 271   Akonadi::Item::Id m_id;
 272
 273 };
 274
 275 }
 276
 277 #endif