/*

* Copyright (c) 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:

*

* Description: 

* sifnotification.h - Interfaces to publish (by installers) and get notified (for clients) to an SIF operation progress

*

*/

/**

 @file

 @released

 @publishedPartner

*/

#ifndef __SIFNOTIFICATION_H__

#define __SIFNOTIFICATION_H__

#include <e32std.h>

#include <e32base.h>

#include <s32strm.h>

#include <usif/usiferror.h>

#include <e32property.h> 

namespace Usif

{

// Forward declaration.

class CSifNotifierBase;

class CDeleteKeyTimer;

//Identifies the type of operation

enum TSifOperationPhase

    {

    EInstalling = 1,

    EUninstalling,

    EUpgrading

    };

//Identifies a stage in type of operation

enum TSifOperationSubPhase 

    {

    ENoSubPhase = 1,

    EOCSPCheck,

    EDownload,

    EFileOperation

    };

enum TSifOperation

    {

    ESifOperationStart = 1,

    ESifOperationEnd

    };

/*

 * This contains the basic information of package going to be installed/uninstalled (provided at the start of the operation)

 */

NONSHARABLE_CLASS(CSifOperationStartData) : public CBase    

    {

public:

    /**

        Creates a CSifOperationStartData object from the stream.

        @param  aStream   The stream to read the CSifOperationStartData object from.

        @return A pointer to the newly allocated CSifOperationStartData object, if creation is successful.

     */ 

    IMPORT_C static CSifOperationStartData* NewL(RReadStream& aStream);

    /**

        Creates a CSifOperationStartData object.

        @param  aGlobalComponentId  The global component id which uniquely identifies the operation          

        @param  aComponentName		The name of the software component

        @param  aApplicationNames	The list of applications associated with the software component, an empty array in case of no applications

        @param  aApplicationIcons   The list of corresponding application icon names(without path) for every application, an empty array in case of no applications                 

        @param  aComponentSize		The total size of the component in bytes

        @param  aIconPath			The path where all application and component icons are found

        @param  aComponentIcon		The name of the component icon(without path)

        @param  aSoftwareType		The software type name of the software component

        @return A pointer to the newly allocated CSifOperationStartData object, if creation is successful.

     */      

    IMPORT_C static CSifOperationStartData* NewL(const TDesC& aGlobalComponentId, const TDesC& aComponentName, const RPointerArray<HBufC>& aApplicationNames,

                                                  const RPointerArray<HBufC>& aApplicationIcons, TInt aComponentSize, const TDesC& aIconPath, const TDesC& aComponentIcon, const TDesC& aSoftwareType);

    /**

        Creates a CSifOperationStartData object.

        @param  aGlobalComponentId  The global component id which uniquely identifies the operation          

        @param  aComponentName      The name of the software component

        @param  aApplicationNames   The list of applications associated with the software component, an empty array in case of no applications

        @param  aApplicationIcons   The list of corresponding application icon names(without path) for every application, an empty array in case of no applications                 

        @param  aComponentSize      The total size of the component in bytes

        @param  aIconPath           The path where all application and component icons are found

        @param  aComponentIcon      The name of the component icon(without path)

        @param  aSoftwareType       The software type name of the software component

        @return A pointer to the newly allocated CSifOperationStartData object, if creation is successful.

                The pointer is also put onto the cleanup stack. 

     */     

    IMPORT_C static CSifOperationStartData* NewLC(const TDesC& aGlobalComponentId, const TDesC& aComponentName, const RPointerArray<HBufC>& aApplicationNames,

                                                  const RPointerArray<HBufC>& aApplicationIcons, TInt aComponentSize, const TDesC& aIconPath, const TDesC& aComponentIcon, const TDesC& aSoftwareType);

    /**

     @return The global component Id associated with the operation.

     */     

    IMPORT_C const HBufC& GlobalComponentId() const;

    /**

     @return The component name associated with the operation.

     */     

    IMPORT_C const HBufC& ComponentName() const;

    /**

     @return An array of application names.

     */     

    IMPORT_C const RPointerArray<HBufC>& ApplicationNames() const;

    /**

     @return An array of application icons.

     */     

    IMPORT_C const RPointerArray<HBufC>& ApplicationIcons() const;

    /**

     @return The size of the component in bytes.

     */      

    IMPORT_C TInt ComponentSize() const;    

    /**

     @return The path to the application icons.

     */     

    IMPORT_C const HBufC& IconPath() const; 

    /**

     @return The icon associated with the component.

     */      

    IMPORT_C const HBufC& ComponentIcon() const;

    /**

     @return The software type associated with the operation.

     */      

    IMPORT_C const HBufC& SoftwareType() const;    

    IMPORT_C ~CSifOperationStartData();          

    IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

private:

    CSifOperationStartData();

    void ConstructL(const TDesC& aGlobalComponentId, const TDesC& aComponentName, const RPointerArray<HBufC>& aApplicationNames,  

          const RPointerArray<HBufC>& aApplicationIcons, TInt aComponentSize, const TDesC& aIconPath, const TDesC& aComponentIcon, const TDesC& aSoftwareType);

    void InternalizeL(RReadStream& aStream);

private:

    HBufC* iGlobalComponentId;                                    

    HBufC* iComponentName;

    HBufC* iComponentIcon;

    RPointerArray<HBufC> iApplicationNames;

    RPointerArray<HBufC> iApplicationIcons;          

    TInt iComponentSize;

    HBufC* iIconPath;      

    HBufC* iSoftwareType;

    TSifOperation iOperationType;

    };

/*

 * This contains the error status information after an install/uninstall operation

 */

NONSHARABLE_CLASS(CSifOperationEndData) : public CBase

    {      

public:

    /**

        Creates a CSifOperationEndData object from the stream.

        @param  aStream   The stream to read the CSifOperationEndData object from.

        @return A pointer to the newly allocated CSifOperationEndData object, if creation is successful.

     */     

    IMPORT_C static CSifOperationEndData* NewL(RReadStream& aStream);

    /**

        Creates a CSifOperationEndData object.

        @param  aGlobalComponentId  The global component id which uniquely identifies the operation          

        @param  aErrCategory		A SIF error category

        @param  aErrCode			SIF plugin (or runtime) specific error code

        @param  aErrMsg				SIF plugin (or runtime) specific localized error message         

        @param  aErrMsgDetails		SIF plugin (or runtime) specific localized message details

        @return A pointer to the newly allocated CSifOperationEndData object, if creation is successful.

     */     

    IMPORT_C static CSifOperationEndData* NewL(const TDesC& aGlobalComponentId, TErrorCategory aErrCategory, TInt aErrCode, const TDesC& aErrMsg, const TDesC& aErrMsgDetails);    

    /**

        Creates a CSifOperationEndData object.

        @param  aGlobalComponentId  The global component id which uniquely identifies the operation          

        @param  aErrCategory		A SIF error category

        @param  aErrCode			SIF plugin (or runtime) specific error code

        @param  aErrMsg				SIF plugin (or runtime) specific localized error message         

        @param  aErrMsgDetails		SIF plugin (or runtime) specific localized message details

        @return A pointer to the newly allocated CSifOperationEndData object, if creation is successful.

                The pointer is also put onto the cleanup stack. 

     */         

    IMPORT_C static CSifOperationEndData* NewLC(const TDesC& aGlobalComponentId, TErrorCategory aErrCategory, TInt aErrCode, const TDesC& aErrMsg, const TDesC& aErrMsgDetails);

    /**

     @return The global component Id associated with the operation.

     */     

    IMPORT_C const HBufC& GlobalComponentId() const;

    /**

    @return The category to which the error belongs.

    */     

    IMPORT_C TErrorCategory ErrorCategory() const;

    /**

    @return An error code associated with the operation.

    */     

    IMPORT_C TInt ErrorCode() const;  

    /**

     @return An error message.

     */     

    IMPORT_C const HBufC& ErrorMessage() const;

    /**

     @return More details regarding the error message. 

     */     

    IMPORT_C const HBufC& ErrorMessageDetails() const;

    IMPORT_C ~CSifOperationEndData();

    IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

private:

    CSifOperationEndData();

    void ConstructL(const TDesC& aGlobalComponentID, TErrorCategory aErrCategory, TInt aErrCode, const TDesC& aErrMsg, const TDesC& aErrMsgDetails);

    void InternalizeL(RReadStream& aStream);

private:     

    HBufC* iGlobalComponentId;   

    HBufC* iErrMsg;                                    

    HBufC* iErrMsgDetails;

    TErrorCategory iErrCategory; 

    TInt iErrCode;      

    TSifOperation iOperationType;

    };

/*

 * This class provides the operation progress.

 */

NONSHARABLE_CLASS(CSifOperationProgressData) : public CBase

    {

    public:

    /**

        Creates a CSifOperationProgressData object from the stream.

        @param  aStream   The stream to read the CSifOperationProgressData object from.

        @return A pointer to the newly allocated CSifOperationProgressData object, if creation is successful.

     */          

    IMPORT_C static CSifOperationProgressData* NewL(RReadStream& aStream);

    /**

        Creates a CSifOperationProgressData object.

        @param  aGlobalComponentId  The global component id which uniquely identifies the operation           

        @param  aPhase				The type of SIF operation

        @param  aSubPhase			The current stage in the type of SIF operation

        @param  aCurrentProgress    The amount of operation which is completed in current subphase

        @param  aTotal				The total amount of operation required by this subphase operation

        @return A pointer to the newly allocated CSifOperationProgressData object, if creation is successful.

     */      

    IMPORT_C static CSifOperationProgressData* NewL(const TDesC& aGlobalcomponentId, TSifOperationPhase aPhase, TSifOperationSubPhase aSubPhase, TInt aCurrentProgress, TInt aTotal);      

    /**

        Creates a CSifOperationProgressData object.

        @param  aGlobalComponentId  The global component id which uniquely identifies the operation           

        @param  aPhase				The type of SIF operation

        @param  aSubPhase			The current stage in the type of SIF operation

        @param  aCurrentProgress    The amount of operation which is completed in current subphase

        @param  aTotal				The total amount of operation required by this subphase operation

        @return A pointer to the newly allocated CSifOperationProgressData object, if creation is successful.

                The pointer is also put onto the cleanup stack. 

     */     

    IMPORT_C static CSifOperationProgressData* NewLC(const TDesC& aGlobalcomponentId, TSifOperationPhase aPhase, TSifOperationSubPhase aSubPhase, TInt aCurrentProgress, TInt aTotal);

    /**

     @return The global component id associated with the operation.

     */ 

    IMPORT_C const HBufC& GlobalComponentId() const;

    /**

     @return The current phase of operation.

     */     

    IMPORT_C TSifOperationPhase Phase() const;

    /**

     @return The current sub-phase of operation.

     */    

    IMPORT_C TSifOperationSubPhase SubPhase() const;

    /**

     @return The current progress value.

     */     

    IMPORT_C TInt CurrentProgess() const;

    /**

     @return The total value to achieve completion of the subphase.

     */     

    IMPORT_C TInt Total() const;  

    IMPORT_C ~CSifOperationProgressData();               

    IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

private:

    CSifOperationProgressData();

    void ConstructL(const TDesC& aGlobalcomponentId, TSifOperationPhase aPhase, TSifOperationSubPhase aSubPhase, TInt aCurrentProgress, TInt aTotal);

    void InternalizeL(RReadStream& aStream);

private:   

    HBufC* iGlobalComponentId;       

    TSifOperationPhase iPhase;

    TSifOperationSubPhase iSubPhase;

    TInt iCurrentProgress;

    TInt iTotal;

    };

/**

 * This class will be used by installers to publish a single install/uninstall/update operation information.

 * A scheduler needs to be in started when using this class.

 */

NONSHARABLE_CLASS(CPublishSifOperationInfo) : public CBase

    {

public:

    /**

        Creates a CPublishSifOperationInfo object.

        @return A pointer to the newly allocated CPublishSifOperationInfo object, if creation is successful.

     */       

    IMPORT_C static CPublishSifOperationInfo* NewL();

    /**

        Creates a CPublishSifOperationInfo object.

        @return A pointer to the newly allocated CPublishSifOperationInfo object, if creation is successful.

                The pointer is also put onto the cleanup stack. 

     */       

    IMPORT_C static CPublishSifOperationInfo* NewLC();

    /**

		Publish the start of an operation. The corresponding PublishCompletionL() method should be called later

		else an opeartion place holder is always blocked for this operation which has started.       

		@capability WriteDeviceData

		@param aStartData Start operation related information.

		@leave KErrInUse No more slots are available to publish.

     */

    IMPORT_C void PublishStartL(CSifOperationStartData& aStartData);

    /**

		Publish the operation progress information

		@capability WriteDeviceData

		@param aProgressData Progress operation related information.

     */

    IMPORT_C void PublishProgressL(CSifOperationProgressData& aProgressData);

    /**

		Publish the error status of the operation (at the end)

		@capability WriteDeviceData

		@param aEndData End operation related information.

     */

    IMPORT_C void PublishCompletionL(CSifOperationEndData& aEndData);

    IMPORT_C ~CPublishSifOperationInfo(); 

private:

    void SetKeyToDelete(TUint aStartEndKey);

    void SetStartEndKey(TUint aStartEndKey);

    CPublishSifOperationInfo();

    void ConstructL();

    TUint AvailableKeyL();

    TUint KeyForGlobalComponentIdL(const TDesC& aGlobalComponentId);

private:

    CDeleteKeyTimer* iDeleteTimer;

    TInt iBufferSize;

    TUint iStartEndKey;

    };

/**

 * MSifOperationsHandler

 * Clients must implement this class in order to receive notifications.

 */

class MSifOperationsHandler

    {

public:

    /**

       Called when a new operation is started. The client should use the SubscribeL() method 

       (@see CSifOperationsNotifier) to register for progress and end notification for this operation.

       This function should return quickly as this is run as part of an active object request completion handler.

       @param aKey The Start End key of the operation.

       @param aStartData Start operation related information.

     */

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

    /**

       Called when an operation completes.

       This function should return quickly as this is run as part of an active object request completion handler.

       @param aEndData End operation related information.

     */

    virtual void EndOperationHandler(const CSifOperationEndData& aEndData) = 0;

    /**

       Called whenever a progress update is available.

       This function should return quickly as this is run as part of an active object request completion handler.

       @param aProgressData Progress operation related information.

     */   

    virtual void ProgressOperationHandler(const CSifOperationProgressData& aProgressData) = 0;

    virtual ~MSifOperationsHandler() {}

    };

/**

 * CSifOperationsNotifier

 *

 * Clients must create a CSifOperationsNotifier object by passing in the handler object.

 *

 * For every new Sif Operation, the StartOperationHandler() method of the handler would be called along

 * with some related information. The client can choose to subscribe to this operation by calling the 

 * SubscribeL() method.

 * 

 * A scheduler needs to be started when using this class.

 */

NONSHARABLE_CLASS(CSifOperationsNotifier) : public CActive

    {

public:    

    /**

        Creates a CSifOperationsNotifier object.

        @param  aHandler A handle to the implementation of the MSifOperationsHandler class.      

        @return A pointer to the newly allocated CSifOperationsNotifier object, if creation is successful.

     */         

    IMPORT_C static CSifOperationsNotifier* NewL(MSifOperationsHandler& aHandler);

    /**

        Creates a CSifOperationsNotifier object.

        @param  aHandler A handle to the implementation of the MSifOperationsHandler class.     

        @return A pointer to the newly allocated CSifOperationsNotifier object, if creation is successful.

                The pointer is also put onto the cleanup stack. 

     */         

    IMPORT_C static CSifOperationsNotifier* NewLC(MSifOperationsHandler& aHandler);

    /**

       Subscribe for progress and end notifications or only end notification.

       @param aKey The StartEnd key assoicated with the operation.

       @param aSubscribeForProgressNotifications Boolean to specify optional subscription to progreess information.

     */

    IMPORT_C void SubscribeL(TUint aKey, TBool aSubscribeForProgressNotifications = ETrue);

    /**

       Cancel Subscription for a specific key.

       @param aKey The StartEnd key assoicated with the operation.

     */    

    IMPORT_C void CancelSubscribeL(TUint aKey);

    /**

       Cancel all subscriptions.

     */      

    IMPORT_C void CancelSubscribeL();

    IMPORT_C ~CSifOperationsNotifier();

private:

    enum TNotifierState

        {

        EFirstStart,

        EWaitForChange

        };

    CSifOperationsNotifier(MSifOperationsHandler& aHandler);

    void GetKeysL(RArray<TUint>& aKeys);

    void ActiveOperationsNotificationL();

    void WaitForChangeL();

    void ConstructL();

    void RunL();

    void DoCancel();

    TInt RunError(TInt aError);

private:

    MSifOperationsHandler& iHandler;

    TInt iBufferSize;   

    RArray<TUint> iKeyArray;

    RProperty iProperty;

    RPointerArray<CSifNotifierBase> iNotifierArray;

    TNotifierState iNotifierState;

    };

} // namespace

#endif