|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 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 #include "qcontactmanager.h" |
|
43 |
|
44 #include "qcontact_p.h" |
|
45 #include "qcontactfilter.h" |
|
46 #include "qcontactdetaildefinition.h" |
|
47 #include "qcontactmanager_p.h" |
|
48 |
|
49 #include <QSharedData> |
|
50 #include <QPair> |
|
51 #include <QSet> |
|
52 |
|
53 QTM_BEGIN_NAMESPACE |
|
54 /*! |
|
55 \class QContactManager |
|
56 \brief The QContactManager class provides clients with access to contact information stored in a particular backend. |
|
57 \ingroup contacts-main |
|
58 |
|
59 This class provides adding, updating and removal of contacts. |
|
60 It also provides definitions for details and fields that can be found in contacts. |
|
61 */ |
|
62 |
|
63 /*! |
|
64 \fn QContactManager::dataChanged() |
|
65 This signal is emitted by the manager if its internal state changes, and it is unable to determine the changes |
|
66 which occurred, or if the manager considers the changes to be radical enough to require clients to reload all data. |
|
67 If this signal is emitted, no other signals will be emitted for the associated changes. |
|
68 */ |
|
69 |
|
70 /*! |
|
71 \fn QContactManager::contactsAdded(const QList<QContactLocalId>& contactIds) |
|
72 This signal is emitted at some point once the contacts identified by \a contactIds have been added to a datastore managed by this manager. |
|
73 This signal must not be emitted if the dataChanged() signal was previously emitted for these changes. |
|
74 */ |
|
75 |
|
76 /*! |
|
77 \fn QContactManager::contactsChanged(const QList<QContactLocalId>& contactIds) |
|
78 This signal is emitted at some point once the contacts identified by \a contactIds have been modified in a datastore managed by this manager. |
|
79 This signal must not be emitted if the dataChanged() signal was previously emitted for these changes. |
|
80 */ |
|
81 |
|
82 /*! |
|
83 \fn QContactManager::contactsRemoved(const QList<QContactLocalId>& contactIds) |
|
84 This signal is emitted at some point once the contacts identified by \a contactIds have been removed from a datastore managed by this manager. |
|
85 This signal must not be emitted if the dataChanged() signal was previously emitted for these changes. |
|
86 */ |
|
87 |
|
88 /*! |
|
89 \fn QContactManager::relationshipsAdded(const QList<QContactLocalId>& affectedContactIds) |
|
90 This signal is emitted at some point after relationships have been added to the manager which involve the contacts identified by \a affectedContactIds. |
|
91 This signal must not be emitted if the dataChanged() signal was previously emitted for these changes. |
|
92 */ |
|
93 |
|
94 /*! |
|
95 \fn QContactManager::relationshipsRemoved(const QList<QContactLocalId>& affectedContactIds) |
|
96 This signal is emitted at some point after relationships have eben removed from the manager which involve the contacts identified by \a affectedContactIds. |
|
97 This signal must not be emitted if the dataChanged() signal was previously emitted for these changes. |
|
98 */ |
|
99 |
|
100 /*! |
|
101 \fn QContactManager::selfContactIdChanged(const QContactLocalId& oldId, const QContactLocalId& newId) |
|
102 This signal is emitted at some point after the id of the self-contact is changed from \a oldId to \a newId in the manager. |
|
103 If the \a newId is the invalid, zero id, then the self contact was deleted or no self contact exists. |
|
104 This signal must not be emitted if the dataChanged() signal was previously emitted for this change. |
|
105 */ |
|
106 |
|
107 |
|
108 |
|
109 #define makestr(x) (#x) |
|
110 #define makename(x) makestr(x) |
|
111 |
|
112 /*! |
|
113 Returns a list of available manager ids that can be used when constructing |
|
114 a QContactManager. If an empty id is specified to the constructor, the |
|
115 first value in this list will be used instead. |
|
116 */ |
|
117 QStringList QContactManager::availableManagers() |
|
118 { |
|
119 QStringList ret; |
|
120 ret << QLatin1String("memory") << QLatin1String("invalid"); |
|
121 QContactManagerData::loadFactories(); |
|
122 ret.append(QContactManagerData::m_engines.keys()); |
|
123 |
|
124 // now swizzle the default engine to pole position |
|
125 #if defined(Q_CONTACTS_DEFAULT_ENGINE) |
|
126 if (ret.removeAll(QLatin1String(makename(Q_CONTACTS_DEFAULT_ENGINE)))) { |
|
127 ret.prepend(QLatin1String(makename(Q_CONTACTS_DEFAULT_ENGINE))); |
|
128 } |
|
129 #endif |
|
130 |
|
131 return ret; |
|
132 } |
|
133 |
|
134 /*! |
|
135 Splits the given \a uri into the manager, store, and parameters that it describes, and places the information into the memory addressed by \a pManagerId and \a pParams respectively. Returns true if \a uri could be split successfully, otherwise returns false |
|
136 */ |
|
137 bool QContactManager::parseUri(const QString& uri, QString* pManagerId, QMap<QString, QString>* pParams) |
|
138 { |
|
139 // Format: qtcontacts:<managerid>:<key>=<value>&<key>=<value> |
|
140 // 1) parameters are currently a qstringlist.. should they be a map? |
|
141 // 2) is the uri going to be escaped? my guess would be "probably not" |
|
142 // 3) hence, do we assume that the prefix, managerid and storeid cannot contain `:' |
|
143 // 4) similarly, that neither keys nor values can contain `=' or `&' |
|
144 |
|
145 QStringList colonSplit = uri.split(QLatin1Char(':')); |
|
146 QString prefix = colonSplit.value(0); |
|
147 |
|
148 if (prefix != QLatin1String("qtcontacts")) |
|
149 return false; |
|
150 |
|
151 QString managerName = colonSplit.value(1); |
|
152 |
|
153 if (managerName.trimmed().isEmpty()) |
|
154 return false; |
|
155 |
|
156 QString firstParts = prefix + QLatin1Char(':') + managerName + QLatin1Char(':'); |
|
157 QString paramString = uri.mid(firstParts.length()); |
|
158 |
|
159 QMap<QString, QString> outParams; |
|
160 |
|
161 // Now we have to decode each parameter |
|
162 if (!paramString.isEmpty()) { |
|
163 QStringList params = paramString.split(QRegExp(QLatin1String("&(?!(amp;|equ;))")), QString::KeepEmptyParts); |
|
164 // If we have an empty string for paramstring, we get one entry in params, |
|
165 // so skip that case. |
|
166 for(int i = 0; i < params.count(); i++) { |
|
167 /* This should be something like "foo&bar&equ;=grob&" */ |
|
168 QStringList paramChunk = params.value(i).split(QLatin1String("="), QString::KeepEmptyParts); |
|
169 |
|
170 if (paramChunk.count() != 2) |
|
171 return false; |
|
172 |
|
173 QString arg = paramChunk.value(0); |
|
174 QString param = paramChunk.value(1); |
|
175 arg.replace(QLatin1String("&equ;"), QLatin1String("=")); |
|
176 arg.replace(QLatin1String("&"), QLatin1String("&")); |
|
177 param.replace(QLatin1String("&equ;"), QLatin1String("=")); |
|
178 param.replace(QLatin1String("&"), QLatin1String("&")); |
|
179 if (arg.isEmpty()) |
|
180 return false; |
|
181 outParams.insert(arg, param); |
|
182 } |
|
183 } |
|
184 |
|
185 if (pParams) |
|
186 *pParams = outParams; |
|
187 if (pManagerId) |
|
188 *pManagerId = managerName; |
|
189 return true; |
|
190 } |
|
191 |
|
192 /*! Returns a URI that completely describes a manager implementation, datastore, and the parameters with which to instantiate the manager, from the given \a managerName, \a params and an optional \a implementationVersion */ |
|
193 QString QContactManager::buildUri(const QString& managerName, const QMap<QString, QString>& params, int implementationVersion) |
|
194 { |
|
195 QString ret(QLatin1String("qtcontacts:%1:%2")); |
|
196 // we have to escape each param |
|
197 QStringList escapedParams; |
|
198 QStringList keys = params.keys(); |
|
199 for (int i=0; i < keys.size(); i++) { |
|
200 QString key = keys.at(i); |
|
201 QString arg = params.value(key); |
|
202 arg = arg.replace(QLatin1Char('&'), QLatin1String("&")); |
|
203 arg = arg.replace(QLatin1Char('='), QLatin1String("&equ;")); |
|
204 key = key.replace(QLatin1Char('&'), QLatin1String("&")); |
|
205 key = key.replace(QLatin1Char('='), QLatin1String("&equ;")); |
|
206 key = key + QLatin1Char('=') + arg; |
|
207 escapedParams.append(key); |
|
208 } |
|
209 |
|
210 if (implementationVersion != -1) { |
|
211 QString versionString = QString(QLatin1String(QTCONTACTS_IMPLEMENTATION_VERSION_NAME)); |
|
212 versionString += QString::fromAscii("="); |
|
213 versionString += QString::number(implementationVersion); |
|
214 escapedParams.append(versionString); |
|
215 } |
|
216 |
|
217 return ret.arg(managerName, escapedParams.join(QLatin1String("&"))); |
|
218 } |
|
219 |
|
220 /*! |
|
221 Constructs a QContactManager whose implementation, store and parameters are specified in the given \a storeUri, |
|
222 and whose parent object is \a parent. |
|
223 */ |
|
224 QContactManager* QContactManager::fromUri(const QString& storeUri, QObject* parent) |
|
225 { |
|
226 if (storeUri.isEmpty()) { |
|
227 return new QContactManager(QString(), QMap<QString, QString>(), parent); |
|
228 } else { |
|
229 QString id; |
|
230 QMap<QString, QString> parameters; |
|
231 if (parseUri(storeUri, &id, ¶meters)) { |
|
232 return new QContactManager(id, parameters, parent); |
|
233 } else { |
|
234 // invalid |
|
235 return new QContactManager(QLatin1String("invalid"), QMap<QString, QString>(), parent); |
|
236 } |
|
237 } |
|
238 } |
|
239 |
|
240 /*! |
|
241 Constructs a QContactManager whose parent QObject is \a parent. |
|
242 The default implementation for the platform will be created. |
|
243 */ |
|
244 QContactManager::QContactManager(QObject* parent) |
|
245 : QObject(parent) |
|
246 { |
|
247 createEngine(QString(), QMap<QString, QString>()); |
|
248 } |
|
249 |
|
250 /*! |
|
251 Constructs a QContactManager whose implementation is identified by \a managerName with the given \a parameters. |
|
252 |
|
253 The \a parent QObject will be used as the parent of this QContactManager. |
|
254 |
|
255 If an empty \a managerName is specified, the default implementation for the platform will |
|
256 be used. |
|
257 */ |
|
258 QContactManager::QContactManager(const QString& managerName, const QMap<QString, QString>& parameters, QObject* parent) |
|
259 : QObject(parent), |
|
260 d(new QContactManagerData) |
|
261 { |
|
262 createEngine(managerName, parameters); |
|
263 } |
|
264 |
|
265 void QContactManager::createEngine(const QString& managerName, const QMap<QString, QString>& parameters) |
|
266 { |
|
267 d->createEngine(managerName, parameters); |
|
268 connect(d->m_engine, SIGNAL(dataChanged()), this, SIGNAL(dataChanged())); |
|
269 connect(d->m_engine, SIGNAL(contactsAdded(QList<QContactLocalId>)), this, SIGNAL(contactsAdded(QList<QContactLocalId>))); |
|
270 connect(d->m_engine, SIGNAL(contactsChanged(QList<QContactLocalId>)), this, SIGNAL(contactsChanged(QList<QContactLocalId>))); |
|
271 connect(d->m_engine, SIGNAL(contactsRemoved(QList<QContactLocalId>)), this, SIGNAL(contactsRemoved(QList<QContactLocalId>))); |
|
272 connect(d->m_engine, SIGNAL(relationshipsAdded(QList<QContactLocalId>)), this, SIGNAL(relationshipsAdded(QList<QContactLocalId>))); |
|
273 connect(d->m_engine, SIGNAL(relationshipsRemoved(QList<QContactLocalId>)), this, SIGNAL(relationshipsRemoved(QList<QContactLocalId>))); |
|
274 connect(d->m_engine, SIGNAL(selfContactIdChanged(QContactLocalId,QContactLocalId)), this, SIGNAL(selfContactIdChanged(QContactLocalId,QContactLocalId))); |
|
275 } |
|
276 |
|
277 /*! |
|
278 Constructs a QContactManager whose backend has the name \a managerName and version \a implementationVersion, where the manager |
|
279 is constructed with the provided \a parameters. |
|
280 |
|
281 The \a parent QObject will be used as the parent of this QContactManager. |
|
282 |
|
283 If an empty \a managerName is specified, the default implementation for the platform will be instantiated. |
|
284 If the specified implementation version is not available, the manager with the name \a managerName with the default implementation version is instantiated. |
|
285 */ |
|
286 QContactManager::QContactManager(const QString& managerName, int implementationVersion, const QMap<QString, QString>& parameters, QObject* parent) |
|
287 : QObject(parent), |
|
288 d(new QContactManagerData) |
|
289 { |
|
290 QMap<QString, QString> params = parameters; |
|
291 params[QString(QLatin1String(QTCONTACTS_IMPLEMENTATION_VERSION_NAME))] = QString::number(implementationVersion); |
|
292 createEngine(managerName, params); |
|
293 } |
|
294 |
|
295 /*! Frees the memory used by the QContactManager */ |
|
296 QContactManager::~QContactManager() |
|
297 { |
|
298 delete d; |
|
299 } |
|
300 |
|
301 /*! |
|
302 \enum QContactManager::Error |
|
303 |
|
304 This enum specifies an error that occurred during the most recent operation: |
|
305 |
|
306 \value NoError The most recent operation was successful |
|
307 \value DoesNotExistError The most recent operation failed because the requested contact or detail definition does not exist |
|
308 \value AlreadyExistsError The most recent operation failed because the specified contact or detail definition already exists |
|
309 \value InvalidDetailError The most recent operation failed because the specified contact contains details which do not conform to their definition |
|
310 \value InvalidRelationshipError The most recent operation failed because the specified relationship is circular or references an invalid local contact |
|
311 \value InvalidContactTypeError The most recent operation failed because the contact type specified was not valid for the operation |
|
312 \value LockedError The most recent operation failed because the datastore specified is currently locked |
|
313 \value DetailAccessError The most recent operation failed because a detail was modified or removed and its access method does not allow that |
|
314 \value PermissionsError The most recent operation failed because the caller does not have permission to perform the operation |
|
315 \value OutOfMemoryError The most recent operation failed due to running out of memory |
|
316 \value VersionMismatchError The most recent operation failed because the backend of the manager is not of the required version |
|
317 \value LimitReachedError The most recent operation failed because the limit for that type of object has been reached |
|
318 \value NotSupportedError The most recent operation failed because the requested operation is not supported in the specified store |
|
319 \value BadArgumentError The most recent operation failed because one or more of the parameters to the operation were invalid |
|
320 \value UnspecifiedError The most recent operation failed for an undocumented reason |
|
321 */ |
|
322 |
|
323 /*! Return the error code of the most recent operation */ |
|
324 QContactManager::Error QContactManager::error() const |
|
325 { |
|
326 return d->m_error; |
|
327 } |
|
328 |
|
329 /*! |
|
330 Return the list of contact ids, sorted according to the given list of \a sortOrders |
|
331 */ |
|
332 QList<QContactLocalId> QContactManager::contactIds(const QList<QContactSortOrder>& sortOrders) const |
|
333 { |
|
334 return d->m_engine->contactIds(sortOrders, d->m_error); |
|
335 } |
|
336 |
|
337 /*! |
|
338 Returns a list of contact ids that match the given \a filter, sorted according to the given list of \a sortOrders. |
|
339 Depending on the backend, this filtering operation may involve retrieving all the contacts. |
|
340 */ |
|
341 QList<QContactLocalId> QContactManager::contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders) const |
|
342 { |
|
343 return d->m_engine->contactIds(filter, sortOrders, d->m_error); |
|
344 } |
|
345 |
|
346 /*! |
|
347 Returns the list of contacts stored in the manager sorted according to the given list of \a sortOrders. |
|
348 |
|
349 The \a definitionRestrictions parameter describes the details that are of |
|
350 interest, as a performance hint. If the list is empty, all existing details for the matching |
|
351 contacts will be returned. Otherwise, the returned contacts may only contain details of the |
|
352 supplied definition names, although the manager is free to return extra details. |
|
353 */ |
|
354 QList<QContact> QContactManager::contacts(const QList<QContactSortOrder>& sortOrders, const QStringList& definitionRestrictions) const |
|
355 { |
|
356 return d->m_engine->contacts(sortOrders, definitionRestrictions, d->m_error); |
|
357 } |
|
358 |
|
359 /*! |
|
360 Returns a list of contacts that match the given \a filter, sorted according to the given list of \a sortOrders. |
|
361 |
|
362 Depending on the manager implementation, this filtering operation might be slow and involve retrieving all the |
|
363 contacts and testing them against the supplied filter - see the \l isFilterSupported() function. |
|
364 |
|
365 The \a definitionRestrictions parameter describes the details that are of |
|
366 interest, as a performance hint. If the list is empty, all existing details for the matching |
|
367 contacts will be returned. Otherwise, the returned contacts may only contain details of the |
|
368 supplied definition names, although the manager is free to return extra details. |
|
369 */ |
|
370 QList<QContact> QContactManager::contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, const QStringList& definitionRestrictions) const |
|
371 { |
|
372 return d->m_engine->contacts(filter, sortOrders, definitionRestrictions, d->m_error); |
|
373 } |
|
374 |
|
375 /*! |
|
376 Returns the contact in the database identified by \a contactId. |
|
377 |
|
378 If the contact does not exist, an empty, default constructed QContact will be returned, |
|
379 and the error returned by \l error() will be \c QContactManager::DoesNotExistError. |
|
380 |
|
381 The \a definitionRestrictions parameter describes the details that are of |
|
382 interest, as a performance hint. If the list is empty, all existing details for the requested |
|
383 contact will be returned. Otherwise, the returned contact may only contain details of the |
|
384 supplied definition names, although the manager is free to return extra details. |
|
385 */ |
|
386 QContact QContactManager::contact(const QContactLocalId& contactId, const QStringList& definitionRestrictions) const |
|
387 { |
|
388 return d->m_engine->contact(contactId, definitionRestrictions, d->m_error); |
|
389 } |
|
390 |
|
391 /*! |
|
392 Adds the given \a contact to the database if \a contact has a |
|
393 default-constructed id, or an id with the manager URI set to the URI of |
|
394 this manager and a local id of zero. |
|
395 |
|
396 If the manager URI of the id of the \a contact is neither empty nor equal to the URI of |
|
397 this manager, or local id of the \a contact is non-zero but does not exist in the |
|
398 manager, the operation will fail and calling error() will return |
|
399 \c QContactManager::DoesNotExistError. |
|
400 |
|
401 Alternatively, the function will update the existing contact in the database if \a contact |
|
402 has a non-zero id and currently exists in the database. |
|
403 |
|
404 If the \a contact contains one or more details whose definitions have |
|
405 not yet been saved with the manager, the operation will fail and calling |
|
406 error() will return \c QContactManager::UnsupportedError. |
|
407 |
|
408 If the \a contact has had its relationships reordered, the manager |
|
409 will check to make sure that every relationship that the contact is currently |
|
410 involved in is included in the reordered list, and that no relationships which |
|
411 either do not involve the contact, or have not been saved in the manager are |
|
412 included in the list. If these conditions are not met, the function will |
|
413 return \c false and calling error() will return |
|
414 \c QContactManager::InvalidRelationshipError. |
|
415 |
|
416 Returns false on failure, or true on |
|
417 success. On successful save of a contact with an id of zero, its |
|
418 id will be set to a new, valid id with the manager URI set to the URI of |
|
419 this manager, and the local id set to a new, valid local id. |
|
420 The manager will automatically synthesize the display label of the contact when it is saved. |
|
421 The manager is not required to fetch updated details of the contact on save, |
|
422 and as such, clients should fetch a contact if they want the most up-to-date information |
|
423 by calling \l QContactManager::contact(). |
|
424 |
|
425 \sa managerUri() |
|
426 */ |
|
427 bool QContactManager::saveContact(QContact* contact) |
|
428 { |
|
429 return d->m_engine->saveContact(contact, d->m_error); |
|
430 } |
|
431 |
|
432 /*! |
|
433 Remove the contact identified by \a contactId from the database, |
|
434 and also removes any relationships in which the contact was involved. |
|
435 Returns true if the contact was removed successfully, otherwise |
|
436 returns false. |
|
437 */ |
|
438 bool QContactManager::removeContact(const QContactLocalId& contactId) |
|
439 { |
|
440 return d->m_engine->removeContact(contactId, d->m_error); |
|
441 } |
|
442 |
|
443 /*! |
|
444 \internal |
|
445 Adds the list of contacts given by \a contactList to the database. |
|
446 Returns a list of the error codes corresponding to the contacts in |
|
447 the \a contactList. The \l QContactManager::error() function will |
|
448 only return \c QContactManager::NoError if all contacts were saved |
|
449 successfully. |
|
450 |
|
451 For each newly saved contact that was successful, the uid of the contact |
|
452 in the list will be updated with the new value. If a failure occurs |
|
453 when saving a new contact, the id will be cleared. If a failure occurs |
|
454 when updating a contact that already exists, then TODO. |
|
455 |
|
456 This function was deprecated in week 1 and will be removed after the transition period has elapsed. |
|
457 |
|
458 \sa QContactManager::saveContact() |
|
459 */ |
|
460 QList<QContactManager::Error> QContactManager::saveContacts(QList<QContact>* contactList) |
|
461 { |
|
462 if (contactList) { |
|
463 QMap<int, QContactManager::Error> errorMap; |
|
464 QList<QContactManager::Error> errorList; |
|
465 int size = contactList->size(); |
|
466 d->m_engine->saveContacts(contactList, &errorMap, d->m_error); |
|
467 |
|
468 for (int j=0; j < size; j++) { |
|
469 if (errorMap.contains(j)) |
|
470 errorList << errorMap.value(j); |
|
471 else |
|
472 errorList << QContactManager::NoError; |
|
473 } |
|
474 return errorList; |
|
475 } else { |
|
476 d->m_error = QContactManager::BadArgumentError; |
|
477 return QList<QContactManager::Error>(); |
|
478 } |
|
479 } |
|
480 |
|
481 /*! |
|
482 Adds the list of contacts given by \a contacts list to the database. |
|
483 Returns true if the contacts were saved successfully, otherwise false. |
|
484 |
|
485 The manager might populate \a errorMap (the map of indices of the \a contacts list to |
|
486 the error which occurred when saving the contact at that index) for |
|
487 every index for which the contact could not be saved, if it is able. |
|
488 The \l QContactManager::error() function will only return \c QContactManager::NoError |
|
489 if all contacts were saved successfully. |
|
490 |
|
491 For each newly saved contact that was successful, the id of the contact |
|
492 in the \a contacts list will be updated with the new value. If a failure occurs |
|
493 when saving a new contact, the id will be cleared. |
|
494 |
|
495 \sa QContactManager::saveContact() |
|
496 */ |
|
497 bool QContactManager::saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap) |
|
498 { |
|
499 return d->m_engine->saveContacts(contacts, errorMap, d->m_error); |
|
500 } |
|
501 |
|
502 /*! |
|
503 Remove every contact whose id is contained in the list of contacts ids |
|
504 \a contactIds. Returns true if all contacts were removed successfully, |
|
505 otherwise false. |
|
506 |
|
507 The manager might populate \a errorMap (the map of indices of the \a contactIds list to |
|
508 the error which occurred when saving the contact at that index) for every |
|
509 index for which the contact could not be removed, if it is able. |
|
510 The \l QContactManager::error() function will |
|
511 only return \c QContactManager::NoError if all contacts were removed |
|
512 successfully. |
|
513 |
|
514 For each contact that was removed succesfully, the corresponding |
|
515 id in the \a contactIds list will be retained but set to zero. The id of contacts |
|
516 that were not successfully removed will be left alone. |
|
517 |
|
518 Any contact that was removed successfully will have the relationships |
|
519 in which it was involved removed also. |
|
520 |
|
521 \sa QContactManager::removeContact() |
|
522 */ |
|
523 bool QContactManager::removeContacts(QList<QContactLocalId>* contactIds, QMap<int, QContactManager::Error>* errorMap) |
|
524 { |
|
525 return d->m_engine->removeContacts(contactIds, errorMap, d->m_error); |
|
526 } |
|
527 |
|
528 /*! |
|
529 \internal |
|
530 Remove the list of contacts identified in \a idList. |
|
531 Returns a list of the error codes corresponding to the contact ids in |
|
532 the \a idList. The \l QContactManager::error() function will |
|
533 only return \c QContactManager::NoError if all contacts were removed |
|
534 successfully. |
|
535 |
|
536 For each contact that was removed succesfully, the corresponding |
|
537 id in the list will be retained but set to zero. The id of contacts |
|
538 that were not successfully removed will be left alone. |
|
539 |
|
540 Any contact that was removed successfully will have the relationships |
|
541 in which it was involved removed also. |
|
542 |
|
543 This function was deprecated in week 1 and will be removed after the transition period has elapsed. |
|
544 |
|
545 \sa QContactManager::removeContact() |
|
546 */ |
|
547 QList<QContactManager::Error> QContactManager::removeContacts(QList<QContactLocalId>* idList) |
|
548 { |
|
549 if (idList) { |
|
550 QMap<int, QContactManager::Error> errorMap; |
|
551 QList<QContactManager::Error> errorList; |
|
552 int size = idList->size(); |
|
553 d->m_engine->removeContacts(idList, &errorMap, d->m_error); |
|
554 |
|
555 for (int j=0; j < size; j++) { |
|
556 if (errorMap.contains(j)) |
|
557 errorList << errorMap.value(j); |
|
558 else |
|
559 errorList << QContactManager::NoError; |
|
560 } |
|
561 return errorList; |
|
562 } else { |
|
563 d->m_error = QContactManager::BadArgumentError; |
|
564 return QList<QContactManager::Error>(); |
|
565 } |
|
566 } |
|
567 |
|
568 /*! |
|
569 Returns a display label for a \a contact which is synthesized from its details in a platform-specific manner |
|
570 */ |
|
571 QString QContactManager::synthesizedDisplayLabel(const QContact& contact) const |
|
572 { |
|
573 return d->m_engine->synthesizedDisplayLabel(contact, d->m_error); |
|
574 } |
|
575 |
|
576 /*! |
|
577 Sets the id of the "self" contact to the given \a contactId. |
|
578 Returns true if the "self" contact id was set successfully. |
|
579 If the given \a contactId does not identify a contact |
|
580 stored in this manager, the error will be set to |
|
581 \c QContactManager::DoesNotExistError and the function will |
|
582 return false; if the backend does not support the |
|
583 concept of a "self" contact then the error will be set to |
|
584 \c QContactManager::NotSupportedError and the function will |
|
585 return false. |
|
586 */ |
|
587 bool QContactManager::setSelfContactId(const QContactLocalId& contactId) |
|
588 { |
|
589 return d->m_engine->setSelfContactId(contactId, d->m_error); |
|
590 } |
|
591 |
|
592 /*! |
|
593 Returns the id of the "self" contact which has previously been set. |
|
594 If no "self" contact has been set, or if the self contact was removed |
|
595 from the manager after being set, or if the backend does not support |
|
596 the concept of a "self" contact, an invalid id will be returned |
|
597 and the error will be set to \c QContactManager::DoesNotExistError. |
|
598 */ |
|
599 QContactLocalId QContactManager::selfContactId() const |
|
600 { |
|
601 return d->m_engine->selfContactId(d->m_error); |
|
602 } |
|
603 |
|
604 /*! |
|
605 Returns a list of relationships in which the contact identified by the given \a participantId participates in the given \a role. |
|
606 If \a participantId is the default-constructed id, \a role is ignored and all relationships are returned. |
|
607 */ |
|
608 QList<QContactRelationship> QContactManager::relationships(const QContactId& participantId, QContactRelationshipFilter::Role role) const |
|
609 { |
|
610 return d->m_engine->relationships(QString(), participantId, role, d->m_error); |
|
611 } |
|
612 |
|
613 /*! |
|
614 Returns a list of relationships of the given \a relationshipType in which the contact identified by the given \a participantId participates in the given \a role. |
|
615 If \a participantId is the default-constructed id, \a role is ignored and all relationships of the given \a relationshipType are returned. |
|
616 If \a relationshipType is empty, relationships of any type are returned. |
|
617 */ |
|
618 QList<QContactRelationship> QContactManager::relationships(const QString& relationshipType, const QContactId& participantId, QContactRelationshipFilter::Role role) const |
|
619 { |
|
620 return d->m_engine->relationships(relationshipType, participantId, role, d->m_error); |
|
621 } |
|
622 |
|
623 /*! |
|
624 Saves the given \a relationship in the database. If the relationship already exists in the database, this function will |
|
625 return \c false and the error will be set to \c QContactManager::AlreadyExistsError. |
|
626 If the relationship is saved successfully, this function will return \c true and error will be set |
|
627 to \c QContactManager::NoError. Note that relationships cannot be updated directly using this function; in order |
|
628 to update a relationship, you must remove the old relationship, make the required modifications, and then save it. |
|
629 |
|
630 The given relationship is invalid if it is circular (one of the destination contacts is also the source contact), or |
|
631 if it references a non-existent local contact (either source or destination). If the given \a relationship is invalid, |
|
632 the function will return \c false and the error will be set to \c QContactManager::InvalidRelationshipError. |
|
633 If the given \a relationship could not be saved in the database (due to backend limitations) |
|
634 the function will return \c false and error will be set to \c QContactManager::NotSupportedError. |
|
635 |
|
636 If any destination contact manager URI is not set in the \a relationship, these will be |
|
637 automatically set to the URI of this manager, before the relationship is saved. |
|
638 */ |
|
639 bool QContactManager::saveRelationship(QContactRelationship* relationship) |
|
640 { |
|
641 return d->m_engine->saveRelationship(relationship, d->m_error); |
|
642 } |
|
643 |
|
644 /*! |
|
645 Saves the given \a relationships in the database and returns a list of error codes. |
|
646 */ |
|
647 QList<QContactManager::Error> QContactManager::saveRelationships(QList<QContactRelationship>* relationships) |
|
648 { |
|
649 return d->m_engine->saveRelationships(relationships, d->m_error); |
|
650 } |
|
651 |
|
652 /*! |
|
653 Removes the given \a relationship from the manager. If the relationship exists in the manager, the relationship |
|
654 will be removed, the error will be set to \c QContactManager::NoError and this function will return true. If no such |
|
655 relationship exists in the manager, the error will be set to \c QContactManager::DoesNotExistError and this function |
|
656 will return false. |
|
657 |
|
658 The priority of the relationship is ignored when determining existence of the relationship. |
|
659 */ |
|
660 bool QContactManager::removeRelationship(const QContactRelationship& relationship) |
|
661 { |
|
662 return d->m_engine->removeRelationship(relationship, d->m_error); |
|
663 } |
|
664 |
|
665 /*! |
|
666 Removes the given \a relationships from the database and returns a list of error codes. |
|
667 */ |
|
668 QList<QContactManager::Error> QContactManager::removeRelationships(const QList<QContactRelationship>& relationships) |
|
669 { |
|
670 return d->m_engine->removeRelationships(relationships, d->m_error); |
|
671 } |
|
672 |
|
673 /*! |
|
674 Returns a map of identifier to detail definition for the registered detail definitions which are valid for contacts whose type is the given \a contactType |
|
675 which are valid for the contacts in this store |
|
676 */ |
|
677 QMap<QString, QContactDetailDefinition> QContactManager::detailDefinitions(const QString& contactType) const |
|
678 { |
|
679 if (!supportedContactTypes().contains(contactType)) { |
|
680 d->m_error = QContactManager::InvalidContactTypeError; |
|
681 return QMap<QString, QContactDetailDefinition>(); |
|
682 } |
|
683 |
|
684 return d->m_engine->detailDefinitions(contactType, d->m_error); |
|
685 } |
|
686 |
|
687 /*! Returns the definition identified by the given \a definitionName that is valid for the contacts whose type is the given \a contactType in this store, or a default-constructed QContactDetailDefinition if no such definition exists */ |
|
688 QContactDetailDefinition QContactManager::detailDefinition(const QString& definitionName, const QString& contactType) const |
|
689 { |
|
690 if (!supportedContactTypes().contains(contactType)) { |
|
691 d->m_error = QContactManager::InvalidContactTypeError; |
|
692 return QContactDetailDefinition(); |
|
693 } |
|
694 |
|
695 return d->m_engine->detailDefinition(definitionName, contactType, d->m_error); |
|
696 } |
|
697 |
|
698 /*! Persists the given definition \a def in the database, which is valid for contacts whose type is the given \a contactType. Returns true if the definition was saved successfully, otherwise returns false */ |
|
699 bool QContactManager::saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType) |
|
700 { |
|
701 if (!supportedContactTypes().contains(contactType)) { |
|
702 d->m_error = QContactManager::InvalidContactTypeError; |
|
703 return false; |
|
704 } |
|
705 |
|
706 return d->m_engine->saveDetailDefinition(def, contactType, d->m_error); |
|
707 } |
|
708 |
|
709 /*! Removes the detail definition identified by \a definitionName from the database, which is valid for contacts whose type is the given \a contactType. Returns true if the definition was removed successfully, otherwise returns false */ |
|
710 bool QContactManager::removeDetailDefinition(const QString& definitionName, const QString& contactType) |
|
711 { |
|
712 if (!supportedContactTypes().contains(contactType)) { |
|
713 d->m_error = QContactManager::InvalidContactTypeError; |
|
714 return false; |
|
715 } |
|
716 |
|
717 return d->m_engine->removeDetailDefinition(definitionName, contactType, d->m_error); |
|
718 } |
|
719 |
|
720 /*! |
|
721 \enum QContactManager::ManagerFeature |
|
722 This enum describes the possible features that a particular manager may support |
|
723 \value Groups The manager supports all QContactGroup related operations, and emits the appropriate signals |
|
724 \value ActionPreferences The manager supports saving preferred details per action per contact |
|
725 \value DetailOrdering When a contact is retrieved, the manager will return the details in the same order in which they were saved |
|
726 \value Relationships The manager supports at least some types of relationships between contacts |
|
727 \value ArbitraryRelationshipTypes The manager supports relationships of arbitrary types between contacts |
|
728 \value RelationshipOrdering The manager supports relationships (re)ordering |
|
729 \value MutableDefinitions The manager supports saving, updating or removing detail definitions. Some built-in definitions may still be immutable |
|
730 \value SelfContact The manager supports the concept of saving a contact which represents the current user |
|
731 \value ChangeLogs The manager supports reporting of timestamps of changes, and filtering and sorting by those timestamps |
|
732 \value Anonymous The manager is isolated from other managers |
|
733 */ |
|
734 |
|
735 /*! |
|
736 Returns true if the given feature \a feature is supported by the manager, for the specified type of contact \a contactType |
|
737 */ |
|
738 bool QContactManager::hasFeature(QContactManager::ManagerFeature feature, const QString& contactType) const |
|
739 { |
|
740 return d->m_engine->hasFeature(feature, contactType); |
|
741 } |
|
742 |
|
743 /*! |
|
744 Returns the list of data types supported by the manager |
|
745 */ |
|
746 QList<QVariant::Type> QContactManager::supportedDataTypes() const |
|
747 { |
|
748 return d->m_engine->supportedDataTypes(); |
|
749 } |
|
750 |
|
751 /*! |
|
752 Returns true if the given \a filter is supported natively by the |
|
753 manager, and false if the filter behaviour would be emulated. |
|
754 |
|
755 Note: In some cases, the behaviour of an unsupported filter |
|
756 cannot be emulated. For example, a filter that requests contacts |
|
757 that have changed since a given time depends on having that information |
|
758 available. In these cases, the filter will fail. |
|
759 */ |
|
760 bool QContactManager::isFilterSupported(const QContactFilter& filter) const |
|
761 { |
|
762 return d->m_engine->isFilterSupported(filter); |
|
763 } |
|
764 |
|
765 /*! |
|
766 Returns the list of relationship types which are supported by this manager where contacts of the |
|
767 given type \a contactType may be the first (dominant) contact in the relationship. |
|
768 If the backend does not support the \c QContactManager::Relationships feature, this list should |
|
769 be empty. If the backend supports the \c QContactManager::Relationships feature and also |
|
770 supports the \c QContactManager::ArbitraryRelationshipTypes feature, the list will |
|
771 contain the natively supported (well-known) relationship types contained in the list, but clients |
|
772 are able to add relationships of any custom type also. |
|
773 |
|
774 \sa QContactRelationship::first() |
|
775 */ |
|
776 QStringList QContactManager::supportedRelationshipTypes(const QString& contactType) const |
|
777 { |
|
778 return d->m_engine->supportedRelationshipTypes(contactType); |
|
779 } |
|
780 |
|
781 /*! |
|
782 Returns the list of contact types which are supported by this manager. |
|
783 This is a convenience function, equivalent to retrieving the allowable values |
|
784 for the \c QContactType::FieldType field of the QContactType definition |
|
785 which is valid in this manager. |
|
786 */ |
|
787 QStringList QContactManager::supportedContactTypes() const |
|
788 { |
|
789 return d->m_engine->supportedContactTypes(); |
|
790 } |
|
791 |
|
792 /*! |
|
793 Returns the engine backend implementation version number |
|
794 */ |
|
795 int QContactManager::managerVersion() const |
|
796 { |
|
797 return d->m_engine->managerVersion(); |
|
798 } |
|
799 |
|
800 /*! Returns the manager name for this QContactManager */ |
|
801 QString QContactManager::managerName() const |
|
802 { |
|
803 return d->m_engine->managerName(); |
|
804 } |
|
805 |
|
806 /*! Return the parameters relevant to the creation of this QContactManager */ |
|
807 QMap<QString, QString> QContactManager::managerParameters() const |
|
808 { |
|
809 QMap<QString, QString> params = d->m_engine->managerParameters(); |
|
810 |
|
811 params.remove(QString::fromAscii(QTCONTACTS_VERSION_NAME)); |
|
812 params.remove(QString::fromAscii(QTCONTACTS_IMPLEMENTATION_VERSION_NAME)); |
|
813 return params; |
|
814 } |
|
815 |
|
816 /*! |
|
817 Return the uri describing this QContactManager, consisting of the manager name and any parameters. |
|
818 */ |
|
819 QString QContactManager::managerUri() const |
|
820 { |
|
821 return d->m_engine->managerUri(); |
|
822 } |
|
823 |
|
824 #include "moc_qcontactmanager.cpp" |
|
825 |
|
826 QTM_END_NAMESPACE |