src/Plugins/AddressbookPlugin.h

   1 /* Copyright (C) 2013 Pali Rohár <pali.rohar@gmail.com>
   2
   3    This file is part of the Trojita Qt IMAP e-mail client,
   4    http://trojita.flaska.net/
   5
   6    This program is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU General Public License as
   8    published by the Free Software Foundation; either version 2 of
   9    the License or (at your option) version 3 or any later version
  10    accepted by the membership of KDE e.V. (or its successor approved
  11    by the membership of KDE e.V.), which shall act as a proxy
  12    defined in Section 14 of version 3 of the license.
  13
  14    This program 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
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21 */
  22
  23 #ifndef ADDRESSBOOK_INTERFACE
  24 #define ADDRESSBOOK_INTERFACE
  25
  26 #include <QList>
  27 #include <QObject>
  28 #include <QPair>
  29 #include <QString>
  30 #include <QStringList>
  31
  32 #include "PluginJob.h"
  33
  34 namespace Plugins
  35 {
  36
  37 struct PLUGINMANAGER_EXPORT NameEmail
  38 {
  39     NameEmail(const QString &n, const QString &e) : name(n), email(e) {}
  40     QString name;
  41     QString email;
  42 };
  43
  44 typedef QList<NameEmail> NameEmailList;
  45
  46 class PLUGINMANAGER_EXPORT AddressbookJob : public PluginJob
  47 {
  48     Q_OBJECT
  49
  50 public:
  51     /** @short Error emitted by error signal */
  52     enum Error {
  53         UnknownError, /**< Unknown error */
  54         Stopped /**< Emitted when job stopped */
  55     };
  56
  57 signals:
  58     /** @short Emitted when job finishes unsuccessful with error */
  59     void error(Plugins::AddressbookJob::Error error);
  60
  61 protected:
  62     AddressbookJob(QObject *parent);
  63 };
  64
  65 class PLUGINMANAGER_EXPORT AddressbookCompletionJob : public AddressbookJob
  66 {
  67     Q_OBJECT
  68
  69 signals:
  70     /** @short Emitted when completion is available */
  71     void completionAvailable(const Plugins::NameEmailList &completion);
  72
  73 protected:
  74     AddressbookCompletionJob(QObject *parent);
  75 };
  76
  77 class PLUGINMANAGER_EXPORT AddressbookNamesJob : public AddressbookJob
  78 {
  79     Q_OBJECT
  80
  81 signals:
  82     /** @short Emitted when pretty names for address is available */
  83     void prettyNamesForAddressAvailable(const QStringList &displayNames);
  84
  85 protected:
  86     AddressbookNamesJob(QObject *parent);
  87 };
  88
  89 class PLUGINMANAGER_EXPORT AddressbookPlugin : public QObject
  90 {
  91     Q_OBJECT
  92
  93 public:
  94     /** @short Features returned by method features */
  95     enum Feature {
  96         FeatureAddressbookWindow = 1 << 0, /**< Plugin has support for opening addressbook window via openAddressbookWindow */
  97         FeatureContactWindow = 1 << 1, /**< Plugin has support for opening contact window via openContactWindow */
  98         FeatureAddContact = 1 << 2, /**< Plugin has support for adding new contact via openContactWindow */
  99         FeatureEditContact = 1 << 3, /**< Plugin has support for editing existing contact via openContactWindow */
 100         FeatureCompletion = 1 << 4, /**< Plugin has support for completion via requestCompletion */
 101         FeaturePrettyNames = 1 << 5 /**< Plugin has support for display names via requestPrettyNamesForAddress */
 102     };
 103
 104     Q_DECLARE_FLAGS(Features, Feature)
 105
 106     /** @short Return implementation features */
 107     virtual Features features() const = 0;
 108
 109 public slots:
 110     /** @short Request a list of pairs (name, email) matching contacts and return AddressbookJob
 111      *  @p input is input string
 112      *  @p ignores is list of strings which are NOT included in result
 113      *  @p max is the demanded maximum reply length, negative value means "uncapped"
 114      */
 115     virtual AddressbookCompletionJob *requestCompletion(const QString &input, const QStringList &ignores = QStringList(), int max = -1) = 0;
 116
 117     /** @short Request a list of display names matching the given e-mail address and return AddressbookJob
 118      *  @p email is e-mail address
 119      */
 120     virtual AddressbookNamesJob *requestPrettyNamesForAddress(const QString &email) = 0;
 121
 122     /** @short Open window for addressbook manager */
 123     virtual void openAddressbookWindow() = 0;
 124
 125     /** @short Open window for specified contact
 126      *  first try to match contact by email, then by name
 127      *  if contact not exist, open window for adding new contact and fill name and email strings
 128      */
 129     virtual void openContactWindow(const QString &email, const QString &displayName) = 0;
 130
 131 protected:
 132     AddressbookPlugin(QObject *parent);
 133 };
 134
 135 Q_DECLARE_OPERATORS_FOR_FLAGS(AddressbookPlugin::Features)
 136
 137 }
 138
 139 #endif //ADDRESSBOOK_INTERFACE
 140
 141 // vim: set et ts=4 sts=4 sw=4