1 /*

     2 * Copyright (c) 2008 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 "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:  Service for storing configurations into the file system

    15 

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef C_hspsDEFINITIONREPOSITORY_H

    22 #define C_hspsDEFINITIONREPOSITORY_H

    23 

    24 //  INCLUDES

    25 #include <f32file.h>

    26 #include <badesca.h>

    27 #include <s32mem.h>

    28 #include <fbs.h>

    29 

    30 #include "hspsresource.h"

    31 

    32 #ifdef HSPS_LOG_ACTIVE

    33 class ChspsLogBus;

    34 #endif

    35 

    36 /**

    37 *   ThspsRepositoryEvent.

    38 *   Events used in ThspsRepositoryInfo.

    39 **/

    40 

    41 enum ThspsRepositoryEvent

    42     {

    43     EhspsODTActivated = 0x00, // active application configuration changed 

    44     EhspsODTAdded = 0x01, //new configuration installed

    45     EhspsODTUpdated = 0x02, //installing new version of plugin

    46     EhspsODTRemoved = 0x04, // plugin removed from configuration

    47     EhspsODTModified = 0x08,  // plugin added to configuration 

    48     EhspsCacheUpdate = 0x10, // forces full cache update

    49     EhspsClean = 0x20,  // destructors&unstalling plugin 

    50     EhspsSettingsChanged = 0x40, // settings changed

    51     EhspsPluginsMoved = 0x80, //plugins moved

    52     EhspsPluginActivated = 0x100,

    53     EhspsPluginReplaced = 0x200,

    54     EhspsNoEvent = 0x800

    55     };

    56     

    57 /**

    58 *   ThspsRepositoryInfo.

    59 *   The Definitionrepository can inform client observers of changes to repository:

    60 *   theme has been updated, theme added etc. A client needs to register to repository

    61 *   (RegisterObserverL) to receive repository events. The client will receive the 

    62 *   events via callback function HandleDefinitionRespositoryEvent().

    63 *   If observer handles the event, it must return ETrue, else, it must return EFalse.

    64 */

    65 class ThspsRepositoryInfo

    66     {

    67     public:

    68         ThspsRepositoryInfo( 

    69 	    		ThspsRepositoryEvent aEventType, 

    70 				TUint aAppUid = 0, 

    71 				TUint aAppConfUid = 0, 

    72 				TUint aSecureId = 0,

    73 				TUint aAppConfProviderUid = 0,

    74 				TUint aPluginIfUid = 0,

    75 				TUint aPluginProviderUid = 0,

    76 				TUint aPluginUid = 0,

    77 				TUint aPluginId = 0,

    78 				TBool aLastNotification = ETrue,

    79 				TPtrC aName = KNullDesC(),

    80 				TLanguage aLanguage = ELangTest )

    81         	{

    82             iEventTime.HomeTime();

    83             iEventType = aEventType;

    84             iAppUid = aAppUid;

    85             iAppConfUid = aAppConfUid;

    86             iSecureId = aSecureId;

    87             iAppConfProviderUid = aAppConfProviderUid;

    88             iPluginIfUid = aPluginIfUid;

    89             iPluginProviderUid = aPluginProviderUid;

    90             iPluginUid = aPluginUid;

    91             iPluginId = aPluginId;

    92             iLastNotification = aLastNotification;

    93             iName = aName;

    94             iLanguage = aLanguage;

    95             }

    96     public:  

    97         TTime iEventTime;

    98         ThspsRepositoryEvent iEventType;

    99         TUint iAppUid;

   100         TUint iAppConfUid;

   101         TUint iSecureId;

   102         TUint iAppConfProviderUid;

   103         TUint iPluginIfUid; 

   104         TUint iPluginProviderUid;

   105         TUint iPluginUid;

   106         TUint iPluginId;

   107         TBool iLastNotification;

   108         TBuf<KMaxFileName> iName;

   109         TLanguage iLanguage;

   110     };

   111 

   112 /** 

   113 * MhspsDefinitionRepositoryObserver is an interface definition to be implemented by the repository events 

   114 * observers. 

   115 */

   116 class MhspsDefinitionRepositoryObserver

   117     {

   118     /** 

   119     * Definition repository callback 

   120     * 

   121     * @since S60 5.0

   122     * @param aRepositoryInfo Repository callback info.

   123     */    

   124     public:

   125         virtual TBool HandleDefinitionRespositoryEvent( ThspsRepositoryInfo aRepositoryInfo ) = 0;

   126     };

   127 

   128 // FORWARD DECLARATIONS

   129 class ChspsODT;

   130 class RWriteStream;

   131 class RReadStream;

   132 class CFileStore;

   133 class ChspsDomDocument;

   134 

   135 _LIT(KROMDrive,"z:");

   136 _LIT(KCDrive,"c:");

   137 

   138 /**

   139  *  hspsDefinitionRepository is a common and secure place to store the HSPS's

   140  *  definition files.

   141  *  

   142  *  Class provides the APIs to store and retrieve all the definition files: 

   143  *  locale, style, structure and resource files. 

   144  *

   145  *  Repository can store disk space limited number of ODT data structures and

   146  *  definition files (themes) for every application. Themes are identified by

   147  *  application uid, vendor name, theme name and theme version. Localisation is

   148  *  supported by naming the ODT for each language variant uniquely. TLanguage

   149  *  enumeration is used in the ODT header to specify the variant. The ODT can be

   150  *  retrieved from the repository as a fully constructed object or a descriptor

   151  *  stream.

   152  *  

   153  *  Existing themes can be queried from the repository for managing purposes. 

   154  *  Same method can be used to avoid accidental overwrites. If the query returns

   155  *  zero count for the appropriate ODT the new theme can be safely installed.

   156  *  Themes can be also removed with the valid header information. When the theme

   157  *  is removed also all the definition files will be deleted.

   158  *

   159  *

   160  *  @lib hspsDefRep.dll

   161  *  @since S60 5.0

   162  *  @ingroup group_hspspluginregistry

   163  */

   164 class ChspsDefinitionRepository : public CBase

   165     {

   166     public:  // Constructors and destructor

   167         

   168         /**

   169         * Two-phased constructor.

   170         * 

   171         * @since S60 5.0

   172         */

   173         IMPORT_C static ChspsDefinitionRepository* NewL();

   174         

   175         /**

   176         * Destructor.

   177         */

   178         virtual ~ChspsDefinitionRepository();

   179 

   180     public: // New functions

   181         

   182         /**

   183         * Saves the localisation file into repository. ODT must contain the valid 

   184         * header information, which is used to define the location for the file.

   185         * Updates resource object with the new location.

   186         * Leaves if original file does not exist or information is not valid.

   187         * 

   188         * @since S60 5.0        

   189         * @param aODT Contains the header information.

   190         * @param aResource The resource file to be saved.       

   191         */

   192         IMPORT_C TInt SetLocaleL( ChspsODT& aODT, ChspsResource& aResource );

   193                                 

   194         /**

   195         * Creates a path for the ODT to be stored on repository.

   196         * ODT-header information works as a set mask.

   197         * 

   198         * @since S60 5.0

   199         * @param aODT Contains the header information. Works as a set mask. Leaves if invalid data.

   200         * @param aResource A ChspsResource-object filled with the new path is returned to caller.

   201         */       

   202         IMPORT_C void MakeODTPathL( ChspsODT& aODT, ChspsResource& aResource );

   203         

   204         /**

   205         * Saves the ODT data structure into the repository. The location of the data is

   206         * defined from the ODT's header information.

   207         * 

   208         * @since S60 5.0

   209         * @param aODT The actual data to be stored.

   210         */

   211         IMPORT_C TInt SetOdtL( const ChspsODT &aODT );

   212         

   213         /**

   214         * Retrieves the ODT from the repository. The ODT must contain the valid header 

   215         * information, which is used to locate the correct data. Leaves if ODT not found.

   216         * 

   217         * @since S60 5.0

   218         * @param aODT A reference to ODT object, which is filled with data from the repository.

   219         */

   220         IMPORT_C TInt GetOdtL( ChspsODT& aODT );

   221         

   222         /**

   223         * Retrieves the ODT header from the repository. The aPath variable must contain

   224         * the valid path. Leaves if path not found.

   225         * 

   226         * @since S60 5.0

   227         * @param aPath The path where the theme is located.

   228         * @param aLang Informs the correct language version.

   229         * @param aODT A reference to ODT header object, which is filled with data from the repository.

   230         */

   231         IMPORT_C TInt GetOdtHeaderL( TDes& aPath, TLanguage aLang, ChspsODT& aODT );

   232         

   233        

   234         /**

   235         * Retrieves the exact path of the repository object.

   236         * Does not check whether the object is really existing on repository or not.

   237         * 

   238         * @since S60 5.0

   239         * @param aODT Contains the header information. Works as a search mask. Leaves if invalid data.

   240         * @param aResourceType resource type to search for.

   241         * @param aFilePath A file path returned to caller.

   242         */       

   243         IMPORT_C void GetResourcePathL( const ChspsODT& aODT, ThspsResourceType aResourceType, TDes& aFilePath );

   244         

   245         

   246         /**

   247         * Retrieves the list of installed themes in an array. ODT header information works

   248         * as a search mask. If all the information is available in the header a function

   249         * can be used to query the theme's existence. This is useful when the accidental

   250         * overwrites needs to be avoided e.g. when installing a new theme.

   251         * 

   252         * @since S60 5.0

   253         * @param aThemeList A reference to an array, which is filled with the theme paths.

   254         * @param aODT Contains the header information. Works as a search mask. Leaves if invalid data.

   255         */

   256         IMPORT_C void GetThemePathListL( CDesCArraySeg& aThemeList, const ChspsODT& aODT );

   257         

   258         /**

   259         * Retrieves the list of installed themes as a streams in an array. ODT header information

   260         * works as a search mask.

   261         * 

   262         * @since S60 5.0

   263         * @param aThemeList A reference to an array, which contains internalized theme headers.

   264         * @param aODT Contains the header information. Works as a search mask. Leaves if invalid data.

   265         */

   266         IMPORT_C void GetThemeListAsStreamL( CArrayPtrSeg<HBufC8>& aThemeList, const ChspsODT& aODT );

   267         

   268         /**

   269         * Removes the theme specific ODT and definition files from the repository.

   270         * ODT header information works as a mask, which defines the level of removal. 

   271         * A single theme, all themes from a provider or all application specific

   272         * themes can be removed at once.

   273         * 

   274         * @since S60 5.0

   275         * @param aODT Contains the header information. Leaves if information is not valid.

   276         */

   277         IMPORT_C void RemoveThemeL( const ChspsODT& aODT );

   278         

   279         /**

   280         * Get a path for resource to be stored.

   281         * 

   282         * @since S60 5.0

   283         * @param aODT Contains the header information.

   284         * @param aResource resource where path is stored.

   285         * Leaves if path could not be defined.

   286         */

   287         IMPORT_C void MakeResourcePathL( const ChspsODT& aODT, ChspsResource& aResource );

   288         

   289         /**

   290         * Saves the resource into the repository.

   291         * 

   292         * @since S60 5.0

   293         * @param aODT Contains the header information.

   294         * @param aFbsBitmap bitmap to store to repository.

   295         * @param aResource resource where path is stored.

   296         * Leaves if original file does not exist.

   297         */

   298         IMPORT_C TInt SetResourceL( const ChspsODT& aODT, const CFbsBitmap& aFbsBitmap, ChspsResource& aResource );

   299         

   300         /**

   301         * Stores the resource list to the repository. Every registered resource has an

   302         * own entry in the array.

   303         * Leaves if the repository is corrupted. Use RemoveThemeL to remove the

   304         * corrupted repository.

   305         * 

   306         * @since S60 5.0

   307         * @param aODT Contains the header information.

   308         * @param aResourceList resource list to store to repository.

   309         */  

   310         IMPORT_C TInt SetResourceListL( ChspsODT& aODT, const CArrayPtrSeg<ChspsResource>& aResourceList );

   311       

   312 

   313         /**

   314         * Retrieves the resource list in an array. Every registered resource has an

   315         * own entry in the array.

   316         * Leaves if the repository is corrupted. Use RemoveThemeL to remove the

   317         * corrupted repository.

   318         * 

   319         * @since S60 5.0

   320         * @param aODT contains the theme header associated to this resourcelist.

   321         * @param aResourceList destination resource list where resource are read from repository.

   322         * @return a resource list.

   323         */

   324         IMPORT_C TInt GetResourceListL( const ChspsODT& aODT, CArrayPtrSeg<ChspsResource>& aResourceList );

   325                

   326         /**

   327         * GetRepositoryInfo

   328         * Register a ThspsRepositoryInfo-object to the repository. Repository's responsibility is

   329         * to notify its observers about the notification.

   330         * 

   331         * @since S60 5.0

   332         * @param aRepositoryInfo is aThspsRepositorynfo-object to be registered.

   333         */

   334         IMPORT_C void RegisterNotification( ThspsRepositoryInfo aRepositoryInfo );

   335         

   336         /**

   337         * RegisterObserverL (  )

   338         * Returns a refrence to a RArray-object containing changes in repository system.

   339         * It is a responsibilty of the caller to lock the repository for modifications.

   340         *    

   341         * @since S60 5.0

   342         * @param aObserver is a MhspsDefinitionRepositoryObserver-object to be registered.

   343         */

   344         IMPORT_C void RegisterObserverL( const MhspsDefinitionRepositoryObserver& aObserver );

   345         

   346         /**

   347         * UnregisterObserver

   348         * Returns a refrence to a RArray-object containing changes in repository system.

   349         * It is a responsibilty of the caller to lock the repository for modifications.

   350         *    

   351         * @since S60 5.0

   352         * @param aObserver is a MhspsDefinitionRepositoryObserver-object to be unregistered.

   353         */

   354         IMPORT_C void UnregisterObserver( const MhspsDefinitionRepositoryObserver& aObserver );

   355 

   356         /**

   357         * Increases the semaphore controlling repository locking.

   358         * Locking semaphore is increased explicitly by clients that

   359         * going to write data to repository..

   360         * Lockin semaphore revents reading repository as long as there

   361         * are writers. 

   362         * 

   363         * @since S60 5.0

   364         */

   365         IMPORT_C void Lock();

   366         

   367         /**

   368         * Decreases the semaphore controlling repository locking. 

   369         * Semaphore minimun value is 0 meaning unlocked situation.

   370         * 

   371         * @since S60 5.0

   372         */

   373         IMPORT_C void Unlock();

   374         

   375         /**

   376         * Returns repository locking status

   377         * 

   378         * @since S60 5.0

   379         * @returns ETrue if repository is locked otherwise EFalse

   380         */

   381         IMPORT_C TBool Locked() const;

   382                     

   383         /**

   384         * Creates a path from the header information. Results are stored into the iPath member.

   385         * 

   386         * @since S60 5.0

   387         * @param aODT An ODT whose path is being requested

   388         * @param aPath Relative path without a drive letter         

   389         */

   390         IMPORT_C void GetODTPathL( const ChspsODT& aODT, TDes& aPath );

   391         

   392         /** 

   393         * Set log bus.

   394         * Empty implementation if non HSPS_LOG_ACTIVE build.

   395         *  

   396         * @since S60 5.0

   397         * @param aLogBus Log bus to be set.

   398         */

   399         IMPORT_C void SetLogBus( void* aLogBus );        

   400 

   401         /** 

   402         * Restores a defined configuration from backup folder 

   403         * @since S60 5.0

   404         * @param aODT ODT header defining the configuration to be restored

   405         * @return Operation status 

   406         *         KErrNone if backup configuration is found and it is restored

   407         *         KErrNotFound if backup configuration is not found

   408         */

   409         IMPORT_C TInt RestoreBackupConfiguration( const ChspsODT& aODT );        

   410 

   411         /** 

   412         * Copies a defined configuration to theme backup folder 

   413         * @since S60 5.0

   414         * @param aODT ODT header defining the configuration to be copied

   415         */

   416         IMPORT_C void BackupConfigurationL( const ChspsODT& aODT );        

   417 

   418         /** 

   419         * Clears previous backup data

   420         * @since S60 5.0

   421         */

   422         IMPORT_C void ClearBackupsL();        

   423 

   424         /**

   425         * Retrieves the ODT from the repository. The aPath variable must contain

   426         * the valid path. Leaves if path not found.

   427         * @since S60 5.0

   428         * @param aPath The path where the theme is located.

   429         * @param aODT A reference to ODT object, which is filled with data from the repository.

   430         */

   431         IMPORT_C void GetOdtL( const TDes& aPath, ChspsODT& aODT );

   432 

   433      private:

   434 

   435         /**

   436         * C++ default constructor.

   437         */

   438         ChspsDefinitionRepository();

   439 

   440         /**

   441         * By default Symbian 2nd phase constructor is private.

   442         */

   443         void ConstructL();

   444         

   445         void SelectFilesFromPathL( CDesCArraySeg& aFileList, const TDesC& aPath, TEntryKey aSortFlag, const TDesC& aFileExtension );

   446 

   447         void GetPathL( const ChspsODT& aODT, ThspsResourceType aResourceType );

   448                 

   449         void AppendDesCIntoPathL( TDes& aPath, const TDesC& aText );

   450         void AppendNumIntoPathL( TDes& aPath, const TUint aNum );

   451         void FileExtensionL( ThspsResourceType aResourceType, TInt aLanguage );

   452         void AddLocalePathL( TDes& aPath, TInt aLanguage );

   453         

   454         TInt WriteToFileL( const ChspsODT& aODT );        

   455                 

   456         TInt ReadFromFileL( const TDesC& aPath, ChspsODT& aODT );

   457                 

   458         HBufC8* StreamHeaderFromFileL( const TDesC& aPath );

   459         CFileStore* OpenFileStoreLC( const TDesC& aPath );

   460         

   461         void MatchingFoldersFromAllDrivesL(const TDesC& aWildName, const TDesC& aScanDir, CDesCArraySeg& aThemeList );

   462         TInt MatchingFoldersL(const TDesC& aWildName, const TDesC& aScanDir, CDesCArraySeg& aThemeList );

   463         

   464         TInt CopyFileL( const TDesC& aSourceFile );

   465         TInt CopyFileL( const TDesC& aSourceFile, const TDesC& aDestinationFile );

   466         void RemoveDirectoryL();

   467         void RemoveDirectoryL( TDesC& aDirPath );

   468 

   469     private:    // Data

   470     

   471         RArray<ThspsRepositoryInfo> iRepositoryInfoQueue;

   472         

   473         // Array of observers

   474         RPointerArray<MhspsDefinitionRepositoryObserver> iObservers;     

   475         

   476         //Handle to a file server session

   477         RFs iFs;

   478         

   479         //Holds the path information, owned

   480         HBufC* iPath;

   481          

   482         TBool iLicenseDefault;

   483         TInt iLockSemaphore;

   484                 

   485         // Contains a temporary filepath

   486         TFileName iTempFileName1;

   487         

   488         // Contains a temporary filepath

   489         TFileName iTempFileName2;

   490 

   491 #ifdef HSPS_LOG_ACTIVE        

   492         // Log bus. Not owned.

   493         ChspsLogBus* iLogBus;

   494 #endif        

   495     };

   496 

   497 #endif      // C_hspsDEFINITIONREPOSITORY_H   

   498             

   499 // End of File