|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the Qt Mobility Components. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 |
|
43 #ifndef QCONTACTMANAGER_H |
|
44 #define QCONTACTMANAGER_H |
|
45 |
|
46 #include <QObject> |
|
47 |
|
48 #include <QMap> |
|
49 #include <QString> |
|
50 #include <QStringList> |
|
51 #include <QList> |
|
52 #include <QDateTime> |
|
53 |
|
54 #include "qtcontactsglobal.h" |
|
55 #include "qcontact.h" |
|
56 #include "qcontactid.h" |
|
57 #include "qcontactrelationship.h" |
|
58 #include "qcontactsortorder.h" |
|
59 #include "qcontactfetchhint.h" |
|
60 |
|
61 QTM_BEGIN_NAMESPACE |
|
62 |
|
63 class QContactFilter; |
|
64 class QContactAction; |
|
65 |
|
66 class QContactManagerData; |
|
67 class Q_CONTACTS_EXPORT QContactManager : public QObject |
|
68 { |
|
69 Q_OBJECT |
|
70 |
|
71 public: |
|
72 #if Q_QDOC // qdoc's parser fails to recognise the default map argument |
|
73 explicit QContactManager(const QString& managerName = QString(), const QMap<QString, QString>& parameters = 0, QObject* parent = 0); |
|
74 QContactManager(const QString& managerName, int implementationVersion, const QMap<QString, QString>& parameters = 0, QObject* parent = 0); |
|
75 #else |
|
76 explicit QContactManager(const QString& managerName = QString(), const QMap<QString, QString>& parameters = (QMap<QString, QString>()), QObject* parent = 0); |
|
77 QContactManager(const QString& managerName, int implementationVersion, const QMap<QString, QString>& parameters = (QMap<QString, QString>()), QObject* parent = 0); |
|
78 #endif |
|
79 explicit QContactManager(QObject* parent); |
|
80 |
|
81 static QContactManager* fromUri(const QString& uri, QObject* parent = 0); |
|
82 ~QContactManager(); // dtor |
|
83 |
|
84 QString managerName() const; // e.g. "Symbian" |
|
85 QMap<QString, QString> managerParameters() const; // e.g. "filename=private.db" |
|
86 QString managerUri() const; // managerName + managerParameters |
|
87 int managerVersion() const; |
|
88 |
|
89 static bool parseUri(const QString& uri, QString* managerName, QMap<QString, QString>* params); // replaces the above. |
|
90 static QString buildUri(const QString& managerName, const QMap<QString, QString>& params, int implementationVersion = -1); |
|
91 |
|
92 /* The values of the Error enum are still to be decided! */ |
|
93 enum Error { |
|
94 NoError = 0, |
|
95 DoesNotExistError, |
|
96 AlreadyExistsError, |
|
97 InvalidDetailError, |
|
98 InvalidRelationshipError, |
|
99 LockedError, |
|
100 DetailAccessError, |
|
101 PermissionsError, |
|
102 OutOfMemoryError, |
|
103 NotSupportedError, |
|
104 BadArgumentError, |
|
105 UnspecifiedError, |
|
106 VersionMismatchError, |
|
107 LimitReachedError, |
|
108 InvalidContactTypeError |
|
109 }; |
|
110 |
|
111 /* Error reporting */ |
|
112 QContactManager::Error error() const; |
|
113 |
|
114 /* Contacts - Accessors and Mutators */ |
|
115 QList<QContactLocalId> contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const; |
|
116 QList<QContactLocalId> contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const; |
|
117 |
|
118 QList<QContact> contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const; |
|
119 QList<QContact> contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const; |
|
120 QContact contact(const QContactLocalId& contactId, const QContactFetchHint& fetchHint = QContactFetchHint()) const; // retrieve a contact |
|
121 |
|
122 bool saveContact(QContact* contact); // note: MODIFIES contact (sets the contactId) |
|
123 bool removeContact(const QContactLocalId& contactId); // remove the contact from the persistent store |
|
124 |
|
125 bool saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap); // batch API - save. |
|
126 bool removeContacts(const QList<QContactLocalId>& contactIds, QMap<int, QContactManager::Error>* errorMap); // batch API - remove. |
|
127 |
|
128 /* Return a pruned or modified contact which is valid and can be saved in the manager */ |
|
129 QContact compatibleContact(const QContact& original); // Preliminary function! |
|
130 |
|
131 /* deprecated - to be removed after the transition period has elapsed */ |
|
132 QString Q_DECL_DEPRECATED synthesizedDisplayLabel(const QContact& contact) const; |
|
133 /* Synthesize the display label of a contact */ |
|
134 QString synthesizedContactDisplayLabel(const QContact& contact) const; |
|
135 void synthesizeContactDisplayLabel(QContact* contact) const; |
|
136 |
|
137 /* "Self" contact id (MyCard) */ |
|
138 bool setSelfContactId(const QContactLocalId& contactId); |
|
139 QContactLocalId selfContactId() const; |
|
140 |
|
141 /* Relationships */ |
|
142 QList<QContactRelationship> relationships(const QContactId& participantId, QContactRelationship::Role role = QContactRelationship::Either) const; |
|
143 QList<QContactRelationship> relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationship::Role role = QContactRelationship::Either) const; |
|
144 bool saveRelationship(QContactRelationship* relationship); |
|
145 bool saveRelationships(QList<QContactRelationship>* relationships, QMap<int, QContactManager::Error>* errorMap); |
|
146 bool removeRelationship(const QContactRelationship& relationship); |
|
147 bool removeRelationships(const QList<QContactRelationship>& relationships, QMap<int, QContactManager::Error>* errorMap); |
|
148 |
|
149 /* Definitions - Accessors and Mutators */ |
|
150 QMap<QString, QContactDetailDefinition> detailDefinitions(const QString& contactType = QContactType::TypeContact) const; |
|
151 QContactDetailDefinition detailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact) const; |
|
152 bool saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType = QContactType::TypeContact); |
|
153 bool removeDetailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact); |
|
154 |
|
155 /* Functionality reporting */ |
|
156 enum ManagerFeature { |
|
157 Groups = 0, // backend supports QContactType::TypeGroup type contacts (convenience for clients... should be deprecated) |
|
158 ActionPreferences, // per-contact action preferences |
|
159 MutableDefinitions, |
|
160 Relationships, |
|
161 ArbitraryRelationshipTypes, |
|
162 RelationshipOrdering, // deprecated along with setRelationshipOrder() etc in QContact. |
|
163 DetailOrdering, |
|
164 SelfContact, |
|
165 Anonymous, |
|
166 ChangeLogs |
|
167 }; |
|
168 bool hasFeature(QContactManager::ManagerFeature feature, const QString& contactType = QContactType::TypeContact) const; |
|
169 bool isRelationshipTypeSupported(const QString& relationshipType, const QString& contactType = QContactType::TypeContact) const; // replaces the above |
|
170 QList<QVariant::Type> supportedDataTypes() const; |
|
171 bool isFilterSupported(const QContactFilter& filter) const; |
|
172 QStringList supportedContactTypes() const; |
|
173 |
|
174 /* return a list of available backends for which a QContactManager can be constructed. */ |
|
175 static QStringList availableManagers(); |
|
176 |
|
177 Q_SIGNALS: |
|
178 void dataChanged(); |
|
179 void contactsAdded(const QList<QContactLocalId>& contactIds); |
|
180 void contactsChanged(const QList<QContactLocalId>& contactIds); |
|
181 void contactsRemoved(const QList<QContactLocalId>& contactIds); |
|
182 void relationshipsAdded(const QList<QContactLocalId>& affectedContactIds); |
|
183 void relationshipsRemoved(const QList<QContactLocalId>& affectedContactIds); |
|
184 void selfContactIdChanged(const QContactLocalId& oldId, const QContactLocalId& newId); // need both? or just new? |
|
185 |
|
186 private: |
|
187 friend class QContactManagerData; |
|
188 void createEngine(const QString& managerName, const QMap<QString, QString>& parameters); |
|
189 Q_DISABLE_COPY(QContactManager) |
|
190 // private data pointer |
|
191 QContactManagerData* d; |
|
192 }; |
|
193 |
|
194 QTM_END_NAMESPACE |
|
195 |
|
196 #endif |