1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd.
4** Contact: http://www.qt.io/licensing/
5**
6** This file is part of the QtContacts module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL21$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 2.1 or version 3 as published by the Free
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22** following information to ensure the GNU Lesser General Public License
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25**
26** As a special exception, The Qt Company gives you certain additional
27** rights. These rights are described in The Qt Company LGPL Exception
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29**
30** $QT_END_LICENSE$
31**
32****************************************************************************/
33
34#ifndef QCONTACTMANAGERENGINE_H
35#define QCONTACTMANAGERENGINE_H
36
37#include <QtCore/qdatetime.h>
38#include <QtCore/qmap.h>
39#include <QtCore/qobject.h>
40#include <QtCore/qstringlist.h>
41#include <QtCore/qvariant.h>
42
43#include <QtContacts/qcontact.h>
44#include <QtContacts/qcontactabstractrequest.h>
45#include <QtContacts/qcontactfetchhint.h>
46#include <QtContacts/qcontactfilter.h>
47#include <QtContacts/qcontactid.h>
48#include <QtContacts/qcontactmanager.h>
49#include <QtContacts/qcontactrequests.h>
50#include <QtContacts/qcontactsortorder.h>
51#include <QtContacts/qcontactcollectionfetchrequest.h>
52#include <QtContacts/qcontactcollectionsaverequest.h>
53#include <QtContacts/qcontactcollectionremoverequest.h>
54
55QT_BEGIN_NAMESPACE_CONTACTS
56
57class Q_CONTACTS_EXPORT QContactManagerEngine : public QObject
58{
59 Q_OBJECT
60
61public:
62 QContactManagerEngine() {}
63
64 /* URI reporting */
65 virtual QString managerName() const = 0; // e.g. "memory"
66 virtual QMap<QString, QString> managerParameters() const; // e.g. "filename=private.db,cachesize=1024"
67 virtual QMap<QString, QString> idInterpretationParameters() const; // e.g. "filename=private.db"
68 virtual int managerVersion() const = 0;
69
70 inline QString managerUri() const
71 { if (m_uri.isNull()) m_uri = QContactManager::buildUri(managerName: managerName(), params: idInterpretationParameters()); return m_uri; }
72
73 inline QContactId contactId(const QByteArray &localId) const
74 { return QContactId(managerUri(), localId); }
75 inline QContactCollectionId collectionId(const QByteArray &localId) const
76 { return QContactCollectionId(managerUri(), localId); }
77
78 /* Filtering */
79 virtual QList<QContactId> contactIds(const QContactFilter &filter, const QList<QContactSortOrder> &sortOrders, QContactManager::Error *error) const;
80 virtual QList<QContact> contacts(const QContactFilter &filter, const QList<QContactSortOrder>& sortOrders, const QContactFetchHint &fetchHint, QContactManager::Error *error) const;
81 virtual QList<QContact> contacts(const QList<QContactId> &contactIds, const QContactFetchHint& fetchHint, QMap<int, QContactManager::Error> *errorMap, QContactManager::Error *error) const;
82 virtual QContact contact(const QContactId &contactId, const QContactFetchHint &fetchHint, QContactManager::Error *error) const;
83
84 virtual bool saveContact(QContact *contact, QContactManager::Error *error);
85 virtual bool removeContact(const QContactId &contactId, QContactManager::Error *error);
86 virtual bool saveRelationship(QContactRelationship *relationship, QContactManager::Error *error);
87 virtual bool removeRelationship(const QContactRelationship &relationship, QContactManager::Error *error);
88
89 virtual bool saveContacts(QList<QContact> *contacts, QMap<int, QContactManager::Error> *errorMap, QContactManager::Error *error);
90 virtual bool saveContacts(QList<QContact> *contacts, const QList<QContactDetail::DetailType> &typeMask, QMap<int, QContactManager::Error> *errorMap, QContactManager::Error *error);
91 virtual bool removeContacts(const QList<QContactId> &contactIds, QMap<int, QContactManager::Error> *errorMap, QContactManager::Error *error);
92
93 /* "Self" contact id (MyCard) */
94 virtual bool setSelfContactId(const QContactId &contactId, QContactManager::Error *error);
95 virtual QContactId selfContactId(QContactManager::Error *error) const;
96
97 /* Relationships between contacts */
98 virtual QList<QContactRelationship> relationships(const QString &relationshipType, const QContactId& participantId, QContactRelationship::Role role, QContactManager::Error *error) const;
99 virtual bool saveRelationships(QList<QContactRelationship> *relationships, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error *error);
100 virtual bool removeRelationships(const QList<QContactRelationship> &relationships, QMap<int, QContactManager::Error> *errorMap, QContactManager::Error *error);
101
102 // collections
103 virtual QContactCollectionId defaultCollectionId() const;
104 virtual QContactCollection collection(const QContactCollectionId &collectionId, QContactManager::Error *error);
105 virtual QList<QContactCollection> collections(QContactManager::Error *error);
106 virtual bool saveCollection(QContactCollection *collection, QContactManager::Error *error);
107 virtual bool removeCollection(const QContactCollectionId &collectionId, QContactManager::Error *error);
108
109 /* Validation for saving */
110 virtual bool validateContact(const QContact &contact, QContactManager::Error *error) const;
111
112 /* Asynchronous Request Support */
113 virtual void requestDestroyed(QContactAbstractRequest *req);
114 virtual bool startRequest(QContactAbstractRequest *req);
115 virtual bool cancelRequest(QContactAbstractRequest *req);
116 virtual bool waitForRequestFinished(QContactAbstractRequest *req, int msecs);
117
118 /* Capabilities reporting */
119 virtual bool isRelationshipTypeSupported(const QString &relationshipType, QContactType::TypeValues contactType) const;
120 virtual bool isFilterSupported(const QContactFilter &filter) const;
121 virtual QList<QVariant::Type> supportedDataTypes() const;
122 virtual QList<QContactType::TypeValues> supportedContactTypes() const;
123 virtual QList<QContactDetail::DetailType> supportedContactDetailTypes() const;
124
125Q_SIGNALS:
126 void dataChanged();
127 void contactsAdded(const QList<QContactId> &contactIds);
128 void contactsChanged(const QList<QContactId> &contactIds, const QList<QContactDetail::DetailType> &typesChanged);
129 void contactsRemoved(const QList<QContactId> &contactIds);
130 void relationshipsAdded(const QList<QContactId> &affectedContactIds);
131 void relationshipsRemoved(const QList<QContactId> &affectedContactIds);
132 void selfContactIdChanged(const QContactId &oldId, const QContactId &newId);
133 void collectionsAdded(const QList<QContactCollectionId> &collectionIds);
134 void collectionsChanged(const QList<QContactCollectionId> &collectionIds);
135 void collectionsRemoved(const QList<QContactCollectionId> &collectionIds);
136 void collectionsModified(const QList<QPair<QContactCollectionId, QContactManager::Operation> > &collectionIds);
137
138public:
139 // Async update functions
140 static void updateRequestState(QContactAbstractRequest *req, QContactAbstractRequest::State state);
141
142 static void updateContactIdFetchRequest(QContactIdFetchRequest *req, const QList<QContactId>& result, QContactManager::Error error, QContactAbstractRequest::State);
143 static void updateContactFetchRequest(QContactFetchRequest *req, const QList<QContact> &result, QContactManager::Error error, QContactAbstractRequest::State);
144 static void updateContactFetchByIdRequest(QContactFetchByIdRequest *req, const QList<QContact>& result, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State);
145 static void updateContactRemoveRequest(QContactRemoveRequest *req, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State);
146 static void updateContactSaveRequest(QContactSaveRequest *req, const QList<QContact> &result, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State);
147 static void updateRelationshipSaveRequest(QContactRelationshipSaveRequest *req, const QList<QContactRelationship> &result, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State);
148 static void updateRelationshipRemoveRequest(QContactRelationshipRemoveRequest *req, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State);
149 static void updateRelationshipFetchRequest(QContactRelationshipFetchRequest *req, const QList<QContactRelationship> &result, QContactManager::Error error, QContactAbstractRequest::State);
150
151 // collections
152 static void updateCollectionFetchRequest(QContactCollectionFetchRequest *request, const QList<QContactCollection> &result, QContactManager::Error error, QContactAbstractRequest::State newState);
153 static void updateCollectionRemoveRequest(QContactCollectionRemoveRequest *request, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State newState);
154 static void updateCollectionSaveRequest(QContactCollectionSaveRequest *request, const QList<QContactCollection> &result, QContactManager::Error error, const QMap<int, QContactManager::Error> &errorMap, QContactAbstractRequest::State newState);
155
156 // Other protected area update functions
157 static void setDetailAccessConstraints(QContactDetail *detail, QContactDetail::AccessConstraints constraints);
158 static void setContactRelationships(QContact *contact, const QList<QContactRelationship> &relationships);
159 static void setDetailProvenance(QContactDetail *detail, const QString &provenance);
160
161 /* Helper functions */
162 static int compareContact(const QContact &a, const QContact &b, const QList<QContactSortOrder> &sortOrders);
163 static void addSorted(QList<QContact>* sorted, const QContact &toAdd, const QList<QContactSortOrder> &sortOrders);
164 static int compareVariant(const QVariant &first, const QVariant &second, Qt::CaseSensitivity sensitivity);
165 static bool testFilter(const QContactFilter& filter, const QContact &contact);
166 static QList<QContactId> sortContacts(const QList<QContact> &contacts, const QList<QContactSortOrder> &sortOrders);
167
168 static QContactFilter canonicalizedFilter(const QContactFilter &filter);
169
170private:
171 /* QContactChangeSet is a utility class used to emit the appropriate signals */
172 friend class QContactChangeSet;
173
174 mutable QString m_uri;
175};
176
177QT_END_NAMESPACE_CONTACTS
178
179QT_BEGIN_NAMESPACE
180Q_DECLARE_INTERFACE(QtContacts::QContactManagerEngine, "org.qt-project.Qt.QContactManagerEngine")
181QT_END_NAMESPACE
182
183#endif // QCONTACTMANAGERENGINE_H
184

source code of qtpim/src/contacts/qcontactmanagerengine.h