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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

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

    12 <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

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

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

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

    16 for SIF operation progress.</p></prereq>

    17 <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">

    18 <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

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

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

    21 to receive notifications. </cmd>

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

    23     {

    24     //  Virtual Handler Functions

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

    26     void EndOperationHandler(const CSifOperationEndData& aEndData);

    27     void ProgressOperationHandler(const CSifOperationProgressData& aProgressData);

    28     private:

    29     CSifOperationsNotifier* iNotifier;

    30     }

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

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

    33     {

    34     iNotifier = CSifOperationsNotifier::NewL(*this);

    35     }

    36 </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

    37 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

    38 invoked in the implementation of StartOperationHandler(). The first

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

    40 second parameter is a boolean  to specify optional subscription to

    41 progress information. Setting the value to ETrue subscribes to both

    42 progress and end notification  and setting the value to Efalse subscribes

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

    44 	const CSifOperationStartData& aStartData)

    45     {

    46     iNotifier->SubscribeL(aKey, ETrue);

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

    48     aStartData.GlobalComponentId());

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

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

    51     {

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

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

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

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

    56     {

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

    58     	aEndData.GlobalComponentId());

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

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

    61     }</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

    62 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>

    63 </step>

    64 </steps>

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

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

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

    68 </taskbody></task>