* don't forget to delete Private of AddTransportDialog

* add TransportType::operator=
* adjust AkonadiJob to use ResourceBase::Transport
* add a note about AkonadiJob needing more thought
* lots of api docs and CamelCase headers

svn path=/branches/work/akonadi-ports/kdepimlibs/; revision=988164

TODO

@@ -12,6 +12,9 @@ TransportManager
 - load passwords if application opens wallet
 - add D-Bus interface for sending mails
 - test to see if there is always a default transport, by adding / deleting accounts
+- it would be nice to make showNewTransportDialog,
+  promptCreateTransportIfNoneExists, and configureTransport visible on D-Bus,
+  but how to handle QWidget *parent?
 
 Transport
 ---------

TODO.cberzan

-* all CamelCase...
-* smtpsettings.ui has hidden widgets... test those... and why can't I set/see the 'visible' property in designer?
-* why is identitylistview in kmail instead of kpimidentities?
-* figure out what needs to be exported and what not (add .hs to CMakeLists afterwards)
-* include KLocale or KLocalizedString??
-* SMTPJob (and probably others) give empty errorString when killed
-
-Bugs:
-* modify -> change password -> ok. password is saved in wallet and seen ok on restart, but clicking modify again shows old password
-* Type=Akonadi and Type=Sendmail appear in the config file, but no Type=SMTP (probably because SMTP == 0 == default)
-* cancel doesn't work in transportmgr, apparently
-

addtransportdialog.cpp

 /*
     Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com>
 
-    Based on code from Kopete (addaccountwizard)
-
     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
@@ -26,8 +24,6 @@
 #include "transporttype.h"
 #include "ui_addtransportdialog.h"
 
-#include <KConfigDialogManager>
-#include <KConfigSkeleton>
 #include <KDebug>
 
 #include <akonadi/agentinstance.h>
@@ -46,10 +42,16 @@ class AddTransportDialog::Private
     {
     }
 
+    /**
+      Returns the currently selected type in the type selection widget, or
+      an invalid type if none is selected.
+    */
     TransportType selectedType() const;
 
-    // slots
-    void typeListClicked();
+    /**
+      Enables the OK button if a type is selected.
+    */
+    void typeListClicked(); // slot
 
     AddTransportDialog *const q;
     Ui::AddTransportDialog ui;
@@ -107,6 +109,7 @@ AddTransportDialog::AddTransportDialog( QWidget *parent )
 
 AddTransportDialog::~AddTransportDialog()
 {
+  delete d;
 }
 
 void AddTransportDialog::accept()

addtransportdialog.h

@@ -20,38 +20,48 @@
 #ifndef MAILTRANSPORT_ADDTRANSPORTDIALOG_H
 #define MAILTRANSPORT_ADDTRANSPORTDIALOG_H
 
-#include <mailtransport/mailtransport_export.h>
-
 #include <KDE/KDialog>
 
 namespace MailTransport {
 
 /**
+  @internal
+
   A dialog for creating a new transport.  It asks the user for the transport
   type and name, and then proceeds to configure the new transport.
+
+  To create a new transport from applications, use
+  TransportManager::showNewTransportDialog().
+
+  @author Constantin Berzan <exit3219@gmail.com>
+  @since 4.4
 */
 class AddTransportDialog : public KDialog
 {
   Q_OBJECT
 
-public:
-  explicit AddTransportDialog( QWidget *parent = 0 );
-  virtual ~AddTransportDialog();
+  public:
+    /**
+      Creates a new AddTransportDialog.
+    */
+    explicit AddTransportDialog( QWidget *parent = 0 );
 
-  /* reimpl */
-  virtual void accept();
+    /**
+      Destroys the AddTransportDialog.
+    */
+    virtual ~AddTransportDialog();
 
-private:
-  class Private;
-  Private *const d;
+    /* reimpl */
+    virtual void accept();
 
-  Q_PRIVATE_SLOT( d, void typeListClicked() )
-
-};
+  private:
+    class Private;
+    Private *const d;
 
+    Q_PRIVATE_SLOT( d, void typeListClicked() )
 
-}
-
+};
 
-#endif
+} // namespace MailTransport
 
+#endif // MAILTRANSPORT_ADDTRANSPORTDIALOG_H

akonadijob.cpp

@@ -83,8 +83,8 @@ void AkonadiJob::doStart()
     return;
   }
 
-  connect( d->iface, SIGNAL( transportResult( bool, const QString & ) ),
-      this, SLOT( resourceResult( bool, const QString & ) ) );
+  connect( d->iface, SIGNAL(transportResult(qlonglong,bool,QString)),
+      this, SLOT(resourceResult(qlonglong,bool,QString)) );
 
   // What TODO about timeouts?  It is quite possible that the result D-Bus signal
   // will get lost, and then what?
@@ -98,8 +98,9 @@ void AkonadiJob::doStart()
   }
 }
 
-void AkonadiJob::resourceResult( bool success, const QString &message )
+void AkonadiJob::resourceResult( qlonglong itemId, bool success, const QString &message )
 {
+  Q_ASSERT( itemId == d->itemId );
   if( !success ) {
     setError( UserDefinedError );
     setErrorText( message );

akonadijob.h

@@ -29,9 +29,16 @@ class AkonadiJobPrivate;
 namespace MailTransport {
 
 /**
-  Mail transport job for an Akonadi resource.
-
-  TODO docu... apps need to call setItem if it's an Akonadi job...
+  Mail transport job for an Akonadi-based transport.
+  Unlike SmtpJob and SendmailJob, you also need to call setItemId() before
+  starting this job.  In other words, the item you want to send has to be
+  created in advance.
+
+  TODO API:
+  * Should we provide setItem or let the job assemble the item out of data()?
+  * What to do about from, to, cc, bcc? Should there be some kind of standard
+    attribute containing these?  Currently data(), from(), to() etc. are
+    completely ignored.
 */
 class MAILTRANSPORT_EXPORT AkonadiJob : public TransportJob
 {
@@ -39,7 +46,7 @@ class MAILTRANSPORT_EXPORT AkonadiJob : public TransportJob
   public:
     /**
       Creates an AkonadiJob.
-      @param transport The transport settings.
+      @param transport The transport object to use.
       @param parent The parent object.
     */
     explicit AkonadiJob( Transport *transport, QObject *parent = 0 );
@@ -49,7 +56,6 @@ class MAILTRANSPORT_EXPORT AkonadiJob : public TransportJob
     */
     virtual ~AkonadiJob();
 
-    // TODO have these here or in TransportJob?  They are useless in {SMTP,Sendmail}Job...
     /**
       The id of the item to send.
     */
@@ -62,16 +68,17 @@ class MAILTRANSPORT_EXPORT AkonadiJob : public TransportJob
     void setItemId( Akonadi::Item::Id id );
 
   protected:
+    /** reimpl */
     virtual void doStart();
 
   private Q_SLOTS:
-    void resourceResult( bool success, const QString &message );
+    void resourceResult( qlonglong itemId, bool success, const QString &message );
 
   private:
     AkonadiJobPrivate *const d;
 
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_AKONADIJOB_H

configmodule.cpp

@@ -20,9 +20,10 @@
 #include "configmodule.h"
 #include "transportmanagementwidget.h"
 
-#include <kpluginfactory.h>
-#include <kpluginloader.h>
-#include <qboxlayout.h>
+#include <QBoxLayout>
+
+#include <KPluginFactory>
+#include <KPluginLoader>
 
 using namespace MailTransport;
 

configmodule.h

@@ -20,7 +20,7 @@
 #ifndef MAILTRANSPORT_CONFIGMODULE_H
 #define MAILTRANSPORT_CONFIGMODULE_H
 
-#include <kcmodule.h>
+#include <KDE/KCModule>
 
 namespace MailTransport {
 
@@ -34,6 +34,6 @@ class ConfigModule : public KCModule
                            const QVariantList &args = QVariantList() );
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_CONFIGMODULE_H

legacydecrypt.cpp

@@ -22,7 +22,7 @@
 
 #include "legacydecrypt.h"
 
-#include <kstringhandler.h>
+#include <KStringHandler>
 
 using namespace MailTransport;
 

legacydecrypt.h

@@ -23,7 +23,7 @@
 #ifndef MAILTRANSPORT_LEGACYDECRYPT_H
 #define MAILTRANSPORT_LEGACYDECRYPT_H
 
-#include <QString>
+#include <QtCore/QString>
 
 namespace MailTransport {
 
@@ -44,6 +44,6 @@ class Legacy
     static QString decryptKNode( const QString &data );
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_LEGACYDECRYPT_H

mailtransport_defs.h

@@ -39,8 +39,8 @@
 #define SMTP_PORT 25
 #define SMTPS_PORT 465
 
-/* Because ServerTest is also capable of testing IMAP,
- * some addition defines. */
+// Because ServerTest is also capable of testing IMAP,
+// some additional defines:
 
 #define IMAP_PROTOCOL QLatin1String("imap")
 #define IMAPS_PROTOCOL QLatin1String("imaps")

precommandjob.cpp

@@ -23,8 +23,8 @@
 
 #include "precommandjob.h"
 
-#include <klocale.h>
-#include <kdebug.h>
+#include <KDebug>
+#include <KLocalizedString>
 #include <KProcess>
 
 using namespace MailTransport;

precommandjob.h

@@ -24,9 +24,9 @@
 #ifndef MAILTRANSPORT_PRECOMMANDJOB_H
 #define MAILTRANSPORT_PRECOMMANDJOB_H
 
-#include <kjob.h>
+#include <QtCore/QProcess>
 
-#include <QProcess>
+#include <KDE/KJob>
 
 class PreCommandJobPrivate;
 
@@ -69,6 +69,6 @@ class PrecommandJob : public KJob
     PreCommandJobPrivate *const d;
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_PRECOMMANDJOB_H

sendmailconfigwidget.h

@@ -59,6 +59,6 @@ class SendmailConfigWidget : public TransportConfigWidget
 
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_SENDMAILCONFIGWIDGET_H

sendmailjob.cpp

@@ -24,7 +24,7 @@
 #include "sendmailjob.h"
 #include "transport.h"
 
-#include <KLocale>
+#include <KLocalizedString>
 
 #include <QtCore/QProcess>
 #include <QtCore/QBuffer>

sendmailjob.h

@@ -27,6 +27,7 @@
 #include <mailtransport/transportjob.h>
 
 #include <QtCore/QProcess>
+
 class SendMailJobPrivate;
 
 namespace MailTransport {
@@ -63,6 +64,6 @@ class MAILTRANSPORT_EXPORT SendmailJob : public TransportJob
     SendMailJobPrivate *const d;
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_SENDMAILJOB_H

servertest.cpp

@@ -32,8 +32,8 @@
 #include <QTimer>
 
 // KDE
-#include <klocale.h>
-#include <kdebug.h>
+#include <KLocalizedString>
+#include <KDebug>
 
 using namespace MailTransport;
 

servertest.h

@@ -209,6 +209,6 @@ class MAILTRANSPORT_EXPORT ServerTest : public QWidget
     Q_PRIVATE_SLOT( d, void slotUpdateProgress() )
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_SERVERTEST_H

smtpconfigwidget.h

@@ -72,6 +72,6 @@ class SMTPConfigWidget : public TransportConfigWidget
 
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_SMTPCONFIGWIDGET_H

smtpjob.cpp

@@ -25,15 +25,15 @@
 #include "mailtransport_defs.h"
 #include "precommandjob.h"
 
-#include <klocale.h>
-#include <kurl.h>
-#include <kio/job.h>
-#include <kio/scheduler.h>
-#include <kio/passworddialog.h>
-
 #include <QBuffer>
 #include <QHash>
 
+#include <KLocalizedString>
+#include <KUrl>
+#include <KIO/Job>
+#include <KIO/Scheduler>
+#include <KIO/PasswordDialog>
+
 using namespace MailTransport;
 
 class SlavePool

smtpjob.h

@@ -26,8 +26,8 @@
 #include <mailtransport/transportjob.h>
 
 namespace KIO {
-class Job;
-class Slave;
+  class Job;
+  class Slave;
 }
 
 class SmtpJobPrivate;
@@ -78,6 +78,6 @@ class MAILTRANSPORT_EXPORT SmtpJob : public TransportJob
     SmtpJobPrivate *const d;
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_SMTPJOB_H

socket.cpp

@@ -29,9 +29,9 @@
 #include <QSslSocket>
 
 // KDE
-#include <kdebug.h>
+#include <KDebug>
+#include <KLocalizedString>
 #include <ksocketfactory.h>
-#include <klocale.h>
 
 using namespace MailTransport;
 

socket.h

@@ -22,7 +22,7 @@
 
 #include <mailtransport/mailtransport_export.h>
 
-#include <QSslSocket>
+#include <QtNetwork/QSslSocket>
 
 namespace MailTransport
 {
@@ -125,7 +125,7 @@ namespace MailTransport
        */
       void tlsDone();
   };
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_SOCKET_H
 

tests/transportmgr.cpp

@@ -74,6 +74,8 @@ void TransportMgr::removeAllBtnClicked()
 
 void TransportMgr::editBtnClicked()
 {
+  // NOTE: Using deprecated TransportConfigDialog here for testing purposes.
+  // The TransportManagementWidget uses the non-deprecated method instead.
   TransportConfigDialog *t =
     new TransportConfigDialog(
       TransportManager::self()->transportById( mComboBox->currentTransportId() ), this );

transport.cpp

@@ -23,15 +23,15 @@
 #include "transportmanager.h"
 #include "transporttype_p.h"
 
-#include <kdebug.h>
-#include <klocale.h>
-#include <kmessagebox.h>
-#include <kstringhandler.h>
-#include <kwallet.h>
-#include <kconfiggroup.h>
-
 #include <QTimer>
 
+#include <KConfigGroup>
+#include <KDebug>
+#include <KLocalizedString>
+#include <KMessageBox>
+#include <KStringHandler>
+#include <KWallet/Wallet>
+
 #include <akonadi/agentinstance.h>
 #include <akonadi/agentmanager.h>
 

transport.h

@@ -73,6 +73,7 @@ class MAILTRANSPORT_EXPORT Transport : public TransportBase
     /**
       Makes sure the transport has a unique name.  Adds #1, #2, #3 etc. if
       necessary.
+      @since 4.4
     */
     void forceUniqueName();
 
@@ -113,12 +114,14 @@ class MAILTRANSPORT_EXPORT Transport : public TransportBase
     /**
       Returns the type of this transport.
       @see TransportType.
+      @since 4.4
     */
     TransportType transportType() const;
 
     /**
       Sets the type of this transport.
       @see TransportType.
+      @since 4.4
     */
     void setTransportType( const TransportType &type );
 
@@ -149,6 +152,6 @@ class MAILTRANSPORT_EXPORT Transport : public TransportBase
     TransportPrivate *const d;
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_TRANSPORT_H

transportcombobox.cpp

@@ -21,10 +21,8 @@
 #include "transport.h"
 #include "transportmanager.h"
 
-#include <kdebug.h>
-#include <klocale.h>
-
-#include <QLineEdit>
+#include <KDebug>
+#include <KLocale>
 
 using namespace MailTransport;
 

transportcombobox.h

@@ -20,9 +20,10 @@
 #ifndef MAILTRANSPORT_TRANSPORTCOMBOBOX_H
 #define MAILTRANSPORT_TRANSPORTCOMBOBOX_H
 
-#include <mailtransport/transportbase.h>
 #include <mailtransport/mailtransport_export.h>
-#include <kcombobox.h>
+#include <mailtransport/transportbase.h>
+
+#include <KDE/KComboBox>
 
 class TransportComboBoxPrivate;
 
@@ -30,6 +31,7 @@ namespace MailTransport {
 
 /**
   A combo-box for selecting a mail transport.
+  It is updated automatically when transports are added, changed, or removed.
 */
 class MAILTRANSPORT_EXPORT TransportComboBox : public KComboBox
 {
@@ -67,6 +69,6 @@ class MAILTRANSPORT_EXPORT TransportComboBox : public KComboBox
     TransportComboBoxPrivate *const d;
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_TRANSPORTCOMBOBOX_H

transportconfigdialog.h

@@ -37,7 +37,7 @@ class Transport;
 
   @deprecated Use TransportManager::configureTransport() instead.
 */
-// KDE5: this class should not be exported.
+// TODO KDE5: this class should not be exported.
 // FIXME how to avoid deprecated warning from its own moc?
 class MAILTRANSPORT_EXPORT_DEPRECATED TransportConfigDialog : public KDialog
 {
@@ -74,6 +74,6 @@ class MAILTRANSPORT_EXPORT_DEPRECATED TransportConfigDialog : public KDialog
 
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_TRANSPORTCONFIGDIALOG_H

transportconfigwidget.cpp

@@ -31,7 +31,6 @@
 
 #include <KConfigDialogManager>
 #include <KDebug>
-#include <KLocalizedString>
 
 using namespace MailTransport;
 
@@ -62,7 +61,7 @@ void TransportConfigWidget::init( Transport *transport )
   d->transport = transport;
 
   d->manager = new KConfigDialogManager( this, transport );
-  //d->manager->updateWidgets(); // no use; ui is set up in subclasses.
+  //d->manager->updateWidgets(); // no-op; ui is set up in subclasses.
 }
 
 KConfigDialogManager *TransportConfigWidget::configManager() const
@@ -81,5 +80,4 @@ void TransportConfigWidget::apply()
   kDebug() << "Config written.";
 }
 
-
 #include "transportconfigwidget.moc"

transportconfigwidget.h

@@ -37,8 +37,24 @@ class TransportConfigWidgetPrivate;
 
 /**
   @internal
-  Abstract configuration widget for a mail transport.
-  There is a derived class for each transport, such as SMTPConfigWidget etc.
+
+  Abstract configuration widget for a mail transport.  It makes sure that
+  the configured transport has a unique name, and takes care of writing its
+  settings to the config file.  If it is a new transport, the caller must
+  still call TransportManager::addTransport() to register the transport.
+
+  Concrete configuration is done in subclasses SMTPConfigWidget and
+  SendmailConfigWidget.  Akonadi-type transports are not configured by
+  MailTransport directly, instead the configure() method of their agent
+  instance is called.
+
+  To configure a transport from applications, use
+  TransportManager::configureTransport().  You still need to call
+  TransportManager::addTransport() if this is a new transport, not registered
+  with TransportManager.
+
+  @author Constantin Berzan <exit3219@gmail.com>
+  @since 4.4
 */
 class TransportConfigWidget : public QWidget
 {
@@ -48,9 +64,7 @@ class TransportConfigWidget : public QWidget
     /**
       Creates a new mail transport configuration widget for the given
       Transport object.
-      @param transport The Transport object to configure. This must be a deep
-      copy of a Transport object or a newly created one, which hasn't been
-      added to the TransportManager yet.
+      @param transport The Transport object to configure.
       @param parent The parent widget.
     */
     explicit TransportConfigWidget( Transport *transport, QWidget *parent = 0 );
@@ -88,6 +102,6 @@ class TransportConfigWidget : public QWidget
 
 };
 
-}
+} // namespace MailTransport
 
-#endif
+#endif // MAILTRANSPORT_TRANSPORTCONFIGWIDGET_H

transportconfigwidget_p.h

@@ -24,9 +24,11 @@
 
 #include <KDE/KConfigDialogManager>
 
-namespace MailTransport
-{
+namespace MailTransport {
 
+/**
+  @internal