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 QCONTACTMANAGER_H
35#define QCONTACTMANAGER_H
36
37#include <QtCore/qmap.h>
38#include <QtCore/qobject.h>
39#include <QtCore/qstringlist.h>
40
41#include <QtContacts/qcontact.h>
42#include <QtContacts/qcontactcollection.h>
43#include <QtContacts/qcontactid.h>
44#include <QtContacts/qcontactfetchhint.h>
45#include <QtContacts/qcontactrelationship.h>
46#include <QtContacts/qcontactsortorder.h>
47#include <QtContacts/qcontacttype.h>
48
49QT_BEGIN_NAMESPACE_CONTACTS
50
51class QContactAction;
52class QContactFilter;
53
54class QContactManagerData;
55class Q_CONTACTS_EXPORT QContactManager : public QObject
56{
57 Q_OBJECT
58
59public:
60#ifdef Q_QDOC // qdoc's parser fails to recognise the default map argument
61 explicit QContactManager(const QString& managerName = QString(), const QMap<QString, QString>& parameters = 0, QObject* parent = Q_NULLPTR);
62 QContactManager(const QString& managerName, int implementationVersion, const QMap<QString, QString>& parameters = 0, QObject* parent = Q_NULLPTR);
63#else
64 explicit QContactManager(const QString& managerName = QString(), const QMap<QString, QString>& parameters = (QMap<QString, QString>()), QObject* parent = Q_NULLPTR);
65 QContactManager(const QString& managerName, int implementationVersion, const QMap<QString, QString>& parameters = (QMap<QString, QString>()), QObject* parent = Q_NULLPTR);
66#endif
67 explicit QContactManager(QObject* parent);
68
69 inline static const QString ParameterSignalSources() {return QStringLiteral("SignalSources");};
70 inline static const QString ParameterSignalDefinitions() {return QStringLiteral("SignalDefinitions");};
71 inline static const QString ParameterValueOnlyOtherProcesses() {return QStringLiteral("OnlyOtherProcesses");};
72 inline static const QString ParameterValueOnlyOtherManagers() {return QStringLiteral("OnlyOtherManagers");};
73
74 static QContactManager* fromUri(const QString& uri, QObject* parent = Q_NULLPTR);
75 ~QContactManager(); // dtor
76
77 QString managerName() const; // e.g. "memory"
78 QMap<QString, QString> managerParameters() const; // e.g. "filename=private.db"
79 QString managerUri() const; // managerName + managerParameters
80 int managerVersion() const;
81
82 static bool parseUri(const QString &uri, QString *managerName, QMap<QString, QString> *params);
83 static QString buildUri(const QString &managerName, const QMap<QString, QString> &params);
84 static QString buildUri(const QString &managerName, const QMap<QString, QString> &params, int implementationVersion);
85
86 enum Error {
87 NoError = 0,
88 DoesNotExistError,
89 AlreadyExistsError,
90 InvalidDetailError,
91 InvalidRelationshipError,
92 LockedError,
93 DetailAccessError,
94 PermissionsError,
95 OutOfMemoryError,
96 NotSupportedError,
97 BadArgumentError,
98 UnspecifiedError,
99 VersionMismatchError,
100 LimitReachedError,
101 InvalidContactTypeError,
102 TimeoutError,
103 MissingPlatformRequirementsError
104 };
105
106 enum Operation {
107 Add,
108 Change,
109 Remove
110 };
111
112 /* Error reporting */
113 QContactManager::Error error() const;
114 QMap<int, QContactManager::Error> errorMap() const;
115
116 /* Contacts - Accessors and Mutators */
117 QList<QContactId> contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const;
118 QList<QContactId> contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const;
119
120 QList<QContact> contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const;
121 QList<QContact> contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const;
122 QList<QContact> contacts(const QList<QContactId>& contactIds, const QContactFetchHint& fetchHint = QContactFetchHint(), QMap<int, QContactManager::Error>* errorMap = Q_NULLPTR) const;
123
124 QContact contact(const QContactId& contactId, const QContactFetchHint& fetchHint = QContactFetchHint()) const; // retrieve a contact
125
126 bool saveContact(QContact* contact); // note: MODIFIES contact (sets the contactId)
127 bool removeContact(const QContactId& contactId); // remove the contact from the persistent store
128
129 bool saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap = Q_NULLPTR); // batch API - save.
130 bool saveContacts(QList<QContact>* contacts, const QList<QContactDetail::DetailType>& typeMask, QMap<int, QContactManager::Error>* errorMap = Q_NULLPTR); // Partial save
131 bool removeContacts(const QList<QContactId>& contactIds, QMap<int, QContactManager::Error>* errorMap = Q_NULLPTR); // batch API - remove.
132
133 /* "Self" contact id (MyCard) */
134 bool setSelfContactId(const QContactId& contactId);
135 QContactId selfContactId() const;
136
137 /* Relationships */
138 QList<QContactRelationship> relationships(const QContactId& participantId, QContactRelationship::Role role = QContactRelationship::Either) const;
139 QList<QContactRelationship> relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationship::Role role = QContactRelationship::Either) const;
140 bool saveRelationship(QContactRelationship* relationship);
141 bool saveRelationships(QList<QContactRelationship>* relationships, QMap<int, QContactManager::Error>* errorMap = Q_NULLPTR);
142 bool removeRelationship(const QContactRelationship& relationship);
143 bool removeRelationships(const QList<QContactRelationship>& relationships, QMap<int, QContactManager::Error>* errorMap = Q_NULLPTR);
144
145 /* Capabilities reporting */
146 bool isRelationshipTypeSupported(const QString& relationshipType, QContactType::TypeValues contactType = QContactType::TypeContact) const;
147 QList<QVariant::Type> supportedDataTypes() const;
148 bool isFilterSupported(const QContactFilter& filter) const;
149 QList<QContactType::TypeValues> supportedContactTypes() const;
150 QList<QContactDetail::DetailType> supportedContactDetailTypes() const;
151
152 // collections
153 QContactCollectionId defaultCollectionId() const;
154 QContactCollection collection(const QContactCollectionId& collectionId);
155 QList<QContactCollection> collections();
156 bool saveCollection(QContactCollection* collection);
157 bool removeCollection(const QContactCollectionId& collectionId);
158
159 /* return a list of available backends for which a QContactManager can be constructed. */
160 static QStringList availableManagers();
161
162Q_SIGNALS:
163 void dataChanged();
164 void contactsAdded(const QList<QContactId>& contactIds);
165 void contactsChanged(const QList<QContactId>& contactIds, const QList<QContactDetail::DetailType>& typesChanged);
166 void contactsRemoved(const QList<QContactId>& contactIds);
167 void relationshipsAdded(const QList<QContactId>& affectedContactIds);
168 void relationshipsRemoved(const QList<QContactId>& affectedContactIds);
169 void selfContactIdChanged(const QContactId& oldId, const QContactId& newId); // need both? or just new?
170 void collectionsAdded(const QList<QContactCollectionId> &collectionIds);
171 void collectionsChanged(const QList<QContactCollectionId> &collectionIds);
172 void collectionsRemoved(const QList<QContactCollectionId> &collectionIds);
173 void collectionsModified(const QList<QPair<QContactCollectionId, QContactManager::Operation> > &collectionIds);
174
175protected:
176 void connectNotify(const QMetaMethod &signal);
177 void disconnectNotify(const QMetaMethod &signal);
178
179private:
180 friend class QContactManagerData;
181 void createEngine(const QString& managerName, const QMap<QString, QString>& parameters);
182
183 Q_DISABLE_COPY(QContactManager)
184
185 Q_PRIVATE_SLOT(d, void _q_contactsUpdated(const QList<QContactId>& ids, const QList<QContactDetail::DetailType>& typesChanged))
186 Q_PRIVATE_SLOT(d, void _q_contactsDeleted(const QList<QContactId>& ids))
187
188 // private data pointer
189 QContactManagerData* d;
190};
191
192QT_END_NAMESPACE_CONTACTS
193
194#endif // QCONTACTMANAGER_H
195

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