<?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 id="GUID-6A9E486A-6C1B-4E31-832A-FD39AF041817" xml:lang="en"><title>Publishing the SIF operation progress</title><shortdesc>Installers must publish the SIF operation progress to notify

clients about the progress of operations (installation or uninstallation).</shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq id="GUID-743E5646-74B5-4D97-87FD-A97F05B8DBC6"><p>The installers

must link against <filepath>Sifnotification.dll</filepath> . It is

the utility library that provides the APIs to publish the SIF operation

progress. </p></prereq>

<steps id="GUID-4DD07DEC-6017-4237-BE46-1D69E5FBD744-GENID-1-12-1-5-1-1-6-1-4-1-4-1-5-1-3-2">

<step id="GUID-72EBB7F4-DBCA-47B2-85D6-B96230084CB1"><cmd>Create an

object of <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita"><apiname>CPublishSifOperationInfo</apiname></xref>.</cmd>

<info><codeblock xml:space="preserve">CPublishSifOperationInfo* sifPublisher = CPublishSifOperationInfo::NewL();</codeblock></info>

</step>

<step id="GUID-F1AE134F-0EFB-4415-88A5-FFF213197B87"><cmd>Publish

the operation start information.</cmd>

<substeps id="GUID-043BDAD9-5001-424F-B9DF-184892A14F0D">

<substep id="GUID-A55F772D-79B5-4624-9AD9-926428D5282D"><cmd>Create

a <xref href="GUID-F1D2CE7E-B5B9-3E35-B648-55F1B24E6272.dita"><apiname>CSifOperationStartData</apiname></xref> object.</cmd>

<info><p>The parameters that need to be initialized are:<ul>

<li><p>global component id that uniquely identifies the package across

devices. For example, this could be the package uid in case of a native

SIS package or the midlet name for java.</p></li>

<li><p>name of the software component (can be the same as global component

id)</p></li>

<li><p>list of applications associated with the software component

(an empty array in case of no applications)</p></li>

<li><p> list of corresponding application icon names (without path)

for every application (an empty array in case of no applications). </p></li>

<li><p> total size of the component in bytes</p></li>

<li><p>path where all application and component icons are found. All

icon files will be checked with respect to this path.</p></li>

<li><p>name of the component icon (without path)</p></li>

<li><p>unique software type name of the component</p></li>

</ul></p><codeblock xml:space="preserve">_LIT(KGlobalCompId, "12345");

_LIT(KComponentName, "Testcomponent");

RPointerArray<HBufC> appNameSet;

RPointerArray<HBufC> appIconSet;

TInt componentSize = 1024;

_LIT(KIconPath, "c:\data\test");

_LIT(KCompIcon, "TestIcon.mbm");

_LIT(KSoftwareType, "native");

CSifOperationStartData* startdata = CSifOperationStartData::NewLC(KGlobalCompId, KComponentName, &appNameSet, &appIconSet, componentSize, KIconPath, KCompIcon, KSoftwareType);

</codeblock></info>

</substep>

<substep id="GUID-D89D10DA-C76A-42DF-BE97-A80C0F41CFC4"><cmd>Invoke

the <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-9F99E500-1FEE-308C-82A6-39523B1DCCDB"><apiname>CPublishSifOperationInfo::PublishStartL()</apiname></xref>.</cmd>

<info><codeblock xml:space="preserve">sifPublisher-&gt;PublishStartL(*startdata);</codeblock></info>

</substep>

</substeps>

<info><xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-9F99E500-1FEE-308C-82A6-39523B1DCCDB"><apiname>CPublishSifOperationInfo::PublishStartL()</apiname></xref> can be invoked only once per operation. However, two parallel installations

can be initiated and <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-9F99E500-1FEE-308C-82A6-39523B1DCCDB"><apiname>CPublishSifOperationInfo::PublishStartL()</apiname></xref> can be invoked by each of the installation.</info>

</step>

<step id="GUID-60FC9468-9D44-4B9D-A554-2205C476D2B9"><cmd>Publish

the operation progress information.</cmd>

<substeps id="GUID-2D687BD2-783F-4D11-814B-E0B1270BCFC6">

<substep id="GUID-8C9D0A0B-551C-43E8-8D80-FDCAA70C07C3"><cmd>Create

a <xref href="GUID-DBEB6AEF-2128-3566-93AA-3CDB5D554B1E.dita"><apiname>CSifOperationProgressData</apiname></xref> object.</cmd>

<info>The parameters that need to be initialized are:<ul>

<li><p>global component id that uniquely identifies the package across

devices. For example, this could be the package uid in case of a native

SIS package or the midlet name for java.</p></li>

<li><p>phase of SIF operation</p></li>

<li><p>current stage in the type of SIF operation</p></li>

<li><p>progress of operation completed in current subphase</p></li>

<li><p>total operation required by this subphase</p></li>

</ul><codeblock xml:space="preserve">// A pointer to the newly allocated object is returned if creation is successful.

TInt phase = TSifOperationPhase::ESifOperationStart; 

TInt subPhase = TSifOperationSubPhase::EOCSPCheck; 

TInt curProgress = 75; 

TInt total = 100;

CSifOperationProgressData* progressdata = CSifOperationProgressData::NewLC(KGlobalCompId, phase, subPhase, curProgress, total);

</codeblock></info>

</substep>

<substep id="GUID-C6974F25-8B7B-4439-AC00-246D68C629F2"><cmd>Invoke

the <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-F8F8059B-DC62-32AB-931D-6E365CB6E6CC"><apiname>CPublishSifOperationInfo::PublishProgressL()</apiname></xref>.</cmd>

<info><codeblock xml:space="preserve">sifPublisher-&gt;PublishProgressL(*progressdata);</codeblock></info>

</substep>

</substeps>

<info><p><xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-F8F8059B-DC62-32AB-931D-6E365CB6E6CC"><apiname>CPublishSifOperationInfo::PublishProgressL()</apiname></xref> can be called iteratively to show the linear progress of the operation.</p></info>

</step>

<step id="GUID-829FAD26-C37B-4572-AEC2-64956F5511EC"><cmd>Publish

the operation completion information (on success or failure of operation).</cmd>

<substeps id="GUID-E5345271-C6F8-4732-BBC9-56EA7A8864A6">

<substep id="GUID-DEC78AB9-E3F9-4175-8163-099FECB54646"><cmd>Create

a <xref href="GUID-4F0E57D3-CE4C-3A41-951B-F2BB43E7BA34.dita"><apiname>CSifOperationEndData</apiname></xref> object.</cmd>

<info><p>The parameters that need to be initialized are:<ul>

<li><p>global component id that uniquely identifies the operation</p></li>

<li><p>a SIF error category</p></li>

<li><p>Installer (or runtime) specific error code</p></li>

<li><p>Installer (or runtime) specific localized error message</p></li>

<li><p>Installer (or runtime) specific localized error message details</p></li>

</ul></p><codeblock xml:space="preserve">TInt errCategory = TErrorCategory::ESecurityError;

TInt errCode = -10255;

_LIT(KErrMsg, "Un-trusted package");

_LIT(KErrMsgDetails, "The package is not signed with a trusted certificate.");

CSifOperationEndData* enddata = CSifOperationEndData::NewLC(KGlobalCompId, errCategory, errCode, KErrMsg, KErrMsgDetails);

</codeblock></info>

</substep>

<substep id="GUID-F16B9612-C128-4275-9B3A-0E7561A4531C"><cmd>Invoke

the <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-F7299F8C-9043-31FD-9758-8E25E839D2D7"><apiname>CPublishSifOperationInfo::PublishCompletionL()</apiname></xref>.</cmd>

<info><codeblock xml:space="preserve">sifPublisher-&gt;PublishCompletionL(*enddata);</codeblock></info>

</substep>

</substeps>

<info><p><xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-F7299F8C-9043-31FD-9758-8E25E839D2D7"><apiname>CPublishSifOperationInfo::PublishCompletionL()</apiname></xref> can be called only once per operation. Every call to <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-9F99E500-1FEE-308C-82A6-39523B1DCCDB"><apiname>CPublishSifOperationInfo::PublishStartL()</apiname></xref> by an operation must have a corresponding <xref href="GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6.dita#GUID-59E1372C-F4F8-3762-B6D9-B92BB5F53FC6/GUID-F7299F8C-9043-31FD-9758-8E25E839D2D7"><apiname>CPublishSifOperationInfo::PublishCompletionL()</apiname></xref>, else an

progress place holder is blocked for this operation.</p></info>

</step>

</steps>

</taskbody></task>