1 /*
2  * Copyright 2014       Christian Dávid <christian-david@web.de>
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License as
6  * published by the Free Software Foundation; either version 2 of
7  * the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
16  */
17 
18 #ifndef PAYEEIDENTIFIERDATA_H
19 #define PAYEEIDENTIFIERDATA_H
20 
21 #include "payeeidentifier/kmm_payeeidentifier_export.h"
22 
23 #include <QtPlugin>
24 #include <QSharedPointer>
25 #include <QHash>
26 #include <QMetaType>
27 #include <QDomElement>
28 
29 class payeeIdentifier;
30 class payeeIdentifierLoader;
31 
32 /**
33  * @brief Define a unique identifier for an payeeIdentifier subclass
34  *
35  * Use this macro in your class's public section.
36  *
37  * This also defines the helper ::ptr, ::constPtr and className::ptr cloneSharedPtr()
38  *
39  * @param PIDID the payeeIdentifier id, e.g. "org.kmymoney.payeeIdentifier.swift". Must be
40  * unique among all payeeIdentifiers as it is used internally to store data, to compare
41  * types and for type casting (there must not be more than one class which uses that pidid).
42  */
43 #define PAYEEIDENTIFIER_IID(className, iid) \
44   /** @brief Returns the payeeIdentifier Iid */ \
45   static const QString& staticPayeeIdentifierIid() { \
46     static const QString _pidid = QLatin1String( iid ); \
47     return _pidid; \
48   } \
49   /** @brief Returns the payeeIdentifier Id */ \
50   QString payeeIdentifierId() const final override { \
51     return className::staticPayeeIdentifierIid(); \
52   }
53 
54 /**
55  * @brief "Something" that identifies a payee (or an account of a payee)
56  *
57  * The simplest form of this class is an identifier for an bank account (consisting of an account number
58  * and a bank code). But also an e-mail address which is used by an online money-transfer service could be
59  * such an identifier (that is the reason for the abstract name "payeeIdentifier").
60  *
61  * But also the creditor identifier for debit-notes in sepa-countries can be a subclass. It does not
62  * address an account but a company.
63  *
64  * Any payee (@ref MyMoneyPayee) can have several payeeIdentifiers.
65  *
66  * The online banking system uses payeeIdentifiers to determine if it is able so create a credit-transfer
67  * to a given payee. During import the payeeIdentifiers are used to find a payee.
68  *
69  * You should use the shared pointer payeeIdentifier::ptr to handle payeeIdentifiers. To copy them used
70  * cloneSharedPtr().
71  *
72  * @internal First this is more complex than creating a superset of all possible identifiers. But there
73  * are many of them. And using this method it is a lot easier to create the comparison operators and
74  * things like isValid().
75  *
76  * @section Inheriting
77  *
78  * To identify the type of an payeeIdentifier you must use the macro @ref PAYEEIDENTIFIER_IID()
79  * in the public section of your subclass.
80  */
81 class KMM_PAYEEIDENTIFIER_EXPORT payeeIdentifierData
82 {
83 public:
~payeeIdentifierData()84   virtual ~payeeIdentifierData() {}
85 
86   /**
87    * Use PAYEEIDENTIFIER_ID(className, PIDID) to reimplement this method.
88    */
89   virtual QString payeeIdentifierId() const = 0;
90 
91   /**
92    * @brief Comparison operator
93    */
94   virtual bool operator==(const payeeIdentifierData& other) const = 0;
95   virtual bool operator!=(const payeeIdentifierData& other) const {
96     return (!operator==(other));
97   }
98 
99   /**
100    * @brief Check if this payeeIdentifier contains correct data
101    *
102    * You should be able to handle invalid data. It is the task of the ui to prevent
103    * invalid data. But during several procedures invalid data could be used (e.g.
104    * during import).
105    */
106   virtual bool isValid() const = 0;
107 
108   /**
109    * @brief Create a new payeeIdentifier form XML data
110    *
111    * @param element Note: there could be more data in that elemenet than you created in writeXML()
112    */
113   virtual payeeIdentifierData* createFromXml(const QDomElement &element) const = 0;
114 
115   /**
116    * @see MyMoneyObject::writeXML()
117    *
118    * @warning Do not set an attribute "type" or "id" to parent, it is used to store internal data and is
119    * set automatically.
120    */
121   virtual void writeXML(QDomDocument &document, QDomElement &parent) const = 0;
122 
123 protected:
124   /**
125    * @brief Create deep copy
126    */
127   virtual payeeIdentifierData* clone() const = 0;
128   friend class payeeIdentifierLoader;
129   friend class payeeIdentifier;
130 };
131 
132 Q_DECLARE_INTERFACE(payeeIdentifierData, "org.kmymoney.payeeIdentifier")
133 
134 #endif // PAYEEIDENTIFIERDATA_H
135