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 #include <e32property.h>

    30 

    31 #include "hspsresource.h"

    32 

    33 class CRepository;

    34 #ifdef HSPS_LOG_ACTIVE

    35 class ChspsLogBus;

    36 #endif

    37 

    38 

    39 /** 

    40 * Publish & Subscribe functionality for controlling the ODT copies.

    41 *

    42 * IPC clients, such as such as sapi_homescreenplugin, should update any ChspsODT based 

    43 * runtime copies when the active application configuration is updated. 

    44 * Updated versions are indicated by an increment in the associated RProperty key.

    45 **/

    46 const TUid KPropertyHspsCat = {0x200159C0};

    47 const TUint KPropertyAI3Key = {0x102750F0}; // Homescreen

    48 const TUint KPropertyMTKey = {0x20000FB1}; // EUNIT MT

    49 const TInt KPropertyKeyDefault = 1;

    50 

    51 

    52 /**

    53 *   ThspsRepositoryEvent.

    54 *   Events used in ThspsRepositoryInfo.

    55 **/

    56 

    57 enum ThspsRepositoryEvent

    58     {

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

    60     EhspsODTAdded = 0x01, //new configuration installed

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

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

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

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

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

    66     EhspsSettingsChanged = 0x40, // settings changed

    67     EhspsPluginsMoved = 0x80, //plugins moved

    68     EhspsPluginActivated = 0x100,

    69     EhspsPluginReplaced = 0x200,

    70     EhspsNoEvent = 0x800

    71     };

    72     

    73 /**

    74 *   ThspsRepositoryInfo.

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

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

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

    78 *   events via callback function HandleDefinitionRespositoryEvent().

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

    80 */

    81 class ThspsRepositoryInfo

    82     {

    83     public:

    84         ThspsRepositoryInfo( 

    85 	    		ThspsRepositoryEvent aEventType, 

    86 				TUint aAppUid = 0, 

    87 				TUint aAppConfUid = 0, 

    88 				TUint aSecureId = 0,

    89 				TUint aAppConfProviderUid = 0,

    90 				TUint aPluginIfUid = 0,

    91 				TUint aPluginProviderUid = 0,

    92 				TUint aPluginUid = 0,

    93 				TUint aPluginId = 0,

    94 				TBool aLastNotification = ETrue,

    95 				TPtrC aName = KNullDesC(),

    96 				TLanguage aLanguage = ELangTest )

    97         	{

    98             iEventTime.HomeTime();

    99             iEventType = aEventType;

   100             iAppUid = aAppUid;

   101             iAppConfUid = aAppConfUid;

   102             iSecureId = aSecureId;

   103             iAppConfProviderUid = aAppConfProviderUid;

   104             iPluginIfUid = aPluginIfUid;

   105             iPluginProviderUid = aPluginProviderUid;

   106             iPluginUid = aPluginUid;

   107             iPluginId = aPluginId;

   108             iLastNotification = aLastNotification;

   109             iName = aName;

   110             iLanguage = aLanguage;

   111             }

   112     public:  

   113         TTime iEventTime;

   114         ThspsRepositoryEvent iEventType;

   115         TUint iAppUid;

   116         TUint iAppConfUid;

   117         TUint iSecureId;

   118         TUint iAppConfProviderUid;

   119         TUint iPluginIfUid; 

   120         TUint iPluginProviderUid;

   121         TUint iPluginUid;

   122         TUint iPluginId;

   123         TBool iLastNotification;

   124         TBuf<KMaxFileName> iName;

   125         TLanguage iLanguage;

   126     };

   127 

   128 /** 

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

   130 * observers. 

   131 */

   132 class MhspsDefinitionRepositoryObserver

   133     {

   134     /** 

   135     * Definition repository callback 

   136     * 

   137     * @since S60 5.0

   138     * @param aRepositoryInfo Repository callback info.

   139     */    

   140     public:

   141         virtual TBool HandleDefinitionRespositoryEvent( ThspsRepositoryInfo aRepositoryInfo ) = 0;

   142     };

   143 

   144 // FORWARD DECLARATIONS

   145 class ChspsODT;

   146 class RWriteStream;

   147 class RReadStream;

   148 class CFileStore;

   149 class ChspsDomDocument;

   150 

   151 _LIT(KROMDrive,"z:");

   152 _LIT(KCDrive,"c:");

   153 

   154 /**

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

   156  *  definition files.

   157  *  

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

   159  *  locale, style, structure and resource files. 

   160  *

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

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

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

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

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

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

   167  *  stream.

   168  *  

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

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

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

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

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

   174  *

   175  *

   176  *  @lib hspsDefRep.dll

   177  *  @since S60 5.0

   178  *  @ingroup group_hspspluginregistry

   179  */

   180 class ChspsDefinitionRepository : public CBase

   181     {

   182     public:  // Constructors and destructor

   183         

   184         /**

   185         * Two-phased constructor.

   186         * 

   187         * @since S60 5.0

   188         */

   189         IMPORT_C static ChspsDefinitionRepository* NewL(

   190                 CRepository& aCentralRepository );

   191         

   192         /**

   193         * Destructor.

   194         */

   195         virtual ~ChspsDefinitionRepository();

   196 

   197     public: // New functions

   198         

   199         /**

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

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

   202         * Updates resource object with the new location.

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

   204         * 

   205         * @since S60 5.0        

   206         * @param aODT Contains the header information.

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

   208         */

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

   210                                 

   211         /**

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

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

   214         * 

   215         * @since S60 5.0

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

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

   218         */       

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

   220         

   221         /**

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

   223         * defined from the ODT's header information.

   224         * 

   225         * @since S60 5.0

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

   227         */

   228         IMPORT_C TInt SetOdtL( const ChspsODT &aODT );

   229         

   230         /**

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

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

   233         * 

   234         * @since S60 5.0

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

   236         */

   237         IMPORT_C TInt GetOdtL( ChspsODT& aODT );

   238         

   239         /**

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

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

   242         * 

   243         * @since S60 5.0

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

   245         * @param aLang Informs the correct language version.

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

   247         */

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

   249         

   250        

   251         /**

   252         * Retrieves the exact path of the repository object.

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

   254         * 

   255         * @since S60 5.0

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

   257         * @param aResourceType resource type to search for.

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

   259         */       

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

   261         

   262         

   263         /**

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

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

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

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

   268         * 

   269         * @since S60 5.0

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

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

   272         */

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

   274         

   275         /**

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

   277         * works as a search mask.

   278         * 

   279         * @since S60 5.0

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

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

   282         */

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

   284         

   285         /**

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

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

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

   289         * themes can be removed at once.

   290         * 

   291         * @since S60 5.0

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

   293         */

   294         IMPORT_C void RemoveThemeL( const ChspsODT& aODT );

   295         

   296         /**

   297         * Get a path for resource to be stored.

   298         * 

   299         * @since S60 5.0

   300         * @param aODT Contains the header information.

   301         * @param aResource resource where path is stored.

   302         * Leaves if path could not be defined.

   303         */

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

   305         

   306         /**

   307         * Saves the resource into the repository.

   308         * 

   309         * @since S60 5.0

   310         * @param aODT Contains the header information.

   311         * @param aFbsBitmap bitmap to store to repository.

   312         * @param aResource resource where path is stored.

   313         * Leaves if original file does not exist.

   314         */

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

   316         

   317         /**

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

   319         * own entry in the array.

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

   321         * corrupted repository.

   322         * 

   323         * @since S60 5.0

   324         * @param aODT Contains the header information.

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

   326         */  

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

   328       

   329 

   330         /**

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

   332         * own entry in the array.

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

   334         * corrupted repository.

   335         * 

   336         * @since S60 5.0

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

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

   339         * @return a resource list.

   340         */

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

   342                

   343         /**

   344         * GetRepositoryInfo

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

   346         * to notify its observers about the notification.

   347         * 

   348         * @since S60 5.0

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

   350         */

   351         IMPORT_C void RegisterNotification( ThspsRepositoryInfo aRepositoryInfo );

   352         

   353         /**

   354         * RegisterObserverL (  )

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

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

   357         *    

   358         * @since S60 5.0

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

   360         */

   361         IMPORT_C void RegisterObserverL( const MhspsDefinitionRepositoryObserver& aObserver );

   362         

   363         /**

   364         * UnregisterObserver

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

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

   367         *    

   368         * @since S60 5.0

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

   370         */

   371         IMPORT_C void UnregisterObserver( const MhspsDefinitionRepositoryObserver& aObserver );

   372 

   373         /**

   374         * Increases the semaphore controlling repository locking.

   375         * Locking semaphore is increased explicitly by clients that

   376         * going to write data to repository..

   377         * Lockin semaphore revents reading repository as long as there

   378         * are writers. 

   379         * 

   380         * @since S60 5.0

   381         */

   382         IMPORT_C void Lock();

   383         

   384         /**

   385         * Decreases the semaphore controlling repository locking. 

   386         * Semaphore minimun value is 0 meaning unlocked situation.

   387         * 

   388         * @since S60 5.0

   389         */

   390         IMPORT_C void Unlock();

   391         

   392         /**

   393         * Returns repository locking status

   394         * 

   395         * @since S60 5.0

   396         * @returns ETrue if repository is locked otherwise EFalse

   397         */

   398         IMPORT_C TBool Locked() const;

   399                     

   400         /**

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

   402         * 

   403         * @since S60 5.0

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

   405         * @param aPath Relative path without a drive letter         

   406         */

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

   408         

   409         /** 

   410         * Set log bus.

   411         * Empty implementation if non HSPS_LOG_ACTIVE build.

   412         *  

   413         * @since S60 5.0

   414         * @param aLogBus Log bus to be set.

   415         */

   416         IMPORT_C void SetLogBus( void* aLogBus );        

   417 

   418         /** 

   419         * Restores a defined configuration from backup folder 

   420         * @since S60 5.0

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

   422         * @return Operation status 

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

   424         *         KErrNotFound if backup configuration is not found

   425         */

   426         IMPORT_C TInt RestoreBackupConfiguration( const ChspsODT& aODT );        

   427 

   428         /** 

   429         * Copies a defined configuration to theme backup folder 

   430         * @since S60 5.0

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

   432         */

   433         IMPORT_C void BackupConfigurationL( const ChspsODT& aODT );        

   434 

   435         /** 

   436         * Clears previous backup data

   437         * @since S60 5.0

   438         */

   439         IMPORT_C void ClearBackupsL();        

   440 

   441         /**

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

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

   444         * @since S60 5.0

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

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

   447         */

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

   449 

   450      private:

   451 

   452         /**

   453         * C++ default constructor.

   454         */

   455         ChspsDefinitionRepository( CRepository& aCentralRepository );

   456 

   457         /**

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

   459         */

   460         void ConstructL();

   461         

   462         void SetupPropertiesL( const TUint aKey );

   463         

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

   465 

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

   467                 

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

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

   470         void FileExtensionL( ThspsResourceType aResourceType, TInt aLanguage );

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

   472         

   473         TInt WriteToFileL( const ChspsODT& aODT );        

   474                 

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

   476                 

   477         HBufC8* StreamHeaderFromFileL( const TDesC& aPath );

   478         CFileStore* OpenFileStoreLC( const TDesC& aPath );

   479         

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

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

   482         

   483         TInt CopyFileL( const TDesC& aSourceFile );

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

   485         void RemoveDirectoryL();

   486         void RemoveDirectoryL( TDesC& aDirPath );

   487 

   488     private:    // Data

   489     

   490         RArray<ThspsRepositoryInfo> iRepositoryInfoQueue;

   491         

   492         // Array of observers

   493         RPointerArray<MhspsDefinitionRepositoryObserver> iObservers;     

   494         

   495         //Handle to a file server session

   496         RFs iFs;

   497         

   498         //Holds the path information, owned

   499         HBufC* iPath;

   500          

   501         TBool iLicenseDefault;

   502         TInt iLockSemaphore;

   503                 

   504         // Contains a temporary filepath

   505         TFileName iTempFileName1;

   506         

   507         // Contains a temporary filepath

   508         TFileName iTempFileName2;

   509 

   510 #ifdef HSPS_LOG_ACTIVE        

   511         // Log bus. Not owned.

   512         ChspsLogBus* iLogBus;

   513 #endif

   514        

   515         // Cached copy of last retrieved ODT.

   516         ChspsODT* iCacheLastODT;        

   517         

   518         // For indicating ODT updates

   519         RProperty iProperty;

   520         

   521         // Reference to central repository

   522         CRepository& iCentralRepository;

   523     };

   524 

   525 #endif      // C_hspsDEFINITIONREPOSITORY_H   

   526             

   527 // End of File