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#include "qcontactsaverequest.h"
35
36#include "qcontactrequests_p.h"
37
38QT_BEGIN_NAMESPACE_CONTACTS
39
40/*!
41 \class QContactSaveRequest
42 \brief The QContactSaveRequest class allows a client to asynchronously
43 request that certain contacts be saved to a contacts store.
44
45 For a QContactSaveRequest, the resultsAvailable() signal will be emitted when
46 either the individual item errors (which may be retrieved by calling errorMap()), or the resultant
47 contacts (which may be retrieved by calling contacts()), are updated, as well as if
48 the overall operation error (which may be retrieved by calling error()) is updated.
49
50 Please see the class documentation of QContactAbstractRequest for more information about
51 the usage of request classes and ownership semantics.
52
53
54 \inmodule QtContacts
55
56 \ingroup contacts-requests
57 */
58
59/*! Constructs a new contact save request whose parent is the specified \a parent */
60QContactSaveRequest::QContactSaveRequest(QObject* parent)
61 : QContactAbstractRequest(new QContactSaveRequestPrivate, parent)
62{
63}
64
65/*! Frees any memory used by this request */
66QContactSaveRequest::~QContactSaveRequest()
67{
68}
69
70/*!
71 Sets the contact to be saved to \a contact.
72 Equivalent to calling:
73 \code
74 setContacts(QList<QContact>() << contact);
75 \endcode
76 */
77void QContactSaveRequest::setContact(const QContact& contact)
78{
79 Q_D(QContactSaveRequest);
80 QMutexLocker ml(&d->m_mutex);
81 d->m_contacts.clear();
82 d->m_contacts.append(t: contact);
83}
84
85/*! Sets the list of contacts to be saved to \a contacts
86*/
87void QContactSaveRequest::setContacts(const QList<QContact>& contacts)
88{
89 Q_D(QContactSaveRequest);
90 QMutexLocker ml(&d->m_mutex);
91 d->m_contacts = contacts;
92}
93
94/*! Returns the list of contacts which will be saved if called prior to calling \c start(),
95 otherwise returns the list of contacts with their ids set appropriately (successfully
96 saved new contacts will have an id assigned).
97*/
98QList<QContact> QContactSaveRequest::contacts() const
99{
100 Q_D(const QContactSaveRequest);
101 QMutexLocker ml(&d->m_mutex);
102 return d->m_contacts;
103}
104
105/*! Returns the map of input contact list indices to errors which occurred
106*/
107QMap<int, QContactManager::Error> QContactSaveRequest::errorMap() const
108{
109 Q_D(const QContactSaveRequest);
110 QMutexLocker ml(&d->m_mutex);
111 return d->m_errors;
112}
113
114/*!
115 Set the list of definitions to restrict saving to \a typeMask. This allows you to perform
116 partial save (and remove) operations on existing contacts.
117
118 If \a typeMask is empty (the default), no restrictions will apply, and the passed
119 in contacts will be saved as is. Otherwise, only details whose types are in
120 the typeMask will be saved. If a type is present in the list, but there are no
121 corresponding details in the contact passed into this request, any existing details in
122 the manager for that contact will be removed.
123
124 This is useful if you've used a fetch hint to fetch a partial contact from a manager
125 so that you can save changes to the details you actually fetched without removing
126 the details you didn't.
127
128 Additionally, when performing synchronization operations with other managers that don't
129 support the full range of details, you can restrict the update operation to only those
130 details so that you don't lose the extra details that are supported in this manager.
131
132 \note Some managers do not support partial updates natively, in which case the QtContacts
133 framework will emulate the functionality (fetching the whole contact, applying the
134 new restricted details, and saving the contact back).
135*/
136void QContactSaveRequest::setTypeMask(const QList<QContactDetail::DetailType> &typeMask)
137{
138 Q_D(QContactSaveRequest);
139 QMutexLocker ml(&d->m_mutex);
140 d->m_typeMask = typeMask;
141}
142
143/*!
144 Returns the list of definitions that this request will operate on.
145
146 If the list is empty, the request will operate on all details.
147 */
148QList<QContactDetail::DetailType> QContactSaveRequest::typeMask() const
149{
150 Q_D(const QContactSaveRequest);
151 QMutexLocker ml(&d->m_mutex);
152 return d->m_typeMask;
153}
154
155#include "moc_qcontactsaverequest.cpp"
156
157QT_END_NAMESPACE_CONTACTS
158

source code of qtpim/src/contacts/requests/qcontactsaverequest.cpp