--- /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 <e32std.h>
+#include <swi/sispackagetrust.h>
+
+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<TUid>& 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<HBufC>& 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<HBufC8>& 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<HBufC>& aPackageNames, RPointerArray<HBufC>& 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<CSisRegistryPackage>& 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<HBufC8>& 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<CX509Certificate>& 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<CX509Certificate>& 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<CSisRegistryPackage>& 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<CSisRegistryDependency>& 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<CSisRegistryPackage>& 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<CSisRegistryPackage>& 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