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 documentation of the Qt PIM Module.
8
** $QT_BEGIN_LICENSE:FDL$
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 Free Documentation License Usage
18
** Alternatively, this file may be used under the terms of the GNU Free
19
** Documentation License version 1.3 as published by the Free Software
20
** Foundation and appearing in the file included in the packaging of
21
** this file. Please review the following information to ensure
22
** the GNU Free Documentation License version 1.3 requirements
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
26
****************************************************************************/
30
\page contactsactions.html
32
\title Qt Contacts Action API
36
The Qt Contacts API supports the concept of a generic action which may be invoked
37
upon an \l{QContactActionTarget}{action target} (e.g., a contact) or list thereof.
38
The API allows clients to invoke an action upon a target (for example, to send an email
39
to a contact) in a cross-platform manner, and allows third-party developers to provide
40
platform-specific action plugins which may be used by clients.
42
\section1 Invoking Actions upon Targets
44
The client interface to actions consists of three classes: QContactAction, QContactActionTarget
45
and QContactActionDescriptor. A \l{QContactActionDescriptor}{descriptor} uniquely identifies
46
a particular implementation of an \l{QContactAction}{action}, and allows the client to query
47
meta-data about the action. An \l{QContactActionTarget}{action target} consists of either a
48
contact, a detail of a contact, or a list of details of a contact.
50
The available actions may be queried by calling \l QContactAction::availableActions(). This
51
function returns the list of names of actions which are provided by the given service name,
52
or by any service if the parameter is omitted.
54
There may be multiple implementations of any given action identified by a particular action
55
name, since multiple third-party action providers could provide (for example) a "call" action,
56
using various proprietary protocols and techologies. Once the client knows which action they
57
wish to perform on a contact, they can retrieve the list of action descriptors for that action
58
by calling \l QContactAction::actionDescriptors() which takes the action name as a parameter.
60
Note that there are several predefined action names including QContactAction::ActionCall,
61
QContactAction::ActionEmail, QContactAction::ActionSms etc, however there is no guarantee
62
that all of these actions are implemented on any given platform.
64
Finally, once the client has selected a particular implementation of the action, by inspecting
65
the action descriptor (from which they can retrieve meta-data and check that it supports the
66
contact that they wish to perform the action on), the client may request a pointer to the
67
action implementation by calling \l QContactAction::action() and passing the action descriptor
68
as a parameter. Note that the client takes ownership of the returned QContactAction
69
pointer and must delete it to avoid leaking memory. The caller is able to delete the action
70
at any time, however doing so prior to when the action transitions to a finished state may
71
have an undefined outcome depending on the implementation of the action.
73
\section1 Implementing Actions
75
If you are a third-party developer who wants to provide an action for other clients to use,
76
you must do four things:
78
\li Implement a QServicePluginInterface-derived class
79
\li Implement a QContactActionFactory-derived class
80
\li Implement (one or more) QContactAction-derived classes
81
\li Write an XML file which describes your service plugin
84
For more information on the QServicePluginInterface and the format of the service description
85
XML, see the \l{Qt Service Framework}{Qt Service Framework} documentation.
86
An example action plugin is provided later in this document.
88
\note While the plugins are loaded by the Qt Service Framework,
89
clients of the Qt Contacts Action API are entirely shielded from this implementation detail.
91
The QContactActionDescriptor class is actually a client-facing interface to an action factory,
92
which allows the factory to provide meta-data and other implementation-specific information
95
\section2 Other Considerations
97
We recommend that action implementors provide values for the default meta-data keys (including
98
icons and labels) documented in QContactActionDescriptor, to allow client applications to
99
provide meaningful user interface elements to represent the action.
101
We recommend that action implementors read the documentation of the
102
\l{Qt Service Framework}{Qt Service Framework} carefully, to better understand
103
how their implementation plugin may be updated with patch releases or major releases,
104
and how these considerations affect the implementation of the plugin.
106
\section2 Example Implementation
108
The following snippet provides an example of an action plugin. As previously described, the action
109
plugin consists of a QServicePluginInterface, a QContactActionFactory, and one or more QContactAction
110
derived classes. The QServicePluginInterface-derived class merely instantiates the
111
QContactActionFactory-derived class on request for the Qt Service Framework. The
112
QContactActionFactory-derived class then instantiates the actions when required.
114
\snippet multiaction/multiaction_p.h Example Contact Action Plugin Declaration
116
The implementation of these classes might be something like the following (example only):
118
\snippet multiaction/multiaction.cpp Example Contact Action Plugin Implementation
120
Once implemented, the plugin must be described by an XML file and installed in
121
an appropriate location. For more information, see the Qt Service Framework
125
<?xml version="1.0" encoding="utf-8" ?>
127
<name>tst_qcontactactions:multiaction</name>
128
<filepath>plugins/contacts/libcontacts_multiaction</filepath>
129
<description>This service provides two test QContactAction implementations for testing purposes. It is also an example of a single plugin providing multiple actions whose descriptors are identical except for their meta data.</description>
131
<name>org.qt-project.Qt.SampleContactsActionPlugin</name>
132
<version>1.1</version>
133
<capabilities></capabilities>
134
<customproperty key="ActionName">call</customproperty>
135
<description>This plugin can instantiate two different QContactAction instances; one which provides the "call" action via the "sip" provider, the other which provides the "call" action via the "example proprietary protocol" provider.</description>
140
\section2 Deploying Services
142
Depending on the platform, the service which provides the action must be
143
deployed in a certain way.