<?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-FDA575AB-F5A5-4244-B47C-F1B1794F09F6" xml:lang="en"><title>Subscribing to SIF operation progress</title><shortdesc>Clients must subscribe to SIF operation progress to receive

status of operations (installation or uninstallation).</shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq id="GUID-E8D8FA6D-7CFE-457F-9B3C-E77DC1823132"><p>The client

applications must link against <filepath>Sifnotification.dll</filepath> . It is the utility library that provides the APIs to subscribe

for 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-6-1-3-2">

<step id="GUID-9A69E5AD-E938-4092-A8C2-CB65C37C8962-GENID-1-12-1-5-1-1-6-1-4-1-4-1-6-1-3-2-1"><cmd>Derive from

the <xref href="GUID-4683B704-D21C-3D42-82BB-2B4B88B4974C.dita"><apiname>MSifOperationsHandler</apiname></xref> abstract handler class.

Clients must implement<xref href="GUID-4683B704-D21C-3D42-82BB-2B4B88B4974C.dita"><apiname> MSifOperationsHandler</apiname></xref> interfaces

to receive notifications. </cmd>

<info><codeblock xml:space="preserve">Class CMySifOperationHandler : public MSifOperationsHandler

    {

    //  Virtual Handler Functions

    void StartOperationHandler(TUint aKey,const CSifOperationStartData& aStartData);

    void EndOperationHandler(const CSifOperationEndData& aEndData);

    void ProgressOperationHandler(const CSifOperationProgressData& aProgressData);

    private:

    CSifOperationsNotifier* iNotifier;

    }

</codeblock><p>Create a <xref href="GUID-33D234E5-2970-3521-BDB9-EE29C9165856.dita"><apiname>CSifOperationsNotifier</apiname></xref> object

by passing the handler object. </p><codeblock xml:space="preserve">CMySifOperationHandler::ConstructL()

    {

    iNotifier = CSifOperationsNotifier::NewL(*this);

    }

</codeblock><p>Implement the virtual functions <xref href="GUID-0AFB93FF-539D-3342-AB9C-8E15C440DB47.dita"><apiname>StartOperationHandler()</apiname></xref>, <xref href="GUID-C2E7966B-6EA5-376D-91E3-2467AF6CCF4E.dita"><apiname>EndOperationHandler()</apiname></xref>, <xref href="GUID-43E7CE06-D669-3BAF-A12E-318C2DD8E49F.dita"><apiname>ProgressOperationHandler()</apiname></xref> .</p><p><xref href="GUID-0AFB93FF-539D-3342-AB9C-8E15C440DB47.dita"><apiname>StartOperationHandler()</apiname></xref> is called when

a new operation is started. The subscriber must use the <xref href="GUID-33D234E5-2970-3521-BDB9-EE29C9165856.dita#GUID-33D234E5-2970-3521-BDB9-EE29C9165856/GUID-245A356C-D1B4-37B7-BFC6-08D1439156F4"><apiname>CSifOperationsNotifier::SubscribeL()</apiname></xref> to register for progress and end notification for the operation.</p><p><xref href="GUID-33D234E5-2970-3521-BDB9-EE29C9165856.dita#GUID-33D234E5-2970-3521-BDB9-EE29C9165856/GUID-245A356C-D1B4-37B7-BFC6-08D1439156F4"><apiname>CSifOperationsNotifier::SubscribeL()</apiname></xref> must be

invoked in the implementation of StartOperationHandler(). The first

parameter is the key to uniquely identify an ongoing operation. The

second parameter is a boolean  to specify optional subscription to

progress information. Setting the value to ETrue subscribes to both

progress and end notification  and setting the value to Efalse subscribes

to only end notification. </p><codeblock xml:space="preserve">void CMySifOperationHandler::StartOperationHandler(TUint aKey,

	const CSifOperationStartData& aStartData)

    {

    iNotifier->SubscribeL(aKey, ETrue);

    DEBUG_PRINTF2(_L8("Subscribing to progress information for component: %S."),

    aStartData.GlobalComponentId());

    }</codeblock><p><xref href="GUID-43E7CE06-D669-3BAF-A12E-318C2DD8E49F.dita"><apiname>ProgressOperationHandler()</apiname></xref> is

invoked when progress update is available .</p><codeblock xml:space="preserve">void ProgressOperationHandler(const CSifOperationProgressData&amp; aProgressData)

    {

    DEBUG_PRINTF2(_L8("%S progress: %d out of %d."), aProgressData.GlobalComponentId(),

    	aProgressData.CurrentProgress(), aProgressData.Total());

    }</codeblock><p><xref href="GUID-C2E7966B-6EA5-376D-91E3-2467AF6CCF4E.dita"><apiname>EndOperationHandler()</apiname></xref> functions

are invoked when operation completes.</p><codeblock xml:space="preserve">void CMySifOperationHandler::EndOperationHandler(const CSifOperationEndData&amp; aEndData)

    {

    DEBUG_PRINTF2(_L8("SIF operation on %S is complete."),  

    	aEndData.GlobalComponentId());

    DEBUG_PRINTF2(_L8("ErrorCode: %d."), aEndData.ErrorCode());

    DEBUG_PRINTF2(_L8("ErrorMessage: %S."), aEndData.ErrorMessage());

    }</codeblock><p>Both <xref href="GUID-43E7CE06-D669-3BAF-A12E-318C2DD8E49F.dita"><apiname>ProgressOperationHandler()</apiname></xref> and <xref href="GUID-C2E7966B-6EA5-376D-91E3-2467AF6CCF4E.dita"><apiname>EndOperationHandler()</apiname></xref> should return quickly

as they are run as part of an active object request completion handler. </p><p>The client can cancel the subscription by invoking <xref href="GUID-33D234E5-2970-3521-BDB9-EE29C9165856.dita#GUID-33D234E5-2970-3521-BDB9-EE29C9165856/GUID-760423DF-24A6-384D-9882-25130933FCB1"><apiname>CSifOperationsNotifier::CancelSubscribeL()</apiname></xref>.<codeblock xml:space="preserve"> iNotifier-&gt;CancelSubscribeL(aKey);</codeblock></p></info>

</step>

</steps>

<result id="GUID-904D6009-3DC7-497A-93CC-17B28872A316"><p>The client

now receives the start, progress and end status notifications as and

when published by the installer. </p></result>

</taskbody></task>