/****************************************************************************
**
** 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 service-framework-on-symbian.html

\title Qt Service Framework on Symbian

\section1 How to register and unregister service plugins in S60?

All services must be registered for clients to be able to locate and use them.
Symbian provides 3 different methods to register services.

\list
\o \l{Automatic registration}
\o \l{Secure registration}
\o \l{ROM build registration}
\endlist

\section2 Automatic registration

Registration phase is a little different compared to other platforms because of the
authenticity of the provider is done during (un)registering phase based on the verification
of VID/SID (vendor ID or secure ID). Durring automatic registration the VID/SID is set to 0.  This method
is suitable for services that aren't security critical.

To use automatic registration the XML file is copied to the imports directory of the service framework database
server.  In the pro file for example:

\code
xmlautoimport.path = /private/2002AC7F/import/
xmlautoimport.sources = <service xml file>.xml
DEPLOYMENT += xmlautoimport
\endcode

Or in a symbian .pkg file by:

\code
"/epoc32/data/z/private/2002AC7F/import/<service xml file>.xml" - "c:\private\2002AC7F\import\<service xml file>.xml"
\endcode

\section2 Secure registration

For security registration a tiny installer application can be implemented by the service provider.
The installer application can then provide a VID/PID and is responsible for the registering (and the unregistering)
of the service. The example code for the installer is shown below. The whole installer project can be found under
\c {examples/serviceinstaller_sfw_symbian}.

\snippet examples/serviceinstaller_sfw_symbian/exampleinstaller/exampleinstaller.cpp 0

If you want to create your own installer take a copy from the installer project (\c {examples/serviceinstaller_sfw_symbian})
and modify only the necessary parts e.g a target for your installer and define plugins which are deployed etc.

If the installer defines the VID (non-zero value) then the VID is stored to the database, otherwise SID is used.
When unregistering the plugin the VID/SID verification is done to ensure that only the application which actually
registered the service is only allowed to remove it. VID/SID is left to the database even the service has been
unregistered. This prevents the exactly same way named services to be installed afterwards because the VID/SID
information is locked to the service name.

More info about VID and SID can be found from
\list
    \o \l {http://wiki.forum.nokia.com/index.php/Symbian_Platform_Security_Model}
    \o \l {http://wiki.forum.nokia.com/index.php/Symbian_Signed_Test_Criteria_V4_Wiki_version}
\endlist

\section2 ROM build registration

For application built into the ROM the host tool servicedbgen must be used prior to building the ROM image to add the service
to the database.

\section1 What's special from the security perspective?

There is only one database in S60 because both databases (user and system) are combined to the same database.
The database is located behind the server's private folder, (\c{c:\private\E3b48c24}). This ensures the database can't
be altered without Allfiles capability which isn't user-grantable (More about the
capabilities: \l http://wiki.forum.nokia.com/index.php/Capabilities). That makes it impossible for example to replace the
whole database with the new one which might contain malicious services.

Note! It doesn't matter which scope is used on Symbian as \l {QService::UserScope} and \l {QService::SystemScope}
are mapped to the same database.

\section1 Directory structure

There are different implementations for the both emulator and device because emulator doesn't support multiple
applications running at the same time, (Known issue: \l {http://bugreports.qt.nokia.com/browse/QTBUG-2950}{QTBUG-2950})
prior to Symbian. The dll approach must be used in the emulator environment and the exe approach instead of
dll in the real device.

Note! The greatest part of the S60 specific code is located under the symbian folder in a directory hierarchy of
Service FW. ServiceDatabase class contains also S60 specific code and the DatabaseManager class has been replaced
totally with the corresponding class.

*/