/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\page contactsactions.html

\title Qt Contacts Action API

\tableofcontents

\section1 Introduction

The QtMobility Contacts API supports the concept of a generic action which may be invoked
upon an \l{QContactActionTarget}{action target} (e.g., a contact) or list thereof.
The API allows clients to invoke an action upon a target (for example, to send an email
to a contact) in a cross-platform manner, and allows third-party developers to provide
platform-specific action plugins which may be used by clients.

\section1 Information For Clients

The client interface to actions consists of three classes: QContactAction, QContactActionTarget
and QContactActionDescriptor.  A \l{QContactActionDescriptor}{descriptor} uniquely identifies
a particular implementation of an \l{QContactAction}{action}, and allows the client to query
meta-data about the action.  An \l{QContactActionTarget}{action target} consists of either a
contact, a detail of a contact, or a list of details of a contact.

The available actions may be queried by calling \l QContactAction::availableActions().  This
function returns the list of names of actions which are provided by the given service name,
or by any service if the parameter is omitted.

There may be multiple implementations of any given action identified by a particular action
name, since multiple third-party action providers could provide (for example) a "call" action,
using various proprietary protocols and techologies.  Once the client knows which action they
wish to perform on a contact, they can retrieve the list of action descriptors for that action
by calling \l QContactAction::actionDescriptors() which takes the action name as a parameter.

Note that there are several predefined action names including QContactAction::ActionCall,
QContactAction::ActionEmail, QContactAction::ActionSms etc, however there is no guarantee
that all of these actions are implemented on any given platform.

Finally, once the client has selected a particular implementation of the action, by inspecting
the action descriptor (from which they can retrieve meta-data and check that it supports the
contact that they wish to perform the action on), the client may request a pointer to the
action implementation by calling \l QContactAction::action() and passing the action descriptor
as a parameter.  Note that the client takes ownership of the returned QContactAction
pointer and must delete it to avoid leaking memory.  The caller is able to delete the action
at any time, however doing so prior to when the action transitions to a finished state may
have an undefined outcome depending on the implementation of the action.

\section1 Information For Action Implementors

If you are a third-party developer who wants to provide an action for other clients to use,
you must do four things:
\list
\o Implement a QServicePluginInterface-derived class
\o Implement a QContactActionFactory-derived class
\o Implement (one or more) QContactAction-derived classes
\o Write an xml file which describes your service plugin
\endlist

For more information on the QServicePluginInterface and the format of the service description
xml, please see the \l{Qt Service Framework}{QtMobility Service Framework} documentation.
An example action plugin is provided later in this document.

Note that while the plugins are loaded by the \l{Qt Service Framework}{QtMobility Service Framework},
clients of the Qt Contacts Action API are entirely shielded from this implementation detail.

The QContactActionDescriptor class is actually a client-facing interface to an action factory,
which allows the factory to provide meta-data and other implementation-specific information
to clients on demand.

\section2 Other Considerations

We recommend that action implementors provide values for the default meta-data keys (including
icons and labels) documented in QContactActionDescriptor, to allow client applications to
provide meaningful user interface elements to represent the action.

We recommend that action implementors read the documentation of the
\l{Qt Service Framework}{QtMobility Service Framework} carefully, to better understand
how their implementation plugin may be updated with patch releases or major releases,
and how these considerations affect the implementation of the plugin.

\section2 Example Implementation

The following snippet provides an example of an action plugin.  As previously described, the action
plugin consists of a QServicePluginInterface, a QContactActionFactory, and one or more QContactAction
derived classes.  The QServicePluginInterface-derived class merely instantiates the
QContactActionFactory-derived class on request for the Qt Service Framework.  The
QContactActionFactory-derived class then instantiates the actions when required.

\snippet ../../tests/auto/qcontactactions/multiaction/multiaction_p.h Example Contact Action Plugin Declaration

The implementation of these classes might be something like the following (example only):

\snippet ../../tests/auto/qcontactactions/multiaction/multiaction.cpp Example Contact Action Plugin Implementation

Once implemented, the plugin must be described by an xml file as per the Qt Service Framework guidelines,
and installed in an appropriate location (once again, please see the documentation for the Qt Service Framework).

\code
<?xml version="1.0" encoding="utf-8" ?>
<service>
    <name>tst_qcontactactions:multiaction</name>
    <filepath>plugins/contacts/libcontacts_multiaction</filepath>
    <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>
    <interface>
        <name>com.nokia.qt.mobility.contacts.action</name>
        <version>1.1</version>
        <capabilities></capabilities>
        <customproperty key="ActionName">call</customproperty>
        <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>
    </interface>
</service>
\endcode

\section2 Deployment

Depending on the platform, the service which provides the action must be
deployed in a certain way.

\section3 Deployment on Maemo5

The QtMobility Service Framework provides the "servicefw" tool which allows
third parties to register their service with the system at installation time
on the Maemo5 platform.  In order to register their service, the plugin and
service description xml file should both be deployed to the installation
directory of your application or component, and then the command:
\code
    servicefw add "path/to/servicedescription.xml" --system
\endcode
should be run as a post-install step to register the service in the system
scope.  Your service will be persistently registered with the system.

Similarly, you should run the command:
\code
    servicefw remove "yourservicename"
\endcode
as an uninstall step for the package which provides your component.  This
will ensure that your service is removed from the service framework database
(although you would still have to remove the files from physical storage).

\section3 Deployment on Symbian

The QtMobility Service Framework will automatically check a particular
directory on Symbian for new or updated service description xmls.
That is, any service described by an xml file in that location will
automatically be registered in the system scope on that device.
To ensure that your service description xml file is deployed properly,
simply insert the following (or something similar) into the .pro
(qmake project) file of your service:
\code
    symbian {
        load(data_caging_paths)
        pluginDep.sources = yourserviceplugin.dll
        pluginDep.path = $$QT_PLUGINS_BASE_DIR
        DEPLOYMENT += pluginDep

        xmlautoimport.path = /private/2002AC7F/import/
        xmlautoimport.sources = yourservicedescription.xml
        DEPLOYMENT += xmlautoimport

        TARGET.EPOCALLOWDLLDATA = 1
        TARGET.CAPABILITY = ## whatever your service requires
        load(armcc_warnings)
    }
\endcode

Note that the UID in the xmlautoimport.path statement is the pre-assigned
UID of the "other components" directory.  For more information on the topic,
please see the documentation for the QtMobility Service Framework.

*/
