1
/****************************************************************************
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4
** Contact: http://www.qt-project.org/legal
6
** This file is part of the QtContacts module of the Qt Toolkit.
8
** $QT_BEGIN_LICENSE:LGPL$
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 Digia. For licensing terms and
14
** conditions see http://qt.digia.com/licensing. For further information
15
** use the contact form at http://qt.digia.com/contact-us.
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 as published by the Free Software
20
** Foundation and appearing in the file LICENSE.LGPL included in the
21
** packaging of this file. Please review the following information to
22
** ensure the GNU Lesser General Public License version 2.1 requirements
23
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25
** In addition, as a special exception, Digia gives you certain additional
26
** rights. These rights are described in the Digia Qt LGPL Exception
27
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29
** GNU General Public License Usage
30
** Alternatively, this file may be used under the terms of the GNU
31
** General Public License version 3.0 as published by the Free Software
32
** Foundation and appearing in the file LICENSE.GPL included in the
33
** packaging of this file. Please review the following information to
34
** ensure the GNU General Public License version 3.0 requirements will be
35
** met: http://www.gnu.org/copyleft/gpl.html.
40
****************************************************************************/
42
#include "qcontactmanager.h"
44
#include "qcontact_p.h"
45
#include "qcontactfilter.h"
46
#include "qcontactmanager_p.h"
47
#include "qcontactfetchhint.h"
49
#include <QMetaMethod>
50
#include <QSharedData>
54
QT_BEGIN_NAMESPACE_CONTACTS
56
\class QContactManager
57
\brief The QContactManager class provides an interface which allows clients with access to contact information stored in a particular backend.
60
\ingroup contacts-main
62
This class provides an abstraction of a datastore or aggregation of datastores which contains contact information.
63
It provides methods to retrieve and manipulate contact information and contact relationship information.
64
It also provides metadata and error information reporting.
66
The functions provided by QContactManager are purely synchronous; to access the same functionality in an
67
asynchronous manner, clients should use the use-case-specific classes derived from QContactAbstractRequest.
69
Some functionality provided by QContactManager directly is not accessible using the asynchronous API. See
70
the \l{Qt Contacts Synchronous API}{synchronous} and \l{Qt Contacts Asynchronous API}{asynchronous} API
71
information in the \l{Qt Contacts C++ API} documentation.
75
\fn QContactManager::dataChanged()
76
This signal is emitted by the manager if its internal state changes, and it is unable to determine the changes
77
which occurred, or if the manager considers the changes to be radical enough to require clients to reload all data.
78
If this signal is emitted, no other signals will be emitted for the associated changes.
82
\fn QContactManager::contactsAdded(const QList<QContactId>& contactIds)
83
This signal is emitted at some point once the contacts identified by \a contactIds have been added to a datastore managed by this manager.
84
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
88
\fn QContactManager::contactsChanged(const QList<QContactId>& contactIds)
89
This signal is emitted at some point once the contacts identified by \a contactIds have been modified in a datastore managed by this manager.
90
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
94
\fn QContactManager::contactsRemoved(const QList<QContactId>& contactIds)
95
This signal is emitted at some point once the contacts identified by \a contactIds have been removed from a datastore managed by this manager.
96
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
100
\fn QContactManager::relationshipsAdded(const QList<QContactId>& affectedContactIds)
101
This signal is emitted at some point after relationships have been added to the manager which involve the contacts identified by \a affectedContactIds.
102
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
106
\fn QContactManager::relationshipsRemoved(const QList<QContactId>& affectedContactIds)
107
This signal is emitted at some point after relationships have eben removed from the manager which involve the contacts identified by \a affectedContactIds.
108
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
112
\fn QContactManager::selfContactIdChanged(const QContactId& oldId, const QContactId& newId)
113
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.
114
If the \a newId is the invalid, then the self contact was deleted or no self contact exists.
115
This signal must not be emitted if the dataChanged() signal was previously emitted for this change.
120
#define makestr(x) (#x)
121
#define makename(x) makestr(x)
124
Returns a list of available manager ids that can be used when constructing
125
a QContactManager. If an empty id is specified to the constructor, the
126
first value in this list will be used instead.
128
The QTCONTACTS_MANAGER_OVERRIDE environment variable may be set to
129
override the default engine.
131
QStringList QContactManager::availableManagers()
134
QContactManagerData::loadFactoriesMetadata();
135
ret = QContactManagerData::m_managerNames;
137
ret << QStringLiteral("invalid");
139
// now swizzle the default engine to pole position
140
#if defined(Q_CONTACTS_DEFAULT_ENGINE)
141
const QString defaultManagerName = QString::fromLatin1(makename(Q_CONTACTS_DEFAULT_ENGINE));
142
if (ret.removeAll(defaultManagerName)) {
143
ret.prepend(defaultManagerName);
147
// and prefer the override engine if specified in the environment
148
const QString overrideManagerName = QString::fromLatin1(qgetenv("QTCONTACTS_MANAGER_OVERRIDE"));
149
if (!overrideManagerName.isEmpty() && ret.contains(overrideManagerName)) {
150
ret.removeAll(overrideManagerName);
151
ret.prepend(overrideManagerName);
154
// bump memory to the end of the list
155
if (ret.removeAll(QStringLiteral("memory")))
156
ret.append(QStringLiteral("memory"));
162
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
164
bool QContactManager::parseUri(const QString &uri, QString *pManagerId, QMap<QString, QString> *pParams)
166
// Format: qtcontacts:<managerid>:<key>=<value>&<key>=<value>
167
// 1) parameters are currently a qstringlist.. should they be a map?
168
// 2) is the uri going to be escaped? my guess would be "probably not"
169
// 3) hence, do we assume that the prefix, managerid and storeid cannot contain `:'
170
// 4) similarly, that neither keys nor values can contain `=' or `&'
172
QStringList colonSplit = uri.split(QLatin1Char(':'));
173
QString prefix = colonSplit.value(0);
175
if (prefix != QStringLiteral("qtcontacts"))
178
QString managerName = colonSplit.value(1);
180
if (managerName.trimmed().isEmpty())
183
QString firstParts = prefix + QLatin1Char(':') + managerName + QLatin1Char(':');
184
QString paramString = uri.mid(firstParts.length());
186
QMap<QString, QString> outParams;
188
// Now we have to decode each parameter
189
if (!paramString.isEmpty()) {
190
QStringList params = paramString.split(QRegExp(QStringLiteral("&(?!(amp;|equ;))")), QString::KeepEmptyParts);
191
// If we have an empty string for paramstring, we get one entry in params,
192
// so skip that case.
193
for(int i = 0; i < params.count(); i++) {
194
/* This should be something like "foo&bar&equ;=grob&" */
195
QStringList paramChunk = params.value(i).split(QStringLiteral("="), QString::KeepEmptyParts);
197
if (paramChunk.count() != 2)
200
QString arg = paramChunk.value(0);
201
QString param = paramChunk.value(1);
202
arg.replace(QStringLiteral("&equ;"), QStringLiteral("="));
203
arg.replace(QStringLiteral("&"), QStringLiteral("&"));
204
param.replace(QStringLiteral("&equ;"), QStringLiteral("="));
205
param.replace(QStringLiteral("&"), QStringLiteral("&"));
208
outParams.insert(arg, param);
213
*pParams = outParams;
215
*pManagerId = managerName;
220
Returns a URI that completely describes a manager implementation, datastore, and the parameters
221
with which to instantiate the manager, from the given \a managerName, \a params and an optional
222
\a implementationVersion. This function is generally useful only if you intend to construct a
223
manager with the \l fromUri() function, or wish to construct a contact id
224
manually (for synchronization or other purposes). Most clients will not need to use this function.
226
QString QContactManager::buildUri(const QString &managerName, const QMap<QString, QString> ¶ms, int implementationVersion)
228
QString ret(QStringLiteral("qtcontacts:%1:%2"));
229
// we have to escape each param
230
QStringList escapedParams;
231
QStringList keys = params.keys();
232
for (int i=0; i < keys.size(); i++) {
233
QString key = keys.at(i);
234
QString arg = params.value(key);
235
arg = QContactId::escapeUriParam(arg);
236
key = QContactId::escapeUriParam(key);
237
key = key + QLatin1Char('=') + arg;
238
escapedParams.append(key);
241
if (implementationVersion != -1) {
242
QString versionString = QString(QStringLiteral(QTCONTACTS_IMPLEMENTATION_VERSION_NAME));
243
versionString += QString::fromLatin1("=");
244
versionString += QString::number(implementationVersion);
245
escapedParams.append(versionString);
248
return ret.arg(managerName, escapedParams.join(QStringLiteral("&")));
252
Constructs a QContactManager whose implementation version, manager name and specific parameters
253
are specified in the given \a managerUri, and whose parent object is \a parent.
255
QContactManager* QContactManager::fromUri(const QString &managerUri, QObject *parent)
257
if (managerUri.isEmpty()) {
258
return new QContactManager(QString(), QMap<QString, QString>(), parent);
261
QMap<QString, QString> parameters;
262
if (parseUri(managerUri, &id, ¶meters)) {
263
return new QContactManager(id, parameters, parent);
266
return new QContactManager(QStringLiteral("invalid"), QMap<QString, QString>(), parent);
272
Constructs a QContactManager whose parent QObject is \a parent.
273
The default implementation for the platform will be created.
275
QContactManager::QContactManager(QObject *parent)
277
d(new QContactManagerData)
279
createEngine(QString(), QMap<QString, QString>());
283
Constructs a QContactManager whose implementation is identified by \a managerName with the given \a parameters.
285
The \a parent QObject will be used as the parent of this QContactManager.
287
If an empty \a managerName is specified, the default implementation for the platform will
290
QContactManager::QContactManager(const QString &managerName, const QMap<QString, QString> ¶meters, QObject *parent)
292
d(new QContactManagerData)
294
createEngine(managerName, parameters);
297
void QContactManager::createEngine(const QString &managerName, const QMap<QString, QString> ¶meters)
299
d->createEngine(managerName, parameters);
301
QContactManagerData::m_aliveEngines.insert(this);
305
Constructs a QContactManager whose backend has the name \a managerName and version \a implementationVersion, where the manager
306
is constructed with the provided \a parameters.
308
The \a parent QObject will be used as the parent of this QContactManager.
310
If an empty \a managerName is specified, the default implementation for the platform will be instantiated.
311
If the specified implementation version is not available, the manager with the name \a managerName with the default implementation version is instantiated.
313
QContactManager::QContactManager(const QString &managerName, int implementationVersion, const QMap<QString, QString> ¶meters, QObject *parent)
315
d(new QContactManagerData)
317
QMap<QString, QString> params = parameters;
318
params[QString(QStringLiteral(QTCONTACTS_IMPLEMENTATION_VERSION_NAME))] = QString::number(implementationVersion);
319
createEngine(managerName, params);
322
/*! Frees the memory used by the QContactManager */
323
QContactManager::~QContactManager()
325
QContactManagerData::m_aliveEngines.remove(this);
331
\fn QContactManager::ParameterSignalSources()
332
The string constant for the parameter key which holds the value for signal sources.
333
If a manager supports suppressing change signals depending on the value given for
334
this construction parameter, clients can request that signals be suppressed if the
335
changes which might cause a signal to be emitted do not match particular criteria.
337
If the parameter (or value given for the parameter) is not supported by the manager,
338
the manager may still be constructed, however the parameter will not be reported
339
to the client if the client calls managerParameters() subsequent to manager construction.
341
The default (assumed) value for this parameter, if this parameter is not given,
342
is that the client wants to be notified of all changes to the data, regardless of
343
the source of the change.
347
\fn QContactManager::ParameterSignalDefinitions()
348
The string constant for the parameter key which holds the names of detail definitions.
349
If a manager supports suppressing change signals depending on the value given for
350
this construction parameter, clients can request that signals be suppressed if the
351
changes which might otherwise cause a signal to be emitted, involve details whose
352
definition name is not contained in the given list.
354
That is, if a detail in a contact is changed, but that detail's definition name is
355
not listed in the value for this parameter, the manager will not emit a change signal
358
If this parameter is not specified at construction time, changes to any detail of a contact
359
will cause a change signal to be emitted.
361
The value of this parameter should be a comma (,) separated list of definition names. Any
362
commas which might be part of a definition name must be escaped with a single backslash
363
(\) character prior to concatenation. Any backslash character which might be part of a
364
definition name must also be escaped with a backslash.
366
If the parameter (or value given for the parameter) is not supported by the manager,
367
the manager may still be constructed, however the parameter will not be reported
368
to the client if the client calls managerParameters() subsequent to manager construction.
372
\fn QContactManager::ParameterValueOnlyOtherManagers()
373
This value tells the manager to only emit signals for changes which
374
are made in other manager instances. That is, the client wishes to receive
375
change signals when another client (or background service) changes
376
the data as it is stored in the backend, but does not wish to be
377
notified of changes (or side effects) which it has caused itself.
381
\fn QContactManager::ParameterValueOnlyOtherProcesses()
382
This value tells the manager to only emit signals for changes which
383
are made in other processes. That is, the client wishes to receive
384
change signals when a client (or background service) in another process changes
385
the data as it is stored in the backend, but does not wish to be
386
notified of changes (or side effects) which were caused in the current client's
387
process, even if those changes were made in a different manager instance to this
392
\enum QContactManager::Error
394
This enum specifies an error that occurred during the most recent operation:
396
\value NoError The most recent operation was successful
397
\value DoesNotExistError The most recent operation failed because the requested contact does not exist
398
\value AlreadyExistsError The most recent operation failed because the specified contact already exists
399
\value InvalidDetailError The most recent operation failed because the specified contact contains details which do not conform to their definition
400
\value InvalidRelationshipError The most recent operation failed because the specified relationship is circular or references an invalid local contact
401
\value InvalidContactTypeError The most recent operation failed because the contact type specified was not valid for the operation
402
\value LockedError The most recent operation failed because the datastore specified is currently locked
403
\value DetailAccessError The most recent operation failed because a detail was modified or removed and its access method does not allow that
404
\value PermissionsError The most recent operation failed because the caller does not have permission to perform the operation
405
\value OutOfMemoryError The most recent operation failed due to running out of memory
406
\value VersionMismatchError The most recent operation failed because the backend of the manager is not of the required version
407
\value LimitReachedError The most recent operation failed because the limit for that type of object has been reached
408
\value NotSupportedError The most recent operation failed because the requested operation is not supported in the specified store
409
\value BadArgumentError The most recent operation failed because one or more of the parameters to the operation were invalid
410
\value TimeoutError The most recent operation failed because it took longer than expected. It may be possible to try again.
411
\value UnspecifiedError The most recent operation failed for an undocumented reason
412
\value InvalidStorageLocationError The most recent operation failed due to requested storage location is unavailable or invalid.
413
\value MissingPlatformRequirementsError The most recent operation failed due to all storage locations are unavailable.
417
Return the error code of the most recent operation.
418
For batch operations, if the error code is not equal to
419
\c QContactManager::NoError, detailed per-input errors
420
may be retrieved by calling \l errorMap().
423
QContactManager::Error QContactManager::error() const
425
return d->m_lastError;
429
Returns per-input error codes for the most recent operation.
430
This function only returns meaningful information if the most
431
recent operation was a batch operation.
432
Each key in the map is the index of the element in the input list
433
for which the error (whose error code is stored in the value for
434
that key in the map) occurred during the batch operation.
435
\sa error(), contacts(), saveContacts(), removeContacts(), saveRelationships(), removeRelationships()
437
QMap<int, QContactManager::Error> QContactManager::errorMap() const
439
return d->m_lastErrorMap;
443
Return the list of contact ids, sorted according to the given list of \a sortOrders
445
QList<QContactId> QContactManager::contactIds(const QList<QContactSortOrder> &sortOrders) const
447
QContactManagerSyncOpErrorHolder h(this);
448
return d->m_engine->contactIds(QContactFilter(), sortOrders, &h.error);
452
Returns a list of contact ids that match the given \a filter, sorted according to the given list of \a sortOrders.
453
Depending on the backend, this filtering operation may involve retrieving all the contacts.
455
QList<QContactId> QContactManager::contactIds(const QContactFilter &filter, const QList<QContactSortOrder> &sortOrders) const
457
QContactManagerSyncOpErrorHolder h(this);
458
return d->m_engine->contactIds(filter, sortOrders, &h.error);
462
Returns the list of contacts stored in the manager sorted according to the given list of \a sortOrders.
464
The \a fetchHint parameter describes the optimization hints that a manager may take.
465
If the \a fetchHint is the default constructed hint, all existing details, relationships and
466
action preferences in the matching contact will be returned. If a client makes changes to an
467
contact which has been retrieved with a fetch hint, they should save it back using a partial save,
468
masked by the same set of detail names in order to avoid information loss.
470
\sa QContactFetchHint
472
QList<QContact> QContactManager::contacts(const QList<QContactSortOrder> &sortOrders, const QContactFetchHint &fetchHint) const
474
QContactManagerSyncOpErrorHolder h(this);
475
return d->m_engine->contacts(QContactFilter(), sortOrders, fetchHint, &h.error);
479
Returns a list of contacts that match the given \a filter, sorted according to the given list of \a sortOrders.
481
Depending on the manager implementation, this filtering operation might be slow and involve retrieving all the
482
contacts and testing them against the supplied filter - see the \l isFilterSupported() function.
484
The \a fetchHint parameter describes the optimization hints that a manager may take.
485
If the \a fetchHint is the default constructed hint, all existing details, relationships and
486
action preferences in the matching contact will be returned. If a client makes changes to an
487
contact which has been retrieved with a fetch hint, they should save it back using a partial save,
488
masked by the same set of detail names in order to avoid information loss.
490
\sa QContactFetchHint
492
QList<QContact> QContactManager::contacts(const QContactFilter &filter, const QList<QContactSortOrder>& sortOrders, const QContactFetchHint &fetchHint) const
494
QContactManagerSyncOpErrorHolder h(this);
495
return d->m_engine->contacts(filter, sortOrders, fetchHint, &h.error);
499
Returns the contact in the database identified by \a contactId.
501
If the contact does not exist, an empty, default constructed QContact will be returned,
502
and the error returned by \l error() will be \c QContactManager::DoesNotExistError.
504
The \a fetchHint parameter describes the optimization hints that a manager may take.
505
If the \a fetchHint is the default constructed hint, all existing details, relationships and
506
action preferences in the matching contact will be returned. If a client makes changes to an
507
contact which has been retrieved with a fetch hint, they should save it back using a partial save,
508
masked by the same set of detail names in order to avoid information loss.
511
\sa QContactFetchHint
513
QContact QContactManager::contact(const QContactId &contactId, const QContactFetchHint &fetchHint) const
515
QContactManagerSyncOpErrorHolder h(this);
516
return d->m_engine->contact(contactId, fetchHint, &h.error);
520
Returns a list of contacts given a list of ids (\a contactIds).
522
Returns the list of contacts with the ids given by \a contactIds. There is a one-to-one
523
correspondence between the returned contacts and the supplied \a contactIds.
525
If there is an invalid id in \a contactIds, then an empty QContact will take its place in the
526
returned list. The \a errorMap parameter can be supplied to store per-input errors in.
527
In all cases, calling \l errorMap() will return the per-input errors for the latest batch function.
529
The \a fetchHint parameter describes the optimization hints that a manager may take.
530
If the \a fetchHint is the default constructed hint, all existing details, relationships and
531
action preferences in the matching contact will be returned. If a client makes changes to an
532
contact which has been retrieved with a fetch hint, they should save it back using a partial save,
533
masked by the same set of detail names in order to avoid information loss.
535
\sa QContactFetchHint
537
QList<QContact> QContactManager::contacts(const QList<QContactId> &contactIds, const QContactFetchHint &fetchHint, QMap<int, QContactManager::Error> *errorMap) const
539
QContactManagerSyncOpErrorHolder h(this, errorMap);
541
return d->m_engine->contacts(contactIds, fetchHint, &h.errorMap, &h.error);
545
Adds the given \a contact to the database if \a contact has
546
the (default constructed) null id.
548
If the manager URI of the id of the \a contact is neither empty nor equal to the URI of
549
this manager, or id of the \a contact is not null but does not exist in the
550
manager, the operation will fail and calling error() will return
551
\c QContactManager::DoesNotExistError.
553
Alternatively, the function will update the existing contact in the database if \a contact
554
has a id which is not null and currently exists in the database.
556
If the \a contact contains one or more details whose types are not
557
supported by the used engine, the operation will fail and calling
558
error() will return \c QContactManager::UnsupportedError.
560
If the \a contact has had its relationships reordered, the manager
561
will check to make sure that every relationship that the contact is currently
562
involved in is included in the reordered list, and that no relationships which
563
either do not involve the contact, or have not been saved in the manager are
564
included in the list. If these conditions are not met, the function will
565
return \c false and calling error() will return
566
\c QContactManager::InvalidRelationshipError.
568
Returns false on failure, or true on
569
success. On successful save of an contact with a null id, its
570
id will be set to a new, non-null id.
572
The manager is not required to fetch updated details of the contact on save,
573
and as such, clients should fetch a contact if they want the most up-to-date information
574
by calling \l QContactManager::contact().
578
bool QContactManager::saveContact(QContact *contact)
580
QContactManagerSyncOpErrorHolder h(this);
583
return d->m_engine->saveContact(contact, &h.error);
585
h.error = QContactManager::BadArgumentError;
591
Remove the contact identified by \a contactId from the database,
592
and also removes any relationships in which the contact was involved.
593
Returns true if the contact was removed successfully, otherwise
596
bool QContactManager::removeContact(const QContactId &contactId)
598
QContactManagerSyncOpErrorHolder h(this);
599
return d->m_engine->removeContact(contactId, &h.error);
603
Adds the list of contacts given by \a contacts list to the database.
604
Returns true if the contacts were saved successfully, otherwise false.
606
The \a errorMap parameter can be supplied to store per-input errors in.
607
In all cases, calling \l errorMap() will return the per-input errors for the latest batch function.
608
The \l QContactManager::error() function will only return \c QContactManager::NoError
609
if all contacts were saved successfully.
611
For each newly saved contact that was successful, the id of the contact
612
in the \a contacts list will be updated with the new value.
614
\sa QContactManager::saveContact()
616
bool QContactManager::saveContacts(QList<QContact> *contacts, QMap<int, QContactManager::Error> *errorMap)
618
QContactManagerSyncOpErrorHolder h(this, errorMap);
621
return d->m_engine->saveContacts(contacts, &h.errorMap, &h.error);
623
h.error = QContactManager::BadArgumentError;
629
Adds the list of contacts given by \a contacts list to the database.
630
Returns true if the contacts were saved successfully, otherwise false.
632
This function accepts a \a typeMask, which specifies which details of
633
the contacts should be updated. Details with types not included in
634
the typeMask will not be updated or added.
636
The \a errorMap parameter can be supplied to store per-input errors in.
637
In all cases, calling \l errorMap() will return the per-input errors for the latest batch function.
638
The \l QContactManager::error() function will only return \c QContactManager::NoError
639
if all contacts were saved successfully.
641
For each newly saved contact that was successful, the id of the contact
642
in the \a contacts list will be updated with the new value.
644
\sa QContactManager::saveContact()
646
bool QContactManager::saveContacts(QList<QContact> *contacts, const QList<QContactDetail::DetailType> &typeMask, QMap<int, QContactManager::Error> *errorMap)
648
QContactManagerSyncOpErrorHolder h(this, errorMap);
651
return d->m_engine->saveContacts(contacts, typeMask, &h.errorMap, &h.error);
653
h.error = QContactManager::BadArgumentError;
659
Remove every contact whose id is contained in the list of contacts ids
660
\a contactIds. Returns true if all contacts were removed successfully,
663
Any contact that was removed successfully will have the relationships
664
in which it was involved removed also.
666
The \a errorMap parameter can be supplied to store per-input errors in.
667
In all cases, calling \l errorMap() will return the per-input errors for the latest batch function.
668
The \l QContactManager::error() function will
669
only return \c QContactManager::NoError if all contacts were removed
672
If the given list of contact ids \a contactIds is empty, the function will return false
673
and calling error() will return \c QContactManager::BadArgumentError. If the list is non-empty
674
and contains ids which do not identify a valid contact in the manager, the function will
675
remove any contacts which are identified by ids in the \a contactIds list, insert
676
\c QContactManager::DoesNotExist entries into the \a errorMap for the indices of invalid ids
677
in the \a contactIds list, return false, and set the overall operation error to
678
\c QContactManager::DoesNotExistError.
680
\sa QContactManager::removeContact()
682
bool QContactManager::removeContacts(const QList<QContactId> &contactIds, QMap<int, QContactManager::Error> *errorMap)
684
QContactManagerSyncOpErrorHolder h(this, errorMap);
686
if (!contactIds.isEmpty()) {
687
return d->m_engine->removeContacts(contactIds, &h.errorMap, &h.error);
689
h.error = QContactManager::BadArgumentError;
695
Sets the id of the "self" contact to the given \a contactId.
696
Returns true if the "self" contact id was set successfully.
697
If the given \a contactId does not identify a contact
698
stored in this manager, the error will be set to
699
\c QContactManager::DoesNotExistError and the function will
700
return false; if the backend does not support the
701
concept of a "self" contact then the error will be set to
702
\c QContactManager::NotSupportedError and the function will
705
bool QContactManager::setSelfContactId(const QContactId &contactId)
707
QContactManagerSyncOpErrorHolder h(this);
708
return d->m_engine->setSelfContactId(contactId, &h.error);
712
Returns the id of the "self" contact which has previously been set.
713
If no "self" contact has been set, or if the self contact was removed
714
from the manager after being set, or if the backend does not support
715
the concept of a "self" contact, an invalid id will be returned
716
and the error will be set to \c QContactManager::DoesNotExistError.
718
QContactId QContactManager::selfContactId() const
720
QContactManagerSyncOpErrorHolder h(this);
721
return d->m_engine->selfContactId(&h.error);
725
Returns a list of relationships in which the contact \a participant participates in the given \a role.
726
If \a participant is empty, \a role is ignored and all relationships are returned.
728
QList<QContactRelationship> QContactManager::relationships(const QContact &participant, QContactRelationship::Role role) const
730
QContactManagerSyncOpErrorHolder h(this);
731
return d->m_engine->relationships(QString(), participant, role, &h.error);
735
Returns a list of relationships of the given \a relationshipType in which the contact identified by the given \a participant participates in the given \a role.
736
If \a participant is empty, \a role is ignored and all relationships of the given \a relationshipType are returned.
737
If \a relationshipType is empty, relationships of any type are returned.
739
QList<QContactRelationship> QContactManager::relationships(const QString &relationshipType, const QContact &participant, QContactRelationship::Role role) const
741
QContactManagerSyncOpErrorHolder h(this);
742
return d->m_engine->relationships(relationshipType, participant, role, &h.error);
746
Saves the given \a relationship in the database. If the relationship already exists in the database, this function will
747
return \c false and the error will be set to \c QContactManager::AlreadyExistsError.
748
If the relationship is saved successfully, this function will return \c true and error will be set
749
to \c QContactManager::NoError. Note that relationships cannot be updated directly using this function; in order
750
to update a relationship, you must remove the old relationship, make the required modifications, and then save it.
752
The given relationship is invalid if it is circular (the first contact is the second contact), or
753
if it references a non-existent local contact (either the first or second contact). If the given \a relationship is invalid,
754
the function will return \c false and the error will be set to \c QContactManager::InvalidRelationshipError.
755
If the given \a relationship could not be saved in the database (due to backend limitations)
756
the function will return \c false and error will be set to \c QContactManager::NotSupportedError.
758
bool QContactManager::saveRelationship(QContactRelationship *relationship)
760
QContactManagerSyncOpErrorHolder h(this);
762
return d->m_engine->saveRelationship(relationship, &h.error);
764
h.error = QContactManager::BadArgumentError;
770
Saves the given \a relationships in the database and returns true if the operation was successful.
771
The \a errorMap parameter can be supplied to store per-input errors in.
772
In all cases, calling \l errorMap() will return the per-input errors for the latest batch function.
774
bool QContactManager::saveRelationships(QList<QContactRelationship> *relationships, QMap<int, QContactManager::Error> *errorMap)
776
QContactManagerSyncOpErrorHolder h(this, errorMap);
779
return d->m_engine->saveRelationships(relationships, &h.errorMap, &h.error);
781
h.error = QContactManager::BadArgumentError;
787
Removes the given \a relationship from the manager. If the relationship exists in the manager, the relationship
788
will be removed, the error will be set to \c QContactManager::NoError and this function will return true. If no such
789
relationship exists in the manager, the error will be set to \c QContactManager::DoesNotExistError and this function
792
bool QContactManager::removeRelationship(const QContactRelationship &relationship)
794
QContactManagerSyncOpErrorHolder h(this);
795
return d->m_engine->removeRelationship(relationship, &h.error);
800
Removes the given \a relationships from the database and returns true if the operation was successful.
801
The \a errorMap parameter can be supplied to store per-input errors in.
802
In all cases, calling \l errorMap() will return the per-input errors for the latest batch function.
804
bool QContactManager::removeRelationships(const QList<QContactRelationship> &relationships, QMap<int, QContactManager::Error> *errorMap)
806
QContactManagerSyncOpErrorHolder h(this, errorMap);
807
return d->m_engine->removeRelationships(relationships, &h.errorMap, &h.error);
811
Returns the list of data types supported by the manager
813
QList<QVariant::Type> QContactManager::supportedDataTypes() const
815
return d->m_engine->supportedDataTypes();
819
Returns true if the given \a filter is supported natively by the
820
manager, and false if the filter behaviour would be emulated.
822
Note: In some cases, the behaviour of an unsupported filter
823
cannot be emulated. For example, a filter that requests contacts
824
that have changed since a given time depends on having that information
825
available. In these cases, the filter will fail.
827
bool QContactManager::isFilterSupported(const QContactFilter &filter) const
829
return d->m_engine->isFilterSupported(filter);
833
Returns true if the manager supports the relationship type specified in \a relationshipType for
834
contacts whose type is the given \a contactType.
836
Note that some managers may support the relationship type for a contact in a limited manner
837
(for example, only as the first contact in the relationship, or only as the second contact
838
in the relationship). In this case, it will still return true. It will only return false
839
if the relationship is entirely unsupported for the given type of contact.
841
bool QContactManager::isRelationshipTypeSupported(const QString& relationshipType, QContactType::TypeValues contactType) const
843
return d->m_engine->isRelationshipTypeSupported(relationshipType, contactType);
847
Returns the list of contact types which are supported by this manager.
848
This is a convenience function, equivalent to retrieving the allowable values
849
for the \c QContactType::FieldType field of the QContactType detail
850
which is valid in this manager.
852
QList<QContactType::TypeValues> QContactManager::supportedContactTypes() const
854
return d->m_engine->supportedContactTypes();
858
Returns the list of contact detail types which are supported by this manager.
859
The returned list can be used by clients to identify incompatibilities between
860
contact objects to be saved and the actual subset of detail types supported by
863
QList<QContactDetail::DetailType> QContactManager::supportedContactDetailTypes() const
865
return d->m_engine->supportedContactDetailTypes();
869
Returns the engine backend implementation version number
871
int QContactManager::managerVersion() const
873
return d->m_engine->managerVersion();
876
/*! Returns the manager name for this QContactManager */
877
QString QContactManager::managerName() const
879
return d->m_engine->managerName();
882
/*! Return the parameters relevant to the creation of this QContactManager */
883
QMap<QString, QString> QContactManager::managerParameters() const
885
QMap<QString, QString> params = d->m_engine->managerParameters();
887
params.remove(QString::fromLatin1(QTCONTACTS_VERSION_NAME));
888
params.remove(QString::fromLatin1(QTCONTACTS_IMPLEMENTATION_VERSION_NAME));
893
Return the uri describing this QContactManager, consisting of the manager name and any parameters.
895
QString QContactManager::managerUri() const
897
return d->m_engine->managerUri();
903
Returns the signal that corresponds to \a proxySignal in the
904
meta-object of the \a sourceObject.
906
static QMetaMethod proxyToSourceSignal(const QMetaMethod &proxySignal, QObject *sourceObject)
908
if (!proxySignal.isValid())
910
Q_ASSERT(proxySignal.methodType() == QMetaMethod::Signal);
911
Q_ASSERT(sourceObject != 0);
912
const QMetaObject *sourceMeta = sourceObject->metaObject();
913
int sourceIndex = sourceMeta->indexOfSignal(proxySignal.methodSignature());
914
Q_ASSERT(sourceIndex != -1);
915
return sourceMeta->method(sourceIndex);
921
When someone connects to this manager, connect the corresponding signal from the engine, if we
922
haven't before. If we have, just increment a count.
924
This allows lazy evaluation on the engine side (e.g. setting up dbus watchers) and prevents
927
void QContactManager::connectNotify(const QMetaMethod &signal)
929
/* For most signals we just connect from the engine to ourselves, since we just proxy, but we should connect only once */
930
QMetaMethod sourceSignal = proxyToSourceSignal(signal, d->m_engine);
931
connect(d->m_engine, sourceSignal, this, signal, Qt::UniqueConnection);
937
When someone disconnects, disconnect from the engine too if there are no more users of that signal.
939
void QContactManager::disconnectNotify(const QMetaMethod &signal)
941
if (!isSignalConnected(signal)) {
942
QMetaMethod sourceSignal = proxyToSourceSignal(signal, d->m_engine);
943
disconnect(d->m_engine, sourceSignal, this, signal);
948
#include "moc_qcontactmanager.cpp"
950
QT_END_NAMESPACE_CONTACTS
added
removed
src/contacts/qcontactmanager.cpp
