← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/contacts/requests/qcontactsaverequest.cpp

  • Committer: chris.gagnon
  • Date: 2013-12-10 23:09:37 UTC
  • Revision ID: chris.gagnon@canonical.com-20131210230937-2akf1ft1edcttk87
first post

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/contacts/requests/qcontactsaverequest.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the QtContacts module of the Qt Toolkit.
 
7
**
 
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.
 
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 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.
 
24
**
 
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.
 
28
**
 
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.
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
#include "qcontactsaverequest.h"
 
43
#include "qcontactrequests_p.h"
 
44
 
 
45
QT_BEGIN_NAMESPACE_CONTACTS
 
46
 
 
47
/*!
 
48
  \class QContactSaveRequest
 
49
  \brief The QContactSaveRequest class allows a client to asynchronously
 
50
    request that certain contacts be saved to a contacts store.
 
51
 
 
52
  For a QContactSaveRequest, the resultsAvailable() signal will be emitted when
 
53
  either the individual item errors (which may be retrieved by calling errorMap()), or the resultant
 
54
  contacts (which may be retrieved by calling contacts()), are updated, as well as if
 
55
  the overall operation error (which may be retrieved by calling error()) is updated.
 
56
 
 
57
  Please see the class documentation of QContactAbstractRequest for more information about
 
58
  the usage of request classes and ownership semantics.
 
59
 
 
60
 
 
61
  \inmodule QtContacts
 
62
 
 
63
  \ingroup contacts-requests
 
64
 */
 
65
 
 
66
/*! Constructs a new contact save request whose parent is the specified \a parent */
 
67
QContactSaveRequest::QContactSaveRequest(QObject* parent)
 
68
    : QContactAbstractRequest(new QContactSaveRequestPrivate, parent)
 
69
{
 
70
}
 
71
 
 
72
/*! Frees any memory used by this request */
 
73
QContactSaveRequest::~QContactSaveRequest()
 
74
{
 
75
    QContactAbstractRequestPrivate::notifyEngine(this);
 
76
}
 
77
 
 
78
/*!
 
79
  Sets the \a storageLocation where the new contacts will be saved to.
 
80
 
 
81
  This is ignored for contacts which have already been saved. Instead,
 
82
  those contacts are saved back to the storage location where they were
 
83
  originally stored.
 
84
 
 
85
  \sa QContactAbstractRequest::StorageLocation
 
86
  \sa storageLocation()
 
87
 
 
88
 */
 
89
void QContactSaveRequest::setStorageLocation(QContactAbstractRequest::StorageLocation storageLocation)
 
90
{
 
91
    Q_D(QContactSaveRequest);
 
92
    QMutexLocker ml(&d->m_mutex);
 
93
    d->m_storageLocation = storageLocation;
 
94
}
 
95
 
 
96
/*!
 
97
  Returns the storage location where the contacts will be saved to.
 
98
 
 
99
  This is ignored for contacts which have already been saved. Instead,
 
100
  those contacts are saved back to the storage location where they were
 
101
  originally stored.
 
102
 
 
103
  \sa QContactAbstractRequest::StorageLocation
 
104
  \sa setStorageLocation()
 
105
 */
 
106
QContactAbstractRequest::StorageLocation QContactSaveRequest::storageLocation() const
 
107
{
 
108
    Q_D(const QContactSaveRequest);
 
109
    QMutexLocker ml(&d->m_mutex);
 
110
    return d->m_storageLocation;
 
111
}
 
112
 
 
113
/*!
 
114
  Sets the contact to be saved to \a contact.
 
115
  Equivalent to calling:
 
116
  \code
 
117
      setContacts(QList<QContact>() << contact);
 
118
  \endcode
 
119
 */
 
120
void QContactSaveRequest::setContact(const QContact& contact)
 
121
{
 
122
    Q_D(QContactSaveRequest);
 
123
    QMutexLocker ml(&d->m_mutex);
 
124
    d->m_contacts.clear();
 
125
    d->m_contacts.append(contact);
 
126
}
 
127
 
 
128
/*! Sets the list of contacts to be saved to \a contacts
 
129
*/
 
130
void QContactSaveRequest::setContacts(const QList<QContact>& contacts)
 
131
{
 
132
    Q_D(QContactSaveRequest);
 
133
    QMutexLocker ml(&d->m_mutex);
 
134
    d->m_contacts = contacts;
 
135
}
 
136
 
 
137
/*! Returns the list of contacts which will be saved if called prior to calling \c start(),
 
138
    otherwise returns the list of contacts with their ids set appropriately (successfully
 
139
    saved new contacts will have an id assigned).
 
140
*/
 
141
QList<QContact> QContactSaveRequest::contacts() const
 
142
{
 
143
    Q_D(const QContactSaveRequest);
 
144
    QMutexLocker ml(&d->m_mutex);
 
145
    return d->m_contacts;
 
146
}
 
147
 
 
148
/*! Returns the map of input contact list indices to errors which occurred
 
149
*/
 
150
QMap<int, QContactManager::Error> QContactSaveRequest::errorMap() const
 
151
{
 
152
    Q_D(const QContactSaveRequest);
 
153
    QMutexLocker ml(&d->m_mutex);
 
154
    return d->m_errors;
 
155
}
 
156
 
 
157
/*!
 
158
    Set the list of definitions to restrict saving to \a typeMask.  This allows you to perform
 
159
    partial save (and remove) operations on existing contacts.
 
160
 
 
161
    If \a typeMask is empty (the default), no restrictions will apply, and the passed
 
162
    in contacts will be saved as is.  Otherwise, only details whose types are in
 
163
    the typeMask will be saved.  If a type is present in the list, but there are no
 
164
    corresponding details in the contact passed into this request, any existing details in
 
165
    the manager for that contact will be removed.
 
166
 
 
167
    This is useful if you've used a fetch hint to fetch a partial contact from a manager
 
168
    so that you can save changes to the details you actually fetched without removing
 
169
    the details you didn't.
 
170
 
 
171
    Additionally, when performing synchronization operations with other managers that don't
 
172
    support the full range of details, you can restrict the update operation to only those
 
173
    details so that you don't lose the extra details that are supported in this manager.
 
174
 
 
175
    \note Some managers do not support partial updates natively, in which case the QtContacts
 
176
    framework will emulate the functionality (fetching the whole contact, applying the
 
177
    new restricted details, and saving the contact back).
 
178
*/
 
179
void QContactSaveRequest::setTypeMask(const QList<QContactDetail::DetailType> &typeMask)
 
180
{
 
181
    Q_D(QContactSaveRequest);
 
182
    QMutexLocker ml(&d->m_mutex);
 
183
    d->m_typeMask = typeMask;
 
184
}
 
185
 
 
186
/*!
 
187
    Returns the list of definitions that this request will operate on.
 
188
 
 
189
    If the list is empty, the request will operate on all details.
 
190
 */
 
191
QList<QContactDetail::DetailType> QContactSaveRequest::typeMask() const
 
192
{
 
193
    Q_D(const QContactSaveRequest);
 
194
    QMutexLocker ml(&d->m_mutex);
 
195
    return d->m_typeMask;
 
196
}
 
197
 
 
198
#include "moc_qcontactsaverequest.cpp"
 
199
 
 
200
QT_END_NAMESPACE_CONTACTS