diff -r 000000000000 -r ba25891c3a9e installationservices/swi/inc/swi/sisregistryentry.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/installationservices/swi/inc/swi/sisregistryentry.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,486 @@ +/* +* Copyright (c) 2004-2009 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: +* SisRegistry - client registry entry(package) interface +* Clients use the defined interface to access and querry information +* specific to a single installed package. +* The access to specific functionality depends on the client capabilities +* and may be restricted. +* +*/ + + +/** + @file + @released + @publishedPartner +*/ + +#ifndef __SISREGISTRYENTRY_H__ +#define __SISREGISTRYENTRY_H__ + +#include +#include + +class CX509Certificate; + +namespace Swi +{ +class RSisRegistrySession; +class CSisRegistryPackage; +class CSisRegistryDependency; +class CHashContainer; +class TSisTrustStatus; + +/** + * Client registry entry interface + * + * @publishedPartner + * @released + */ +class RSisRegistryEntry : public RSubSessionBase + { +public: + + /** + * Opens the base package entry by specifying a UID. + * + * - A base package is a self-sufficient package which does + * not depend on other packages with the same UID. It is also completely removed + * together with all related augmentation packages. + * + * - An agmentation package shares a UID with a base package and 'augments' the base package. + * It can only be installed only when the related base package is installed + * It can be uninstalled separatelly (without removing base package) + * + * + * @param aSession The open RSisRegistrySession to use + * @param aUid The UID identifying the entry + * @return KErrNone if successful, otherwise an error code + */ + IMPORT_C TInt Open(RSisRegistrySession &aSession, TUid aUid); + + /** + * Open a registry entry (includes augmentations) by specifying a package + * + * @param aSession The open RSisRegistrySession to use + * @param aPackage The package to open + * + * @return KErrNone if successful, or an error code + */ + IMPORT_C TInt OpenL(RSisRegistrySession &aSession, const CSisRegistryPackage& aPackage); + + /** + * Open a registry entry (includes augmentations) by specifying a package + * and vendor name. + * + * @param aSession The open RSisRegistrySession to use + * @param aPackageName The name of the package + * @param aVendorName The name of the vendor + * @return KErrNone if successful, otherwise an error code + */ + IMPORT_C TInt Open(RSisRegistrySession &aSession, const TDesC& aPackageName, const TDesC& aVendorName); + + /** + * Closes the registry entry by closing the sub-session + */ + IMPORT_C void Close(); + + /** + * Indicates whether the package is currently on the device (i.e. not on + * removable media that is not inserted). + * + * @return ETrue if the package is on the device; + * EFalse otherwise + */ + IMPORT_C TBool IsPresentL(); + + /** + * Indicates whether the package is signed + * + * @return ETrue the package is signed; + * EFalse otherwise + */ + IMPORT_C TBool IsSignedL(); + + /** + * Indicates the level of trust associated with the package + * + * @return The level of trust + * @deprecated Will be replaced in the future by a more complete TrustStatusL method. + */ + IMPORT_C TSisPackageTrust TrustL() const; + + /** + * The time at which the trust level was established + * + * @return The time at which the trust level was established + * @deprecated Will be replaced in the future by a more complete TrustStatusL method. + */ + IMPORT_C TTime TrustTimeStampL() const; + + + /** + * The trust status object for the entry. This supercedes information + * provided by the deprecated TrustL and TrustTimeStampL methods. + * + * @return The trust status information associated with + * this entry. + */ + IMPORT_C TSisTrustStatus TrustStatusL(); + + /** + * Indicates whether or not the package is installed on read-only media + * + * + * @return ETrue if any drive used by this package is read-only; + * EFalse otherwise + */ +#ifdef SYMBIAN_UNIVERSAL_INSTALL_FRAMEWORK + /** + * N.B. Using Usif::RSoftwareComponentRegistry::IsComponentOnReadOnlyDriveL + * will return different result when we have an empty ROM stub or when all + * the files of a ROM based package are eclipsed, since SCR only considers + * the current list of files registered with it. + */ +#endif + IMPORT_C TBool IsInRomL(); + + + + /** + * Indicates whether or not the package augments another package + * + * @return ETrue if the package is an augmentation; + * EFalse otherwise + */ + IMPORT_C TBool IsAugmentationL(); + + /** + * Gets the version of this package + * + * @return The version + */ + IMPORT_C TVersion VersionL(); + + /** + * Gets the installed language for this package + * + * @return The language + */ + IMPORT_C TLanguage LanguageL(); + + /** + * Gets the UID of this package + * + * @return The UID + */ + IMPORT_C TUid UidL(); + + /** + * Gets the name of a package + * + * @return The name of the package + */ + IMPORT_C HBufC* PackageNameL(); + + /** + * Gets the unique vendor name of this package + * + * @return The unique vendor name + */ + IMPORT_C HBufC* UniqueVendorNameL(); + + /** + * Gets the localised vendor name of a package + * + * @return The localised name of the vendor + */ + IMPORT_C HBufC* LocalizedVendorNameL(); + + /** + * Returns an array of Sids (executables). The array is supplied by the + * client which is then populated. + * + * @param aSids On return, the array object to be populated. + */ + IMPORT_C void SidsL(RArray& aSids); + + /** + * Provides a list of files installed by this package. This function may also return + * a file specification that contains wildcard characters ('?' and/or '*') if the + * package is a rom 'stub' sis file. Wildcard file specifications are NOT expanded and + * in this instance, the Count() member function on 'aFiles' cannot be used as an + * indicator of the number of files within the package. + * + * @param aFiles The array of files to be populated. + */ + IMPORT_C void FilesL(RPointerArray& aFiles); + + /** + * Returns the size of the installation excluding the size of + * other embedded packages + * + * @return A TInt64 value of the total installation size + */ + IMPORT_C TInt64 SizeL(); + + /** + * Provides the certificate chains associated with this package + * + * @param aCertificateChains The array of certificate chains + */ + IMPORT_C void CertificateChainsL(RPointerArray& aCertificateChains); + + /** + * Gets the value of a property within a package + * + * @param aKey The key to search for + * @return The value of this key if found; + KErrNotFound otherwise. + */ + IMPORT_C TInt PropertyL(TInt aKey); + + /** + * Returns all augmentations to this package. If no augmentations exist, + * the lists are empty + * + * @param aPackageNames On return, a list of PackageNames + * @param aVendorNames On return, the corresponding list of VendorNames + * + */ + IMPORT_C void AugmentationsL(RPointerArray& aPackageNames, RPointerArray& aVendorNames); + + /** + * Returns all augmentations to this package. If no augmentations exist, + * the list is empty + * + * @param aPackages The array of CSisRegistryPackages to be populated + */ + IMPORT_C void AugmentationsL(RPointerArray& aPackages); + + /** + * Gets the number of augmentations to this package. + * @return the number of augmentations to this package + */ + IMPORT_C TInt AugmentationsNumberL(); + + /** + * Returns the hash value of a selected file, identified by its name + * + * @param aFileName the full file path + * @return A new CHashContainer object + */ + IMPORT_C CHashContainer* HashL(const TDesC& aFileName); + + /** + * Returns the package of a current entry + * + * @return A new CSisRegistryPackage object + */ + IMPORT_C CSisRegistryPackage* PackageL(); + + /** + * Return the controllers associated with this package as raw binary data + * + * @param aControllers The array of controllers to be populated. + * + */ + IMPORT_C void ControllersL(RPointerArray& aControllers); + + /** + Returns what drive the user selected for files in the Sis file that + did not specify drive.It returns KNoDriveSelected if user is not prompted for drive selection. + For ROM stub packages it returns zero instead of KNoDriveSelected + To determine the set of drives that files were installed to for this registry entry @see RSisRegistryEntry::InstalledDrivesL(). + @return TChar The drive selected + @see KNoDriveSelected + */ + IMPORT_C TChar SelectedDriveL(); + + /** + Determines whether the base package or any of the partial upgrades + require all applications within this package to be to be shutdown before + uninstalling the package. + + @return Whether to shutdown all applications at un-install. + */ + IMPORT_C TBool ShutdownAllAppsL(); + + /** + The function is used to re-verify the signature and certificate of the + SIS Controller associated to the RSisRegistryEntry object. + + aX509CertArray parameter is used to give set of trusted root certificates + that are used for validation of the SIS Controller certificate. If the + set given as parameter is empty, Symbian implementation can fetch the + set of trusted root certificates from Certificate Management. If the set + is not empty, then root certificates should not be fetched from + Certificate Mgmt, but only the root certificates from the set given as + parameter should be used for SIS Controller certificate validation. + + @param Array of trusted root certificates. + @return Returns ETrue if the registry entry is validated against the + trusted certificates provided. + */ + IMPORT_C TBool VerifyControllerSignatureL(RPointerArray& aX509CertArray); + + /** + The function is used to re-verify the signature and certificate of the + SIS Controller associated to the RSisRegistryEntry object. + + aX509CertArray parameter is used to give set of trusted root certificates + that are used for validation of the SIS Controller certificate. If the + set given as parameter is empty, Symbian implementation can fetch the + set of trusted root certificates from Certificate Management. If the set + is not empty, then root certificates should not be fetched from + Certificate Mgmt, but only the root certificates from the set given as + parameter should be used for SIS Controller certificate validation. + + @param aX509CertArray Array of trusted root certificates. + @param aCheckDateAndTime Indicates if the certificate validity period should be checked against the current date and time. + @return Returns ETrue if the registry entry is validated against the + trusted certificates provided. + */ + IMPORT_C TBool VerifyControllerSignatureL(RPointerArray& aX509CertArray, TBool aCheckDateAndTime); + + /** + Indicates whether or not the package will be removed by uninstalling the last dependant + */ + IMPORT_C TInt RemoveWithLastDependentL(); + + /** + This function is used to indicate the embedding package has been uninstalled but + this package remained because of dependency. + */ + IMPORT_C void SetRemoveWithLastDependentL(TUid uid); + + /** + * @return true if the 'non-removable' flag is NOT set in the SisInfo object + * belonging to this package. + */ + IMPORT_C TBool RemovableL(); + + /** + Returns set of drives to which files were installed in SIS file + @return Returns The bitmask of drives is as follows: + Bit 0 -> A drive + Bit 1 -> B drive + so on and so forth. + */ + IMPORT_C TUint InstalledDrivesL(); + + /** + * Returns whether or not the package was pre-installed + * + * @return ETrue if the package was pre-installed + * EFalse otherwise + */ + IMPORT_C TBool PreInstalledL(); + + /** + * Returns whether or not the package was pre-installed and files should + * be deleted on uninstall. This will have been set true if and only if + * the swipolicy indicates that preinstalled files can be deleted, and the + * stub sis file used to install the package was writable at install time. + * + * @return ETrue if the package was pre-installed and files should be + * deleted on uninstall. + * EFalse otherwise + */ + IMPORT_C TBool IsDeletablePreInstalledL(); + + + /** + * Returns the array of packages which are either dependent on this package or are + * augmentations of this package. + * + * @note + * A is a "Dependent" of B if B is in A's dependency list + * A is a "dependency" of B if A is in B's dependency list + * For example consider a package Shared_library_B which is used by a package App_A. + * Shared_Library_B will be listed as a dependency in the sis file which installs App_A + * App_A cannot be installed successfully without Shared_Library_B being present. + * If Shared_Library_B is un-installed App_A may not function correctly. + * App_A is a "dependent" of Shared_library_B + * Shared_library_B is a "dependency" of App_A + * + * @param aDependents The array of packages which are either dependent on this package + * or are augmentations of this package (i.e. its dependents) + * + */ + IMPORT_C void DependentPackagesL(RPointerArray& aDependents); + + /** + * Returns the dependency array for this package (ie the packages, denoted + * by UID and the version ranges it depends on). + * + * @note + * A is a "Dependent" of B if B is in A's dependency list + * A is a "dependency" of B if A is in B's dependency list + * For example consider a package Shared_library_B which is used by a package App_A. + * Shared_Library_B will be listed as a dependency in the sis file which installs App_A + * App_A cannot be installed successfully without Shared_Library_B being present. + * If Shared_Library_B is un-installed App_A may not function correctly. + * In this scenario + * App_A is a "dependent" of Shared_library_B + * Shared_library_B is a "dependency" of App_A + * + * @param aDependencies The array of packages that this package depends on (i.e. its dependencies) + * + */ + IMPORT_C void DependenciesL(RPointerArray& aDependencies); + + /** + * For a given package entry, return a array of packages that were + * embedded within this package. + * + * @param aEmbedded The array of embedded packages + * + */ + IMPORT_C void EmbeddedPackagesL(RPointerArray& aEmbedded); + + /** + * For a given package entry, return a array of packages that + * embed it. + * Note: This is possible when package A embeds D and the subsequently installed packages + * B and C each in turn embed D. As there will be a single copy and a single + * registration for D, it is imperative this back information is retained + * and it is accessible. + * + * @param aEmbedding The array of embedding packages + * + */ + IMPORT_C void EmbeddingPackagesL(RPointerArray& aEmbedding); + + /** + * Returns ETrue if the SIS package is signed by a certificate trusted by the device (SU) + * for eclipsing of files on the Z drive + * + */ + IMPORT_C TBool IsSignedBySuCertL(); + +protected: + /** + * @internalComponent + */ + HBufC8* SendReceiveBufferLC(TInt aMessage); + /** + * @internalComponent + */ + HBufC8* SendReceiveBufferLC(TInt aMessage, const TDesC& aInputDescriptor); + }; + +} // namespace +#endif