1 /*

     2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

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

    16 *

    17 */

    18 

    19 /**

    20  @file

    21  @released

    22  @publishedPartner

    23 */

    24 

    25 #ifndef __SIFNOTIFICATION_H__

    26 #define __SIFNOTIFICATION_H__

    27 

    28 #include <e32std.h>

    29 #include <e32base.h>

    30 #include <s32strm.h>

    31 #include <usif/usiferror.h>

    32 #include <e32property.h> 

    33 

    34 namespace Usif

    35 {

    36 // Forward declaration.

    37 class CSifNotifierBase;

    38 class CDeleteKeyTimer;

    39 

    40 //Identifies the type of operation

    41 enum TSifOperationPhase

    42     {

    43     EInstalling = 1,

    44     EUninstalling,

    45     EUpgrading

    46     };

    47 

    48 //Identifies a stage in type of operation

    49 enum TSifOperationSubPhase 

    50     {

    51     ENoSubPhase = 1,

    52     EOCSPCheck,

    53     EDownload,

    54     EFileOperation

    55     };

    56 

    57 enum TSifOperation

    58     {

    59     ESifOperationStart = 1,

    60     ESifOperationEnd

    61     };

    62 

    63 

    64 /*

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

    66  */

    67 NONSHARABLE_CLASS(CSifOperationStartData) : public CBase    

    68     {

    69 public:

    70     /**

    71         Creates a CSifOperationStartData object from the stream.

    72              

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

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

    75      */ 

    76     IMPORT_C static CSifOperationStartData* NewL(RReadStream& aStream);

    77     

    78     /**

    79         Creates a CSifOperationStartData object.

    80         

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

    82         @param  aComponentName		The name of the software component

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

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

    85         @param  aComponentSize		The total size of the component in bytes

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

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

    88         @param  aSoftwareType		The software type name of the software component

    89                                                    

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

    91      */      

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

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

    94 

    95     /**

    96         Creates a CSifOperationStartData object.

    97         

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

    99         @param  aComponentName      The name of the software component

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

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

   102         @param  aComponentSize      The total size of the component in bytes

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

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

   105         @param  aSoftwareType       The software type name of the software component

   106                                                    

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

   108                 The pointer is also put onto the cleanup stack. 

   109      */     

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

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

   112     

   113     /**

   114      @return The global component Id associated with the operation.

   115      */     

   116     IMPORT_C const HBufC& GlobalComponentId() const;

   117     

   118     /**

   119      @return The component name associated with the operation.

   120      */     

   121     IMPORT_C const HBufC& ComponentName() const;

   122     

   123     /**

   124      @return An array of application names.

   125      */     

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

   127     

   128     /**

   129      @return An array of application icons.

   130      */     

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

   132     

   133     /**

   134      @return The size of the component in bytes.

   135      */      

   136     IMPORT_C TInt ComponentSize() const;    

   137     

   138     /**

   139      @return The path to the application icons.

   140      */     

   141     IMPORT_C const HBufC& IconPath() const; 

   142    

   143     /**

   144      @return The icon associated with the component.

   145      */      

   146     IMPORT_C const HBufC& ComponentIcon() const;

   147     

   148     /**

   149      @return The software type associated with the operation.

   150      */      

   151     IMPORT_C const HBufC& SoftwareType() const;    

   152     

   153     IMPORT_C ~CSifOperationStartData();          

   154 

   155     IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   156 

   157 private:

   158     CSifOperationStartData();

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

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

   161     void InternalizeL(RReadStream& aStream);

   162 

   163 private:

   164     HBufC* iGlobalComponentId;                                    

   165     HBufC* iComponentName;

   166     HBufC* iComponentIcon;

   167     RPointerArray<HBufC> iApplicationNames;

   168     RPointerArray<HBufC> iApplicationIcons;          

   169     TInt iComponentSize;

   170     HBufC* iIconPath;      

   171     HBufC* iSoftwareType;

   172     TSifOperation iOperationType;

   173     };

   174 

   175 

   176 /*

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

   178  */

   179 NONSHARABLE_CLASS(CSifOperationEndData) : public CBase

   180     {      

   181 public:

   182     /**

   183         Creates a CSifOperationEndData object from the stream.

   184              

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

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

   187      */     

   188     IMPORT_C static CSifOperationEndData* NewL(RReadStream& aStream);

   189     

   190     /**

   191         Creates a CSifOperationEndData object.

   192         

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

   194         @param  aErrCategory		A SIF error category

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

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

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

   198                                                         

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

   200      */     

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

   202 

   203     /**

   204         Creates a CSifOperationEndData object.

   205         

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

   207         @param  aErrCategory		A SIF error category

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

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

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

   211                                                         

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

   213                 The pointer is also put onto the cleanup stack. 

   214      */         

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

   216 

   217     /**

   218      @return The global component Id associated with the operation.

   219      */     

   220     IMPORT_C const HBufC& GlobalComponentId() const;

   221     

   222     /**

   223     @return The category to which the error belongs.

   224     */     

   225     IMPORT_C TErrorCategory ErrorCategory() const;

   226        

   227     /**

   228     @return An error code associated with the operation.

   229     */     

   230     IMPORT_C TInt ErrorCode() const;  

   231        

   232     /**

   233      @return An error message.

   234      */     

   235     IMPORT_C const HBufC& ErrorMessage() const;

   236     

   237     /**

   238      @return More details regarding the error message. 

   239      */     

   240     IMPORT_C const HBufC& ErrorMessageDetails() const;

   241        

   242     IMPORT_C ~CSifOperationEndData();

   243   

   244     IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   245 

   246 private:

   247     CSifOperationEndData();

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

   249     void InternalizeL(RReadStream& aStream);

   250 

   251 private:     

   252     HBufC* iGlobalComponentId;   

   253     HBufC* iErrMsg;                                    

   254     HBufC* iErrMsgDetails;

   255     TErrorCategory iErrCategory; 

   256     TInt iErrCode;      

   257     TSifOperation iOperationType;

   258     };

   259 

   260 

   261 /*

   262  * This class provides the operation progress.

   263  */

   264 NONSHARABLE_CLASS(CSifOperationProgressData) : public CBase

   265     {

   266     public:

   267     /**

   268         Creates a CSifOperationProgressData object from the stream.

   269              

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

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

   272      */          

   273     IMPORT_C static CSifOperationProgressData* NewL(RReadStream& aStream);

   274     

   275     /**

   276         Creates a CSifOperationProgressData object.

   277         

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

   279         @param  aPhase				The type of SIF operation

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

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

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

   283                                                         

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

   285      */      

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

   287 

   288     /**

   289         Creates a CSifOperationProgressData object.

   290         

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

   292         @param  aPhase				The type of SIF operation

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

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

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

   296                                                         

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

   298                 The pointer is also put onto the cleanup stack. 

   299      */     

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

   301 

   302     /**

   303      @return The global component id associated with the operation.

   304      */ 

   305     IMPORT_C const HBufC& GlobalComponentId() const;

   306     

   307     /**

   308      @return The current phase of operation.

   309      */     

   310     IMPORT_C TSifOperationPhase Phase() const;

   311     

   312     /**

   313      @return The current sub-phase of operation.

   314      */    

   315     IMPORT_C TSifOperationSubPhase SubPhase() const;

   316     

   317     /**

   318      @return The current progress value.

   319      */     

   320     IMPORT_C TInt CurrentProgess() const;

   321     

   322     /**

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

   324      */     

   325     IMPORT_C TInt Total() const;  

   326     

   327     IMPORT_C ~CSifOperationProgressData();               

   328 

   329     IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   330 

   331 private:

   332     CSifOperationProgressData();

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

   334     void InternalizeL(RReadStream& aStream);

   335 

   336 private:   

   337     HBufC* iGlobalComponentId;       

   338     TSifOperationPhase iPhase;

   339     TSifOperationSubPhase iSubPhase;

   340     TInt iCurrentProgress;

   341     TInt iTotal;

   342     };

   343 

   344 /**

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

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

   347  */

   348 NONSHARABLE_CLASS(CPublishSifOperationInfo) : public CBase

   349     {

   350 public:

   351     

   352     /**

   353         Creates a CPublishSifOperationInfo object.

   354                                                         

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

   356      */       

   357     IMPORT_C static CPublishSifOperationInfo* NewL();

   358   

   359     /**

   360         Creates a CPublishSifOperationInfo object.

   361                              

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

   363                 The pointer is also put onto the cleanup stack. 

   364      */       

   365     IMPORT_C static CPublishSifOperationInfo* NewLC();

   366     

   367     /**

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

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

   370        

   371 		@capability WriteDeviceData

   372 		@param aStartData Start operation related information.

   373 		@leave KErrInUse No more slots are available to publish.

   374      */

   375     IMPORT_C void PublishStartL(CSifOperationStartData& aStartData);

   376 

   377     /**

   378 		Publish the operation progress information

   379        

   380 		@capability WriteDeviceData

   381 		@param aProgressData Progress operation related information.

   382      */

   383     IMPORT_C void PublishProgressL(CSifOperationProgressData& aProgressData);

   384 

   385     /**

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

   387        

   388 		@capability WriteDeviceData

   389 		@param aEndData End operation related information.

   390      */

   391     IMPORT_C void PublishCompletionL(CSifOperationEndData& aEndData);

   392     

   393     IMPORT_C ~CPublishSifOperationInfo(); 

   394     

   395 private:

   396     void SetKeyToDelete(TUint aStartEndKey);

   397     void SetStartEndKey(TUint aStartEndKey);

   398     CPublishSifOperationInfo();

   399     void ConstructL();

   400     TUint AvailableKeyL();

   401     TUint KeyForGlobalComponentIdL(const TDesC& aGlobalComponentId);

   402     

   403 private:

   404     CDeleteKeyTimer* iDeleteTimer;

   405     TInt iBufferSize;

   406     TUint iStartEndKey;

   407     };

   408 

   409 /**

   410  * MSifOperationsHandler

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

   412  */

   413 class MSifOperationsHandler

   414     {

   415 public:

   416     /**

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

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

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

   420 

   421        @param aKey The Start End key of the operation.

   422        @param aStartData Start operation related information.

   423      */

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

   425     

   426     /**

   427        Called when an operation completes.

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

   429 

   430        @param aEndData End operation related information.

   431      */

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

   433    

   434     /**

   435        Called whenever a progress update is available.

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

   437 

   438        @param aProgressData Progress operation related information.

   439      */   

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

   441     virtual ~MSifOperationsHandler() {}

   442     };

   443 

   444 /**

   445  * CSifOperationsNotifier

   446  *

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

   448  *

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

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

   451  * SubscribeL() method.

   452  * 

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

   454  */

   455 NONSHARABLE_CLASS(CSifOperationsNotifier) : public CActive

   456     {

   457 public:    

   458     

   459     /**

   460         Creates a CSifOperationsNotifier object.

   461         

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

   463                                         

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

   465                 The pointer is also put onto the cleanup stack. 

   466      */         

   467     IMPORT_C static CSifOperationsNotifier* NewL(MSifOperationsHandler& aHandler);

   468     

   469     /**

   470         Creates a CSifOperationsNotifier object.

   471         

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

   473                                                         

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

   475                 The pointer is also put onto the cleanup stack. 

   476      */         

   477     IMPORT_C static CSifOperationsNotifier* NewLC(MSifOperationsHandler& aHandler);

   478     

   479     /**

   480        Subscribe for progress and end notifications or only end notification.

   481        

   482        @param aKey The StartEnd key assoicated with the operation.

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

   484      */

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

   486     

   487     /**

   488        Cancel Subscription for a specific key.

   489        

   490        @param aKey The StartEnd key assoicated with the operation.

   491      */    

   492     IMPORT_C void CancelSubscribeL(TUint aKey);

   493     

   494     /**

   495        Cancel all subscriptions.

   496      */      

   497     IMPORT_C void CancelSubscribeL();

   498     

   499     IMPORT_C ~CSifOperationsNotifier();

   500 

   501 private:

   502     enum TNotifierState

   503         {

   504         EFirstStart,

   505         EWaitForChange

   506         };

   507     CSifOperationsNotifier(MSifOperationsHandler& aHandler);

   508     void GetKeysL(RArray<TUint>& aKeys);

   509     void ActiveOperationsNotificationL();

   510     void WaitForChangeL();

   511     void ConstructL();

   512     void RunL();

   513     void DoCancel();

   514     TInt RunError(TInt aError);

   515 

   516 private:

   517     MSifOperationsHandler& iHandler;

   518     TInt iBufferSize;   

   519     RArray<TUint> iKeyArray;

   520     RProperty iProperty;

   521     RPointerArray<CSifNotifierBase> iNotifierArray;

   522     TNotifierState iNotifierState;

   523     };

   524 

   525 

   526 } // namespace

   527 

   528 #endif