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 "qcontactaction.h"
35
36#include <QtCore/qset.h>
37
38#include "qcontactactiondescriptor.h"
39#include "qcontactactionmanager_p.h"
40#include "qcontactmanager_p.h"
41
42QT_BEGIN_NAMESPACE_CONTACTS
43
44QContactAction::~QContactAction()
45{
46}
47
48/*!
49 \class QContactAction
50 \brief The QContactAction class provides an interface for performing an
51 action on a QContact or QContactDetail.
52 \ingroup contacts-main
53 \ingroup contacts-actions
54
55 \inmodule QtContacts
56
57 An action is anything that can be performed on a contact, or a detail of a contact. An example
58 of an action might be "Send Email" or "Dial" or "Plot Navigation Route". One action may be
59 implemented by multiple vendors, and indeed one vendor may provide multiple implementations of
60 the same action. The name of an action identifies its semantics, while its implementation version
61 distinguishes it from other implementations of the action by the same vendor.
62
63 Invocation of an action is asynchronous; at some stage after calling \l invokeAction() the
64 action instance will emit the \l stateChanged() signal. Any results of the action may be retrieved
65 by calling \l results(), and as results become available the action will emit \l resultsAvailable().
66
67 Each instance of a QContactAction is created by a \l QContactActionFactory when
68 \l QContactAction::action() is called; the caller takes ownership of the action instance.
69 Each action is uniquely described by a \l QContactActionDescriptor, which is passed to the
70 \l QContactAction::action() function to instantiate an action.
71
72 \sa QContactActionFactory, QContactActionFilter
73 */
74
75/*!
76 \fn QContactAction::~QContactAction()
77 Clears any memory in use by this instance of the action implementation
78 */
79
80/*!
81 \fn QContactAction::state() const
82 Returns the current state of the action.
83 \sa stateChanged()
84 */
85
86
87/*!
88 \fn QContactAction::invokeAction(const QList<QContactActionTarget>& targets, const QVariantMap& parameters = QVariantMap())
89 \overload
90
91 Initiates the action on the specified list of \a targets with the optional supplied \a parameters.
92
93 At some point after invocation, one or more \l resultsAvailable() signals will be emitted by the action instance.
94 The results of the action (if any) may be retrieved by calling \l results().
95 When the state of the action changes, the \l stateChanged() signal will be emitted.
96
97 Returns true if the action was invoked successfully, otherwise false. The return value says nothing
98 about whether the action which was invoked was successful or not, only whether it was initiated or
99 the request for it to be initiated was sent successfully (e.g., if the action is implemented as a one-way
100 RPC call).
101
102 \sa results(), stateChanged()
103 */
104
105
106/*!
107 \fn QContactAction::invokeAction(const QContact& contact, const QContactDetail& detail = QContactDetail(), const QVariantMap& parameters = QVariantMap())
108 \overload
109
110 This is a convenience function.
111
112 Initiates the action on the specified \a detail of the given \a contact, or on the first
113 eligible detail saved in the contact if the given \a detail is empty, with the given \a parameters specified.
114
115 \sa results(), stateChanged()
116 */
117
118/*!
119 \fn QContactAction::invokeAction(const QContactActionTarget& target, const QVariantMap& parameters = QVariantMap())
120 \overload
121
122 This is a convenience function,
123
124 Initiates the action on the specified \a target with the given \a parameters specified.
125 \sa results(), stateChanged()
126 */
127
128/*!
129 \fn QContactAction::results() const
130 Returns the result of the action, if any exists. Calling this function prior to receiving the \l resultsAvailable()
131 signal will not return a meaningful result.
132 */
133
134/*!
135 \enum QContactAction::State
136 Describes the current status of the asynchronous action operation
137 \value InactiveState The operation has not yet been initiated
138 \value FinishedDetachedState The operation was initiated but no further information is or will be available
139 \value ActiveState The operation was initiated and is not yet finished
140 \value FinishedState The operation successfully completed
141 \value FinishedWithErrorState The operation has finished, but an error occurred
142 */
143
144/*!
145 \fn QContactAction::resultsAvailable()
146 This signal is emitted by an action instance whose functionality has been initiated with \l invokeAction()
147 when results of the action are available. Not all actions will have results, and these
148 actions will not emit the resultsAvailable() signal.
149
150 If the action implementation is incapable of reporting results of the operation (for example, the
151 action is implemented via a one-way IPC call) it should transition to the \c QContactAction::FinishedDetachedState state
152 immediately upon invocation.
153 */
154
155/*!
156 \fn QContactAction::stateChanged(QContactAction::State newState)
157 This signal is emitted when the state of an action changes to the given \a newState.
158 \sa state()
159 */
160
161/*!
162 Returns a list of identifiers of the available actions which are provided by the service provider with the given \a serviceName.
163 If \a serviceName is empty, actions from all service providers and of any implementation version are returned.
164 */
165QStringList QContactAction::availableActions(const QString& serviceName)
166{
167 // SLOW naive implementation...
168 QSet<QString> ret;
169 QList<QContactActionDescriptor> actionDescriptors = QContactActionManager::instance()->actionDescriptors();
170 for (int i = 0; i < actionDescriptors.size(); i++) {
171 QContactActionDescriptor descriptor = actionDescriptors.at(i);
172 if (serviceName.isEmpty() || serviceName == descriptor.serviceName()) {
173 ret.insert(value: descriptor.actionName());
174 }
175 }
176
177 return ret.toList();
178}
179
180
181/*!
182 \fn QContactAction::ActionCall()
183 The name of the default call action.
184 Actions of this name will allow the client to call
185 the specified action target (contact or detail of a contact).
186 \sa actionDescriptors()
187 */
188
189/*!
190 \fn QContactAction::ActionEmail()
191 The name of the default send email action.
192 Actions of this name will either open a graphical element
193 which allows the client to send the specified action
194 target an email, or directly send the specified action
195 target an email if the correct parameters to invocation
196 are specified.
197 \sa actionDescriptors()
198 */
199
200/*!
201 \fn QContactAction::ActionSms()
202 The name of the default send sms action.
203 Actions of this name will allow the client to send
204 the specified action target an sms.
205 \sa actionDescriptors()
206 */
207
208/*!
209 \fn QContactAction::ActionMms()
210 The name of the default send mms action.
211 Actions of this name will allow the client to send
212 the specified action target an mms.
213 \sa actionDescriptors()
214 */
215
216/*!
217 \fn QContactAction::ActionChat()
218 The name of the default IM chat action.
219 Actions of this name will allow the client to begin
220 an IM chat session with the specified action target.
221 \sa actionDescriptors()
222 */
223
224/*!
225 \fn QContactAction::ActionVideoCall()
226 The name of the default video call action.
227 Actions of this name will allow clients to initiate
228 a video call with the specified action target.
229 \sa actionDescriptors()
230 */
231
232/*!
233 \fn QContactAction::ActionOpenInEditor()
234 The name of the default "edit contact" action.
235 Actions of this name will open a graphical element
236 which allows the user to edit the contact.
237 \sa actionDescriptors()
238 */
239
240/*!
241 \fn QContactAction::ActionOpenInViewer()
242 The name of the default view contact action.
243 Actions of this name will open a graphical element
244 which allows the user to view the contact.
245 \sa actionDescriptors()
246 */
247
248/*!
249 Returns a list of QContactActionDescriptor instances which identified implementations of the given \a actionName.
250 The action name may either be one of the default action names, or any other arbitrary string.
251
252 Example:
253 \code
254 QList<QContactActionDescriptor> availableCallActions = QContactAction::actionDescriptors(QContactAction::ActionCall());
255 \endcode
256
257 Example 2:
258 \code
259 QList<QContactActionDescriptor> customActions = QContactAction::actionDescriptors(QStringLiteral("customActionName"));
260 \endcode
261
262 The actions which are available depend on which action plugins have been installed. For more information
263 on this topic (for example, if you are interested in providing an action plugin for third-party developers
264 to use) please see the relevant documentation for \l{Qt Contacts Action API}{action providers}.
265 */
266QList<QContactActionDescriptor> QContactAction::actionDescriptors(const QString& actionName)
267{
268 QContactActionManager* qcam = QContactActionManager::instance();
269 return qcam->actionDescriptors(actionName);
270}
271
272/*!
273 Returns a pointer to a new instance of the action implementation identified by the given \a descriptor.
274 The caller takes ownership of the action implementation and must delete it to avoid leaking memory.
275 The caller is able to delete the action at any time, however doing so prior to when the action
276 transitions to a finished state may have an undefined outcome depending on the implementation of the action.
277 */
278QContactAction* QContactAction::action(const QContactActionDescriptor& descriptor)
279{
280 QContactActionManager* qcam = QContactActionManager::instance();
281 return qcam->action(descriptor);
282}
283
284#include "moc_qcontactaction.cpp"
285
286QT_END_NAMESPACE_CONTACTS
287

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