/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
**
** GNU Free Documentation License
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage creator-deployment.html
    \page creator-deployment-symbian.html
    \nextpage creator-deployment-maemo.html

    \title Deploying Applications to Symbian Devices

    This section describes how to create installation packages that meet the
    requirements for installing applications to Symbian devices.

    \section1 Creating SIS Files

    When you deploy the application for the \gui{Symbian Device} target, \QC
    automatically generates a Symbian installation system (SIS) file
    in the project folder. You can deliver the installation file to users for
    installation on Symbian devices.

    The name of the installation file is displayed in the \gui {Installation file}
    field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device
    to install the application to. To suppress notifications on the device during the
    installation, select the \gui {Silent installation} check box. If the silent
    installation fails, \QC attempts installation again, this time displaying
    notifications and error messages.

    To create a SIS package without copying it to the device (for example, to submit it
    to \e {Application Signing Services for Nokia Store} or \e {Symbian Signed}),
    create a deploy configuration that contains only the
    \gui {Create SIS Package} step.

    \image qtcreator-run-settings-create.png "Create SIS Package step"


    \section1 Signing SIS Files

    Only installation files signed with a certificate and private key are
    allowed to be installed onto Symbian devices. By default, \QC
    self-signs the installation file. This self-signing allows you to install
    the application on a mobile  device but places limits on what you can do
    with the installation file, including:
    \list
       \o  Self-signed applications cannot access the more sensitive
           \l{Capabilities and Signing}{capabilities} of the mobile device.
       \o  Security warnings will be displayed when you install the self-signed
           application on a mobile device.
       \o  Self-signed applications cannot be published to Nokia
           Store.
    \endlist

    To get around these limitations, you need to go through the Symbian Signed
    or Application Signing Services for Nokia Store. The Symbian Signed organisation
    manages a public key
    infrastructure to provide public authentication of the information in the
    application signing certificates. Their security partner can validate your
    certificate and give you a Publisher ID. Then, when you sign an
    application, other people can be confident that the information in your
    certificate is correct and that the application does actually come from you.

    Application Signing Services for Nokia Store is a variant of the Symbian
    Signed certification provided by Nokia
    Publish. It is limited to the Basic and System capability sets
    (Express Signing). Participants can submit an unsigned SIS file to Nokia
    Publish for signing. For more information about how
    to participate, see
    \l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Nokia Store}.

    There are also options that do not require you to get a Publisher ID. For
    more detail about how the Symbian Signed process works, see
    \l{https://www.symbiansigned.com}{Symbian Signed}.

    When you have your own certificate and private key, you can specify them in
    the \gui{Create SIS Package} step in the \gui {Run Settings}.

    \image qtcreator-qt4-symbian-signing.png


    If your private key is protected by a passphrase, \QC asks you for the
    passphrase when the package is signed and offers to store it. However, storing
    passphrases in \QC presents a security risk. To make \QC forget
    all saved passphrases, click \gui {Reset Passphrases}.

    \section2 Capabilities and Signing

    Capabilities allow the Symbian platform to control access by applications to
    the functionality provided by the platform APIs. Access to capabilities is
    determined by the device configuration and how the application has been signed.

    Symbian Signed offers the following signing options depending on the
    capabilities that the application accesses:

    \list

        \o \bold{Express signed} for applications that access only user and system
        capabilities.

        \o \bold{Certified signed} for applications that access also restricted or
        device manufacturer capabilities.

        \note You need to request the rights to access device manufacturer
        capabilities from the manufacturer.

    \endlist

    For more information about how to choose the appropriate signing option and
    how you can check which capabilities you need, see
    \l{https://www.symbiansigned.com}{Symbian Signed}
    and
    \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.

    For more information on how to define capabilities for a project, see
    \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.

    \note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate}
    option, the SIS generation process checks that the package can be self-signed.
    If problems are found, it attempts to fix the package. If fixes cannot be made,
    a message appears in the \gui {Compile Output} view.

    The following modifications can be made:

    \list

        \o Package UID is changed to an UID from the unprotected range (if it was
        from the protected range).

        \o Vendor ID is set to zero on all binaries included in the package file.

        \o All restricted and device manufacturer capabilities are removed from all
        libraries included in the package file.

    \endlist

    The application UID or capabilities used in executables (.exe) cannot be changed,
    because that would break the application. If the executables use protected UIDs
    or restricted or device manufacturer capabilities, signing fails and an error
    message appears in the \gui {Compile Output} view.

    \section1 Creating Smart Installer for Symbian Packages

    You can run Qt applications on Symbian devices if the software that Qt
    applications require (typically Qt, Qt Mobility, QtWebkit, and Open C) is
    installed on the device. On Symbian^3 and later devices, some version of Qt
    is pre-installed. On earlier devices, you must install the modules that Qt
    applications require. Nokia Smart Installer for Symbian makes it easier
    for users to install Qt applications to Symbian phones by checking whether the device contains
    the necessary software and by installing the missing pieces.

    For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
    application SIS file must first be Symbian Signed or signed by the Application
    Signing Services for Nokia Store. The capabilities used in the applications
    determine, which signing option must be selected. The wrapper package must be signed using
    either the same option or a more extensive option than the application SIS.

    \note If you use the Application Signing Services for Nokia Store, you can submit an unsigned
    wrapper package to Nokia Publish. For more information, see
    \l{Publishing Qt Content for Symbian Devices}.

    You can either install the Nokia Smart Installer for Symbian as part of
    the \QSDK, or download and install it from the
    \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}
    wiki.

    To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
    package} check box. This ensures that up-to-date and appropriate versions of Qt and its
    dependencies are installed on devices. Further, it reduces the file size of the application you
    publish, because you do not have to deliver the required libraries.

    Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:

    \list

        \o 0xA000D7CE for self-signed applications
        \o 0x2002CCCF for Nokia Store or Symbian Signed packages

    \endlist

    \section2 Creating Self-signed Smart Installer Packages

    To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file,
    you must use an UID from the unprotected UID range, provided by Symbian Signed
    and the wrapper package UID value 0xA000D7CE. If you used the \QC project
    wizard to create the project, this wrapper package UID is used by default.

    \list 1

        \o Make sure that the source directory is clean. For example, if you use Git,
        enter the following command:

        \c {git clean -dfx}

        \o Click \gui Projects to edit the \gui {Build Settings} for the
        \gui {Symbian Device} target.

        \o Select the \gui Release configuration.

        \o Open the \gui {Run Settings}.

        \o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}.

        \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} (1) to
        skip the step of copying the SIS file to a device. The SIS file is created
        in the project folder.

        \image qtcreator-remove-deploy-step.png "Removing deploy steps"

        \o To package Nokia Smart Installer for Symbian with the application, select
        the \gui {Create Smart Installer package} check box.

        \o Edit the project .pro file to use the correct UIDs for the application and
        the wrapper package, as illustrated by the following code snippet:

       \code
       symbian {
            TARGET.UID3 = 0xE4DE5D27
            DEPLOYMENT.installer_header=0xA000D7CE

            vendorinfo = \
            "%{\"CustomVendor-EN\"}" \
            ":\"CustomVendor\""

            my_deployment.pkg_prerules = vendorinfo
            DEPLOYMENT += my_deployment
        }
        \endcode

        \o Choose \gui {Build > Run Project}.

    \endlist

    \QC automatically generates a wrapper package in the project folder.

    \section2 Creating Symbian Signed Smart Installer Packages

    If the application uses functions that require advanced capabilities (AllFiles,
    DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the
    standard Symbian Signed process to have the application Symbian Signed. Depending
    on the capabilities used, you may use either the Express Signed or the Certified
    Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB).

    \list 1

        \o Make sure that the source directory is clean. For example, if you use Git,
        enter the following command:

        \c {git clean -dfx}

        \o Click \gui Projects to edit the \gui {Build Settings} for the
        \gui {Symbian Device} target.

        \o Select the \gui Release configuration.

        \o Open the \gui {Run Settings}.

        \o In the \gui {Create SIS Package} step, specify the developer certificate
        and key in the \gui {Custom certificate} and \gui {Key file} fields.

        \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
        skip the step of copying the SIS file to a device. The SIS file is created
        in the project folder.

        \o Edit the project .pro file to use the correct UIDs and vendor information
        for the application, as illustrated by the following code snippet:

       \code
       symbian {
            TARGET.UID3 = 0x2000D7D1
            DEPLOYMENT.installer_header=0x2002CCCF

            vendorinfo = \
            "%{\"CustomVendor-EN\"}" \
            ":\"CustomVendor\""

            my_deployment.pkg_prerules = vendorinfo
            DEPLOYMENT += my_deployment
        }
        \endcode

        \o Choose \gui {Build > Run Project}.

        \o Submit the created .sis file to Symbian Signed for certification.

        \note Ensure that your application complies with the Symbian Signed
        Test Criteria before submitting the file for certification. Also, if the file is
        intended for Nokia Store publishing, verify that the application complies with Nokia
        Store publishing requirements.

        \o After receiving the .sis file from Symbian Signed, copy it over the old
        application.sis.

        \note The instructions below assume that you have installed \QSDK.

        \o To package Nokia Smart Installer for Symbian with the application, choose
        \gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt}
        to open the Qt command line environment.

        \o Change to the project directory. For example:

        \c{cd C:\Sources\Application}

        \o To create a Smart Installer wrapper package, enter the following
        command:

        \c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key}

        \o Submit the created wrapped .sis file, application_installer.sis, to
        Symbian Signed. Express Signed is a suitable signing option for the wrapper
        package. The capabilities used in the application do not play a role here,
        because the wrapper package is already signed.

    \endlist

    \QC automatically generates a wrapper package in the project folder.

    \note Ensure that your application complies with the requirements before submitting
    the file to Nokia Store.

    For more information about the qmake DEPLOYMENT variable, see
    \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}.

    For more information about the Nokia Smart Installer, see the
    \l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}.

    Note: Nokia Smart Installer for Symbian is only available on Windows.

    \section1 Application UID

    A UID is a globally unique identifier that is used to
    uniquely identify, for example, an object or file type. In Symbian development,
    objects are identified by compound identifiers that are constructed from three
    UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
    object, whereas UID3 identifies a particular object, such as an application.

    When you create a \gui {Mobile Qt Application}, \QC adds a UID3 suitable for
    development and debugging automatically to the application .pro file. However, to
    distribute your application and get it Symbian Signed, you must apply for a UID
    from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
    at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
    web site.

    If you use the Nokia Signed process, Nokia Publisher Support allocates the UID for you.

    Replace the testing UID with the distribution UID in the .pro file before you
    build the final installation package. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.

*/
