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 "qcontactactiondescriptor.h"
35#include "qcontactactiondescriptor_p.h"
36
37#ifndef QT_NO_DEBUG_STREAM
38#include <QtCore/qdebug.h>
39#endif
40
41#include "qcontact.h"
42#include "qcontactactionfactory.h"
43#include "qcontactinvalidfilter.h"
44
45/*
46 When these conditions are satisfied, QStringLiteral is implemented by
47 gcc's statement-expression extension. However, in this file it will
48 not work, because "statement-expressions are not allowed outside functions
49 nor in template-argument lists".
50
51 Fall back to the less-performant QLatin1String in this case.
52*/
53#if defined(QStringLiteral) && defined(QT_UNICODE_LITERAL_II) && defined(Q_CC_GNU) && !defined(Q_COMPILER_LAMBDA)
54# undef QStringLiteral
55# define QStringLiteral QLatin1String
56#endif
57
58QT_BEGIN_NAMESPACE_CONTACTS
59
60/*!
61 \class QContactActionDescriptor
62 \brief The QContactActionDescriptor class provides information that
63 uniquely identifies a specific implementation of an action
64 \ingroup contacts-actions
65 \inmodule QtContacts
66*/
67
68/*!
69 * Constructs a new, invalid action descriptor
70 */
71QContactActionDescriptor::QContactActionDescriptor()
72 : d(new QContactActionDescriptorPrivate())
73{
74}
75
76/*!
77 * Constructs a copy of the \a other action descriptor
78 */
79QContactActionDescriptor::QContactActionDescriptor(const QContactActionDescriptor& other)
80 : d(other.d)
81{
82}
83
84/*!
85 * Assigns this action descriptor to be equal to \a other
86 */
87QContactActionDescriptor& QContactActionDescriptor::operator=(const QContactActionDescriptor& other)
88{
89 d = other.d;
90 return *this;
91}
92
93/*!
94 * Cleans up any memory in use by the action descriptor
95 */
96QContactActionDescriptor::~QContactActionDescriptor()
97{
98}
99
100/*!
101 * Returns the name of the action which is identified by the action descriptor
102 */
103QString QContactActionDescriptor::actionName() const
104{
105 return d.constData()->m_actionName;
106}
107
108
109/*!
110 * Returns the name of the service of the action implementation which is identified by the action descriptor
111 */
112QString QContactActionDescriptor::serviceName() const
113{
114 return d.constData()->m_serviceName;
115}
116
117/*!
118 * Returns the identifier of the action, within the service.
119 */
120QString QContactActionDescriptor::actionIdentifier() const
121{
122 return d.constData()->m_identifier;
123}
124
125/*!
126 Returns the service-specified version of the action implementation which is identified by the action descriptor
127 */
128int QContactActionDescriptor::implementationVersion() const
129{
130 return d.constData()->m_implementationVersion;
131}
132
133/*!
134 Returns the set of action targets which are supported by this action for the given contact \a contact
135 */
136QSet<QContactActionTarget> QContactActionDescriptor::supportedTargets(const QContact& contact) const
137{
138 if (d.constData()->m_factory) {
139 return d.constData()->m_factory->supportedTargets(contact, which: *this);
140 }
141
142 return QSet<QContactActionTarget>();
143}
144
145/*!
146 Returns a filter which will match contacts for which this action has at least one supported action target
147 */
148QContactFilter QContactActionDescriptor::contactFilter() const
149{
150 if (d.constData()->m_factory) {
151 return d.constData()->m_factory->contactFilter(which: *this);
152 }
153
154 return QContactInvalidFilter();
155}
156
157
158/*!
159 \variable QContactActionDescriptor::MetaDataIcon
160 The meta data key which corresponds to the meta data value
161 which contains the icon which should be displayed for this
162 action.
163 \sa metaData()
164 */
165const QString QContactActionDescriptor::MetaDataIcon(QStringLiteral("Icon"));
166
167/*!
168 \variable QContactActionDescriptor::MetaDataLabel
169 The meta data key which corresponds to the meta data value
170 which contains the display label for this action.
171 \sa metaData()
172 */
173const QString QContactActionDescriptor::MetaDataLabel(QStringLiteral("Label"));
174
175/*!
176 \variable QContactActionDescriptor::MetaDataSecondLabel
177 The meta data key which corresponds to the meta data value
178 which contains the second or additional display label for this
179 action.
180 \sa metaData()
181 */
182const QString QContactActionDescriptor::MetaDataSecondLabel(QStringLiteral("SecondLabel"));
183
184/*!
185 \variable QContactActionDescriptor::MetaDataOptionalParameterKeys
186 The meta data key which corresponds to the meta data value which
187 contains the list of keys of parameters which the client may provide
188 at invocation time which may affect the action.
189
190 An example of an optional parameter might be an "attachment"
191 parameter to a "send email" action.
192
193 \sa metaData()
194 */
195const QString QContactActionDescriptor::MetaDataOptionalParameterKeys(QStringLiteral("OptionalParameterKeys"));
196
197/*!
198 \variable QContactActionDescriptor::MetaDataMandatoryParameterKeys
199 The meta data key which corresponds to the meta data value which
200 contains the list of keys of parameters which the client must provide
201 at invocation for the action to succeed.
202
203 An example of a mandatory parameter might be a "recipient"
204 parameter to a "send email" action.
205
206 \sa metaData()
207 */
208const QString QContactActionDescriptor::MetaDataMandatoryParameterKeys(QStringLiteral("MandatoryParameterKeys"));
209
210/*!
211 Returns the meta data for the given meta data key \a key for the the given action targets \a targets with the given invocation parameters \a parameters.
212 */
213QVariant QContactActionDescriptor::metaData(const QString& key, const QList<QContactActionTarget>& targets, const QVariantMap& parameters) const
214{
215 if (d.constData()->m_factory) {
216 return d.constData()->m_factory->metaData(key, targets, parameters, which: *this);
217 }
218
219 return QVariant();
220}
221
222/*!
223 Returns the meta data for the given meta data key \a key with the given invocation parameters \a parameters.
224 */
225QVariant QContactActionDescriptor::metaData(const QString& key, const QVariantMap& parameters) const
226{
227 return metaData(key, targets: QList<QContactActionTarget>(), parameters);
228}
229
230/*!
231 Returns the meta data for the given meta data key \a key for the \a target, with the given invocation parameters \a parameters.
232 */
233QVariant QContactActionDescriptor::metaData(const QString& key, const QContactActionTarget& target, const QVariantMap& parameters) const
234{
235 return metaData(key, targets: QList<QContactActionTarget>() << target, parameters);
236}
237
238/*!
239 Returns the meta data for the given meta data key \a key for a target identified by \a contact and \a detail, with the given invocation parameters \a parameters.
240 */
241QVariant QContactActionDescriptor::metaData(const QString& key, const QContact& contact, const QContactDetail& detail, const QVariantMap& parameters) const
242{
243 return metaData(key, targets: QList<QContactActionTarget>() << QContactActionTarget(contact, detail), parameters);
244}
245
246/*!
247 Returns true if the action which this descriptor describes supports at least one action target for the given \a contact
248 */
249bool QContactActionDescriptor::supportsContact(const QContact& contact) const
250{
251 if (d.constData()->m_factory) {
252 return d.constData()->m_factory->supportsContact(contact, which: *this);
253 }
254
255 return false;
256}
257
258/*!
259 * Returns false if either the name, service and version of the descriptor are missing from the descriptor,
260 * or if the descriptor is not associated with a valid action factory which can create instances of an action.
261 * An empty descriptor cannot uniquely identify an action.
262 */
263bool QContactActionDescriptor::isValid() const
264{
265 if (d.constData()->m_actionName.isEmpty())
266 return false;
267 if (d.constData()->m_serviceName.isEmpty())
268 return false;
269 if (d.constData()->m_identifier.isEmpty())
270 return false;
271 if (d.constData()->m_implementationVersion <= 0)
272 return false;
273 if (d.constData()->m_factory == 0)
274 return false;
275 return true;
276}
277
278/*!
279 * Returns true if the action identified by this descriptor is the same as the action
280 * identified by the \a other descriptor. Note that two actions with the same
281 * action name, service name and implementation version may in fact be different (for example,
282 * they may have different metaData), so using this function is the only way for clients
283 * to tell whether or not the action descriptors identify different actions.
284 */
285bool QContactActionDescriptor::operator==(const QContactActionDescriptor& other) const
286{
287 return (d.constData()->m_factory == other.d.constData()->m_factory && d.constData()->m_identifier == other.d.constData()->m_identifier);
288}
289
290/*!
291 * Returns true if the action name, service name or service-specified implementation version
292 * specified by this action descriptor are different to that specified by \a other
293 */
294bool QContactActionDescriptor::operator!=(const QContactActionDescriptor& other) const
295{
296 return !(*this == other);
297}
298
299/*! Returns the hash value for \a key. */
300uint qHash(const QContactActionDescriptor& key)
301{
302 uint ret = 0;
303
304 ret += QT_PREPEND_NAMESPACE(qHash)(key: key.serviceName())
305 + QT_PREPEND_NAMESPACE(qHash)(key: key.actionName())
306 + QT_PREPEND_NAMESPACE(qHash)(key: key.d.constData()->m_identifier)
307 + QT_PREPEND_NAMESPACE(qHash)(key: key.implementationVersion())
308 + QT_PREPEND_NAMESPACE(qHash)(key: key.d.constData()->m_factory);
309
310 return ret;
311}
312
313#ifndef QT_NO_DEBUG_STREAM
314QDebug& operator<<(QDebug dbg, const QContactActionDescriptor& descriptor)
315{
316 dbg.nospace() << "QContactActionDescriptor("
317 << descriptor.serviceName() << ","
318 << descriptor.actionName() << ","
319 << descriptor.d.constData()->m_identifier << ","
320 << descriptor.implementationVersion() << ","
321 << descriptor.d.constData()->m_factory
322 << ')';
323 return dbg.maybeSpace();
324}
325#endif
326
327QT_END_NAMESPACE_CONTACTS
328

source code of qtpim/src/contacts/qcontactactiondescriptor.cpp