<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-5885167D-4755-54CC-B366-6DA89A608F8E"><title>Installing Features with Feature Manager</title><shortdesc>Provides instructions for adding features when installing a new software component. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><context id="GUID-40496782-F0E4-5F4D-B6E9-DA4474CDA671"><p>A phone is typically built with many features either disabled or not included. When you install a new software component which requires disabled or excluded features you need to enable or add them for the first time. You do this using the feature installer, a C++ program which calls the Feature Manager API. To install the required features you customise and install the source code. </p> </context> <steps id="GUID-2CA20C7B-26A2-5E4B-BBE2-95E7674421DC"><step id="GUID-A6C4B135-B93B-5C68-85F3-026E9BB02BC2"><cmd/><info>customise the source code in <filepath>featureinstaller.cpp</filepath>, </info> <substeps id="GUID-D8A88FAD-0987-50AA-A986-1BB629106DC1"><substep id="GUID-F3505836-5E4D-52CB-9540-423E036A92D2"><cmd/><info>Set the TUid <codeph>featureUid</codeph> to the UId of the required feature as defined in <filepath>featureUIDs.h</filepath>, </info> <stepxmp><codeblock id="GUID-22B3B46E-99A7-5D21-8E9D-B5A762510A3C" xml:space="preserve">    // TODO: Replace UID 0x00000000 with real value

    TUid featureUid( TUid::Uid( 0x00000000 ) ); 

</codeblock> </stepxmp> </substep> <substep id="GUID-7538FC56-74C7-52B4-8B4C-B860D59F0E12"><cmd/><info>set the TBitFlags32 <codeph>featureFlags</codeph> to the status flags which should be set for the required feature, and </info> <stepxmp><codeblock id="GUID-325D9F6F-F8A1-55A7-9171-212D441E9C40" xml:space="preserve">    // If set, feature is supported and available for use; 

    // if not, feature is not supported.

    // TODO: Comment when needed!

    featureFlags.Set( EFeatureSupported );

    ...

</codeblock> </stepxmp> </substep> <substep id="GUID-A7FACC1E-4B45-5479-9992-2DD321082751"><cmd>set the TUint32 <codeph> featureData</codeph> to the user-defined data. </cmd> <stepxmp><codeblock id="GUID-C28942F8-CD93-5A0D-A62D-42A54E69BFAF" xml:space="preserve">    // TODO: Set feature data. Replace &lt;featureData&gt; with real value!

    // TODO: Comment when needed!

    TUint32 featureData( 0x00000000 );

</codeblock> </stepxmp> </substep> </substeps> <info>This is the source code to be modified. </info> <stepxmp><codeblock id="GUID-4A29F159-AC08-598D-80CE-389E16BFFDF4" xml:space="preserve">

// INCLUDE FILES

#include <featurecontrol.h>

// LOCAL CONSTANTS AND MACROS

_LIT(KTxt,"featureinstaller: mainL failed");

// ============================= LOCAL FUNCTIONS ===============================

// -----------------------------------------------------------------------------

// mainL

// -----------------------------------------------------------------------------

//  

LOCAL_C void mainL()

    {

    // Open Feature Control.

    RFeatureControl featureControl;

    User::LeaveIfError( featureControl.Open() );

    // Example code adds a new persisted feature to the device.

    // TODO: Comment or uncomment code when needed. 

    // TODO: Specify in your .pkg file:

    // @"featureinstaller.sisx", (0x10283303)

    // TODO: Replace UID 0x00000000 with real value

    TUid featureUid( TUid::Uid( 0x00000000 ) ); 

    // TODO: Set feature flags of the feature!

    // Set all flags to zero.

    // TODO: Comment when needed!

    TBitFlags32 featureFlags( 0 );

    // If set, feature is supported and available for use; 

    // if not, feature is not supported.

    // TODO: Comment when needed!

    featureFlags.Set( EFeatureSupported );

    // If set, feature is upgradeable. The feature is known to the device

    // but it must be upgraded to enable it. If a feature s blacklisted, 

    // its upgradeable flag is unset. 

    // TODO: Uncomment when needed!

    // featureFlags.Set( EFeatureUpgradeable );

    // If set, the feature is modifiable and may be enabled/disabled 

    // at run-time. The initial flag values for such a feature flag are

    // defined in a ROM image obey file.

    // TODO: Comment when needed!

    featureFlags.Set( EFeatureModifiable );

    // If set, the feature has been blacklisted, and may not be changed at 

    // run-time. This also prevents a feature from being upgraded.

    // TODO: Uncomment when needed!

    // featureFlags.Set( EFeatureBlackListed );

    // If set, only clients with WriteDeviceData capability can modify it.

    // This ensures only trusted software can set the feature Supported flag.

    // TODO: Uncomment when needed!

    // featureFlags.Set( EFeatureProtected );

    // If set, this flag is saved to the system drive when modified 

    // preserving its value across reboots/power downs.

    // TODO: Comment when needed!

    featureFlags.Set( EFeaturePersisted );

    // If set, this flag Supported state is unknown at build-time and is

    // initialised at run-time by system software. The Feature Manager will

    // ignore the Supported flag in the file. A run-time call to RFeatureControl

    // will be needed to set the feature's supported flag. Look ups of 

    // uninitialised features result in a KErrNotReady error code

    // TODO: Uncomment when needed!

    // featureFlags.Set( EFeatureUninitialized );

    // Feature data is 32-bit quantity for client read and write. Feature data is

    // defined by owner of the feature and can contain for example flags, 

    // enumeratons and/or integers.

    // TODO: Set feature data. Replace <featureData> with real value!

    // TODO: Comment when needed!

    TUint32 featureData( 0x00000000 );

    // TODO: Comment when needed!

    TFeatureEntry entry( featureUid, featureFlags, featureData );

    TInt err( KErrNone );

    // Add a new feature to the device.

    // TODO: Comment when needed!

    err = featureControl.AddFeature( entry );

    if ( err == KErrAlreadyExists ) // Existing feature cannot be added as a new feature.

        {

        // Enable an existing feature.

        User::LeaveIfError( featureControl.EnableFeature( featureUid ) );

        // OR enable an exsiting feature and set feature data.

        // TODO: Uncomment when needed!

        //User::LeaveIfError( featureControl.SetFeature( featureUid, ETrue, featureData ) );

        }

    featureControl.Close();

    }

</codeblock> </stepxmp> </step> <step id="GUID-780D9456-0023-5D1A-BA9D-814429D87BCD"><cmd/><info>compile the code to <filepath>featureinstaller.exe</filepath>, </info> </step> <step id="GUID-EE257E8E-12A5-5BBF-B87E-201D4D707CE9"><cmd>customise the package file <filepath>featureinstaller.pkg</filepath> with the filepath of featureinstaller.exe, and </cmd> <stepxmp><codeblock id="GUID-231869B5-8D76-595C-9F7B-7189437E594A" xml:space="preserve">; This file installs an exe that is run asynchronously on installation, 

;Languages

&EN

;Header

#{"featureinstaller"}, (0x10283303), 1, 2, 3,TYPE=SA

%{"Vendor"}

:"Unique Vendor Name"

"\epoc32\release\winscw\udeb\featureinstaller.exe"-"!:\sys\bin\featureinstaller.exe", FR, RI</codeblock> </stepxmp> </step> <step id="GUID-7DED0C7A-C820-58AF-9780-AFBD4F44E1A5"><cmd>convert <filepath>featureinstaller.pkg</filepath> into a .sis file to be placed on the phone in accordance with the normal installation process. </cmd> <stepresult>The .sis file will cause the .exe to run when the .sis file is installed on the device. </stepresult> </step> </steps> <result id="GUID-06AAB92C-BB6A-583F-A432-E837AA7EF1FF"><p>The features you have installed will now be enabled on the device. </p> </result> </taskbody><related-links><link href="GUID-AB99E33E-322A-5C65-AAA0-6F3DE038ED71.dita"><linktext>Uninstalling Features with Feature

                Manager Tutorial </linktext> </link> <link href="GUID-B71AC5E3-8AA8-55AD-916F-9E873926011B.dita"><linktext> Feature Manager Overview</linktext> </link> </related-links></task>