diff -r 5cc91383ab1e -r 7333d7932ef7 installationservices/swinstallationfw/inc/sifnotification.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/installationservices/swinstallationfw/inc/sifnotification.h Tue Aug 31 15:21:33 2010 +0300 @@ -0,0 +1,587 @@ +/* +* 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 +#include +#include +#include +#include + +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. + + @deprecated Use the overload with aOperationPhase instead. + + @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& aApplicationNames, + const RPointerArray& 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 + @param aOperationPhase The type of SIF operation + + @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& aApplicationNames, + const RPointerArray& aApplicationIcons, TInt aComponentSize, const TDesC& aIconPath, const TDesC& aComponentIcon, + const TDesC& aSoftwareType, TSifOperationPhase aOperationPhase); + + /** + Creates a CSifOperationStartData object. + + @deprecated Use the overload with aOperationPhase instead. + + @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& aApplicationNames, + const RPointerArray& 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 + @param aOperationPhase The type of SIF operation + + @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& aApplicationNames, + const RPointerArray& aApplicationIcons, TInt aComponentSize, const TDesC& aIconPath, const TDesC& aComponentIcon, + const TDesC& aSoftwareType, TSifOperationPhase aOperationPhase); + + /** + @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& ApplicationNames() const; + + /** + @return An array of application icons. + */ + IMPORT_C const RPointerArray& 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; + + /** + @return The type of SIF operation. + */ + IMPORT_C TSifOperationPhase OperationPhase() const; + +private: + CSifOperationStartData(); + void ConstructL(const TDesC& aGlobalComponentId, const TDesC& aComponentName, const RPointerArray& aApplicationNames, + const RPointerArray& aApplicationIcons, TInt aComponentSize, const TDesC& aIconPath, + const TDesC& aComponentIcon, const TDesC& aSoftwareType, TSifOperationPhase aOperationPhase); + void InternalizeL(RReadStream& aStream); + +private: + HBufC* iGlobalComponentId; + HBufC* iComponentName; + HBufC* iComponentIcon; + RPointerArray iApplicationNames; + RPointerArray iApplicationIcons; + TInt iComponentSize; + HBufC* iIconPath; + HBufC* iSoftwareType; + TSifOperation iOperationType; + TSifOperationPhase iOperationPhase; + }; + + +/* + * 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. + + @deprecated Use CurrentProgress() instead. + */ + IMPORT_C TInt CurrentProgess() const; + + /** + @return The current progress value. + */ + IMPORT_C TInt CurrentProgress() 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& aKeys); + void ActiveOperationsNotificationL(); + void WaitForChangeL(); + void ConstructL(); + void RunL(); + void DoCancel(); + TInt RunError(TInt aError); + +private: + MSifOperationsHandler& iHandler; + TInt iBufferSize; + RArray iKeyArray; + RProperty iProperty; + RPointerArray iNotifierArray; + TNotifierState iNotifierState; + }; + + +} // namespace + +#endif