diff -r 5cc91383ab1e -r 7333d7932ef7 installationservices/swinstallationfw/inc/sifcommon.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/installationservices/swinstallationfw/inc/sifcommon.h Tue Aug 31 15:21:33 2010 +0300 @@ -0,0 +1,774 @@ +/* +* Copyright (c) 2008-2010 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: +* This file defines common types for the SIF APIs. +* +*/ + + +/** + @file + @publishedAll + @released +*/ + +#ifndef SIFCOMMON_H +#define SIFCOMMON_H + +#include +#include +#include + +namespace Usif + { + class MOpaqueParam; + + /** + This enumeration defines the possible values of the status of an installation package. This status + can be obtained from a @see CComponentInfo object using the @see CComponentInfo::InstallStatusL() + method. + */ + enum TInstallStatus + { + ENewComponent, ///< New installation; the component is not present in the system + EUpgrade, ///< This is a valid upgrade of an existing component + EAlreadyInstalled, ///< Component with the same version is already installed + ENewerVersionAlreadyInstalled, ///< A newer version of the component is already installed + EInvalid ///< Package is not valid and cannot be installed, for example, + ///< it may be an upgrade of an uninstalled component or the + ///< package may be corrupt + }; + + /** + This enumeration defines the possible values of the authenticity of an installation package. This authenticity + can be obtained from a @see CComponentInfo object using the @see CComponentInfo::Authenticity() + method. + */ + enum TAuthenticity + { + ENotAuthenticated, ///< Component could not be authenticated by the installer, e.g. unsigned or self-signed + EAuthenticated, ///< Component is authenticated + }; + + /** + The TSecurityContext class allows SIF plug-ins to verify the capabilities and secure Ids of SIF clients. + For example, when a SIF client requests silent installation a SIF plug-in may verify that that the client + has the TrustedUI capability. + */ + class TSecurityContext + { + public: + /** + Checks if the SIF client has a given capability. + + @param aCapability The capability to test. + @return ETrue if the SIF client has the capability, EFalse otherwise. + */ + IMPORT_C TBool HasCapability(TCapability aCapability) const; + + /** + Checks if the SIF client has a given capability. + + @param aCapability The capability to test. + @leave KErrPermissionDenied If the SIF client does not have the capability. + */ + IMPORT_C void HasCapabilityL(TCapability aCapability) const; + + /** + Returns the secure Id of a SIF client. + */ + IMPORT_C TSecureId SecureId() const; + + private: + friend class CSifTransportRequest; + IMPORT_C TSecurityContext(const RMessage2& aMessage); + + const RMessagePtr2 iMsg; + }; + + /** + This class provides information about a software package. Returned by RSoftwareInstall::GetComponentInfo()." + */ + class CComponentInfo : public CBase + { + public: + + class CApplicationInfo : public CBase + { + public: + IMPORT_C static CApplicationInfo* NewLC(const TUid& aAppUid, const TDesC& aName, const TDesC& aGroupName, const TDesC& aIconFileName); + static CApplicationInfo* NewL(RReadStream& aStream); + void ExternalizeL(RWriteStream& aStream) const; + + IMPORT_C const TUid& AppUid() const; + IMPORT_C const TDesC& Name() const; + IMPORT_C const TDesC& GroupName() const; + IMPORT_C const TDesC& IconFileName() const; + IMPORT_C virtual ~CApplicationInfo(); + + private: + CApplicationInfo(); + + TUid iAppUid; // Application UID + HBufC* iName; // Name of the application + HBufC* iGroupName; // Group folder name where the application will be present + HBufC* iIconFileName; // Full path of the icon file + }; + + class CNode : public CBase + { + public: + /** + Initializes the object with the details of a component. + + @param aSoftwareTypeName The name of the software type of a component. + @param aComponentName The name of a component. + @param aVersion The version of a component. + @param aVendor The name of a component vendor. + @param aScomoState The SCOMO state of a component. + @param TInstallStatus The installation status of a component. + @param aComponentId The Id of a component. + @param aGlobalComponentId The global Id of a component. + @param aAuthenticity The authenticity of a component. + @param aUserGrantableCaps User grantable capabilities of a component. + @param aHasExe Whether component has an executable. + @param aIsDriveSelectionRequired Whether drive selection is required or not. + @param aApplications Information of the applications in the package. + @param aChildren Child nodes describing embedded components of a component. This method + passes the ownership of the child nodes to this new node and empties the aChildren array. + However, if the leave occurs the caller must delete the child nodes in the array. + @leave KErrOverflow it the total length of aName, aVersion and aVendor exceeds 512 characters. + @leave Or other system wide error code + */ + IMPORT_C static CNode* NewLC(const TDesC& aSoftwareTypeName, const TDesC& aComponentName, + const TDesC& aVersion, const TDesC& aVendor, TScomoState aScomoState, + TInstallStatus aInstallStatus, TComponentId aComponentId, + const TDesC& aGlobalComponentId, TAuthenticity aAuthenticity, + const TCapabilitySet& aUserGrantableCaps, TInt aMaxInstalledSize, + TBool aHasExe, TBool aIsDriveSelectionRequired, + RPointerArray* aApplications = NULL, + RPointerArray* aChildren = NULL); + + /** + Adds a child node to this node. This method passes the ownership of the child node + to this node so the caller must pop it from the cleanup stack but not delete. + + @return The pointer to the child node to be added. + @leave System wide error code + */ + IMPORT_C void AddChildL(CNode* aChild); + + /** + Returns the name of software type of a component. + + @return The name of the software type of a component. + @leave System wide error code + */ + IMPORT_C const TDesC& SoftwareTypeName() const; + + /** + Returns the name of a component. + + @return The name of a component. + @leave System wide error code + */ + IMPORT_C const TDesC& ComponentName() const; + + /** + Returns the version of a component. + + @return The version of a component. + @leave System wide error code + */ + IMPORT_C const TDesC& Version() const; + + /** + Returns the name of the component vendor. + + @return The name of the component vendor. + @leave System wide error code + */ + IMPORT_C const TDesC& Vendor() const; + + /** + Returns the SCOMO state of a component. This has meaning only if the installStatus of the component + is not EInvalid or ENewComponent. + + @return The SCOMO state of a component. + @leave System wide error code + */ + IMPORT_C TScomoState ScomoState() const; + + /** + Returns the installation status of a component. + + @return The installation status of a component. + @leave System wide error code + */ + IMPORT_C TInstallStatus InstallStatus() const; + + /** + Returns the Id of a component. + + @return The Id of a component. + @leave System wide error code + */ + IMPORT_C TComponentId ComponentId() const; + + /** + Returns the global Id of a component. + + @return The global Id of a component. + @leave System wide error code + */ + IMPORT_C const TDesC& GlobalComponentId() const; + + /** + Returns the authenticity of a component. + + @return The authenticity of a component. + @leave System wide error code + */ + IMPORT_C TAuthenticity Authenticity() const; + + /** + Returns user capabilities required by a component. + + @return The user grantable capabilities. + @leave System wide error code + */ + IMPORT_C const TCapabilitySet& UserGrantableCaps() const; + + /** + Returns the maximum size of a component after installation. + + @return The maximum size of a component. + @leave System wide error code + */ + IMPORT_C TInt MaxInstalledSize() const; + + /** + Returns the array of CComponentInfo objects for the components embedded + in the component being queried. + + @return The array of the embedded CComponentInfo objects. + @leave System wide error code + */ + IMPORT_C const RPointerArray& Children() const; + + /** + Destructor. + */ + IMPORT_C virtual ~CNode(); + /** + Returns the HasExecutable Flag which indicates whether the + component has an executable. + + @return The HasExecutable TBool Flag . + */ + IMPORT_C TBool HasExecutable() const; + + /** + Returns the IsDriveSelectionRequired Flag which indicates whether the + drive selection is required or not. + + @return The IsDriveSelectionRequired TBool Flag . + */ + IMPORT_C TBool DriveSeletionRequired() const; + + /** + Returns the applications in the component being queried. + + @return The array of the CApplicationInfo objects. + @leave System wide error code + */ + IMPORT_C const RPointerArray& Applications() const; + + private: + friend class CComponentInfo; + + CNode(); + CNode& operator=(const CNode& other); + CNode(const CNode& other); + + static CNode* NewL(RReadStream& aStream); + void ExternalizeL(RWriteStream& aStream) const; + + HBufC* iSoftwareTypeName; ///< The name of software type of the component + HBufC* iComponentName; ///< The name of the software component + HBufC* iVersion; ///< The Version of the software component + HBufC* iVendor; ///< The of the vendor of the software component + HBufC* iGlobalComponentId; ///< The global id of the component if already installed + TScomoState iScomoState; ///< The SCOMO status of the component + TInstallStatus iInstallStatus; ///< Informs whether the component is already installed or upgradeable + TComponentId iComponentId; ///< The unique id of the component if already installed + TAuthenticity iAuthenticity; ///< The authenticity of the component + TCapabilitySet iUserGrantableCaps; ///< User grantable capabilities required be the component + TInt iMaxInstalledSize; ///< The maximum size of the component after installation + TBool iHasExe; ///< Indicates Whether the component has an executable + TBool iIsDriveSelectionRequired; ///< Indicates Whether drive selection is required or not. + RCPointerArray iApplications; ///< The array of application info of the component being queried + RCPointerArray iChildren; ///< The array of components embedded in the component being queried + }; + + public: + + /** + Creates a new instance of the CComponentInfo class. + + @leave System wide error code + */ + IMPORT_C static CComponentInfo* NewL(); + + /** + Creates a new instance of the CComponentInfo class. + + @leave System wide error code + */ + IMPORT_C static CComponentInfo* NewLC(); + + /** + Returns the root node of this CComponentInfo object. + + @return The root node of this CComponentInfo object. + @leave System wide error code + */ + IMPORT_C const CNode& RootNodeL() const; + + /** + Sets a node as the root node of this component info. This method passes the + ownership of the root node to this object so the caller must pop it from the + cleanup stack but not delete. + + @return The pointer to the root node to be set. + @leave System wide error code + */ + IMPORT_C void SetRootNodeL(CNode* aRootNode); + + /** + Returns the pointer to the root node of this object. The caller takes the ownership + of this node and must delete it when no longer needed. After this call the CComponentInfo + object doesn't contain a root node. Hence, calling RootNodeL() results in the leave with + KErrNotFound. + + @return The pointer to the root node. + @leave System wide error code + */ + IMPORT_C void SetRootNodeAsChildL(CNode& aParentNode); + + /** + Externalises an object of this class to a write stream. + + @param aStream Stream to which the object should be externalised. + @leave System wide error code + */ + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + + /** + Allocates a buffer for serialized CComponentInfo and registers it in the @see TIpcArgs class. + The SIF server serializes a @see CComponentInfo object into this buffer. + + @param aIpcArgs Arguments to be sent to the SIF Server. + @param aIndex An index value that identifies the slot in the array of arguments into which + the argument value is to be placed. This must be a value in the range 0 to 3. + @leave System wide error code + */ + IMPORT_C void PrepareForIpcL(TIpcArgs& aIpcArgs, TInt aIndex); + + /** + Destructor. + */ + IMPORT_C virtual ~CComponentInfo(); + + private: + CComponentInfo(); + CComponentInfo& operator=(const CComponentInfo& other); + CComponentInfo(const CComponentInfo& other); + + void InternalizeFromExternalBufferL() const; + void ConstInternalizeL(RReadStream& aStream) const; + void CleanupExternalBuffer() const; + + CNode* iRootNode; + + mutable HBufC8* iExternalBuffer; + mutable TPtr8 iExternalBufferPtr; + mutable TBool iDeferredInternalization; + + enum + { + // An arbitrary limit for the length of a single descriptor, for example aComponentName, aVersion or aVendor. + KMaxDescriptorLength = 256, + // An arbitrary limit for the total length of iSoftwareTypeName, iComponentName, iVersion, iVendor and iGlobalComponentId. + KMaxHeapBufLength = 2048, + // An arbitrary size of the internal buffer for sending the component info across the process boundary + KMaxComponentInfoStreamedSize = 2*KMaxHeapBufLength+6*sizeof(TInt)+sizeof(TInt8), + }; + }; + + + /** + The COpaqueNamedParams class is a container for integer and string values identified by name. + + This class is designed for sending opaque params across the process boundary. For example, a SIF + client may use it to send custom arguments to the SIF server or receive custom results. + */ + NONSHARABLE_CLASS(COpaqueNamedParams) : public CBase + { + public: + /** + Creates a new instance of the COpaqueNamedParams class. + + @leave System wide error code + */ + IMPORT_C static COpaqueNamedParams* NewL(); + + /** + Creates a new instance of the COpaqueNamedParams class. + + @leave System wide error code + */ + IMPORT_C static COpaqueNamedParams* NewLC(); + + /** + Externalises an object of this class to a write stream. + + @param aStream Stream to which the object should be externalised. + @leave System wide error code + */ + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + + /** + Internalises an object of this class from a read stream. + + @param aStream Stream from which the object should be internalised. + @leave System wide error code + */ + IMPORT_C void InternalizeL(RReadStream& aStream); + + /** + Allocates a buffer and serializes the params of this object into it. The buffer is registered + in the @see TIpcArgs class in order to be sent to the SIF Server. + + @param aIpcArgs Ipc arguments to be sent to the SIF Server. + @param aIndex An index value that identifies the slot in the array of arguments into which + the argument value is to be placed. This must be a value in the range 0 to 3. + @leave System wide error code + */ + IMPORT_C void PrepareArgumentsForIpcL(TIpcArgs& aIpcArgs, TInt aIndex) const; + + /** + Allocates a buffer for serialized opaque results and registers it in the TIpcArgs class. + The SIF server serializes opaque results into this buffer. + + @param aIpcArgs Arguments to be sent to the SIF Server. + @param aIndex An index value that identifies the slot in the array of arguments into which + the argument value is to be placed. This must be a value in the range 0 to 3. + @leave System wide error code + */ + IMPORT_C void PrepareResultsForIpcL(TIpcArgs& aIpcArgs, TInt aIndex); + + /** + Returns the number of the opaque params added to this object. + @leave System wide error code + */ + IMPORT_C TInt CountL() const; + + /** + Adds a string param to this object. If a param with the same name already exists it gets overwritten. + + @param aName The name of the string param to be added. + @param aValue The value of the string param to be added. + @leave KErrOverflow if the size of the name or value of the string param being added exceeds 128 bytes or + the memory allocated for all the params added to this container exceeds 512 bytes. + @leave System wide error code + */ + IMPORT_C void AddStringL(const TDesC& aName, const TDesC& aValue); + + /** + Adds a string array param to this object. If a param with the same name already exists it gets overwritten. + + @param aName The name of the string param to be added. + @param aValueArray The array of value string params to be added. + @leave KErrOverflow if the size of the name or any value in the string array being added exceeds 128 bytes or + the memory allocated for all the params added to this container exceeds 512 bytes. + @leave System wide error code. + */ + IMPORT_C void AddStringArrayL(const TDesC& aName, const RPointerArray& aValueArray); + + /** + Adds an integer param to this object. If a param with the same name already exists it gets overwritten. + + @param aName The name of the integer param to be added. + @param aValue The value of the integer param to be added. + @leave KErrOverflow if the size of the name being added exceeds 128 bytes or + the memory allocated for all the params added to this container exceeds 512 bytes. + @leave System wide error code + */ + IMPORT_C void AddIntL(const TDesC& aName, TInt aValue); + + /** + Adds an integer array param to this object. If a param with the same name already exists it gets overwritten. + + @param aName The name of the integer param to be added. + @param aValueArray The array of value integer params to be added. + @leave KErrOverflow if the size of the name being added exceeds 128 bytes or + the memory allocated for all the params added to this container exceeds 512 bytes. + @leave System wide error code. + */ + IMPORT_C void AddIntArrayL(const TDesC& aName, const RArray& aValueArray); + + + /** + Returns the list of the names of params added to the object. + + @param aNames The list of the names of params. The caller is responsible for the instantiation + and cleanup of RPointerArray. The caller must also destroy all the elements of aNames added + by this method. + @leave System wide error code + */ + IMPORT_C void GetNamesL(RPointerArray& aNames) const; + + /** + Gets a reference to the string param identified by aName. + + @param aName The name of the string param to be obtained. + @return The value of the string param or KNullDesC if not found. + @leave System wide error code + */ + IMPORT_C const TDesC& StringByNameL(const TDesC& aName) const; + + /** + Gets a reference to the string array param identified by aName. + + @param aName The name of the string param to be obtained. + @return The string array param. + @leave KErrNotFound if aName is not found. + @leave System wide error code. + */ + IMPORT_C const RPointerArray& StringArrayByNameL(const TDesC& aName) const; + + /** + Returns the integer param identified by aName. + + @param aName The name of the integer param to be obtained. + @param aValue The value of the integer param returned by this method. + @return Indicates if the requested param has been found. + @leave System wide error code + */ + IMPORT_C TBool GetIntByNameL(const TDesC& aName, TInt& aValue) const; + + /** + Returns the integer param identified by aName. + + @param aName The name of the integer param to be obtained. + @return The value of the integer param. + @leave KErrNotFound if not found + @leave Or other system-wide error code. + */ + IMPORT_C TInt IntByNameL(const TDesC& aName) const; + + /** + Returns the integer array param identified by aName. + + @param aName The name of the integer param to be obtained. + @return The integer array param. + @leave KErrNotFound if aName is not found. + @leave Or other system-wide error code. + */ + IMPORT_C const RArray& IntArrayByNameL(const TDesC& aName) const; + + /** + Empties the container and frees all memory allocated to the params. + */ + IMPORT_C void Cleanup(); + + /** + Destructor. + */ + IMPORT_C virtual ~COpaqueNamedParams(); + + private: + COpaqueNamedParams(); + COpaqueNamedParams& operator=(const COpaqueNamedParams& other); + COpaqueNamedParams(const COpaqueNamedParams& other); + + void InternalizeFromExternalBufferL() const; + void ConstInternalizeL(RReadStream& aStream) const; + void ConstCleanup() const; + void CleanupExternalBuffer() const; + void VerifyExternalizedSizeForNewParamArrayL(TInt aNameSize, TInt aValueSize) const; + void VerifyExternalizedSizeForExistingParamArrayL(TInt aOldValueSize, TInt aNewValueSize) const; + void AddOpaqueParamL(MOpaqueParam* aItemBase); +private: + RPointerArray iParams; + + mutable HBufC8* iExternalBuffer; + mutable TPtr8 iExternalBufferPtr; + mutable TBool iDeferredInternalization; + mutable TInt iExternalizedSize; + + }; + + /** + Input Opaque Parameters: + + Pre-defined opaque arguments and results: + "InstallInactive" - Yes/No + If provided in the opaque installation parameters, requests the installation of + a component without activating it. Otherwise, components are activeted after installation by default. + + "InstallSilently" - Yes/No + If provided in the opaque installation parameters, requests a silent installation, + i.e. one which avoids interaction with the user whenever possible. Please note that this may involve + additional security checks, and is not necessarily supported by all installers. + + "Drive" - Array of TUInt + Preffered drive in the order of priority with zero index being the highest priority + + "Languages" - Array of TLanguage + List of languages to use + + "OCSPUrl" - TDesC + The OSCP responder's URL + + "PerformOCSP" - TSifPolicy + Whether OCSP should be performed or not or Request user + + "IgnoreOCSPWarnings" - TSifPolicy + Action in case of OCSP warnings + + "AllowUpgrade" - TSifPolicy + Allow an upgrade (if yes, upgrade of the application) + + "AllowUpgradeData" - TSifPolicy + Whether private data of the application to be retained or removed during the upgrade + + "InstallOptionalItems" - TSifPolicy + Install optional items in package + + "AllowUntrusted" - TSifPolicy + Check if installation of untrusted (uncertified) package is allowed + + "GrantCapabilities" - TSifPolicy + Whether to grant user capabilities + + "AllowAppShutdown" - TSifPolicy + Should we silently kill an application if needed + + "AllowAppBreakDependency" - TSifPolicy + Allow uninstall of dependent packages + + "AllowOverwrite" - TSifPolicy + Can files be overwritten + + "PackageInfo" - TSifPolicy + Whether to skip infos + + "AllowDownload" - TSifPolicy + Is it ok to download + + "UserName" - TDesC + UserName for Download request + + "Password" - TDesC + Password for Download request + + "SourceUrl" - TDesC + SourceUrl or Directory + + "IAP" - TInt + Internet Access Point + + "SNAP" - TInt + Service Network Access Point, alternative to passing iap + + "MimeType" - TDesC + Represents MIME Type to be used during HTTP download + + "Charset" - TDesC + Represents charset to be used during HTTP download + + "AllowIncompatible" - TSifPolicy + Check if installation of incompatible packages is allowed + + + + Output Opaque parameters: + + "ComponentId" - Array of TUInt + If returned in the custom results, provides the id's of the newly added components + after an install. Please note that not all installers (i.e. SIF Plugins) may support this. + Eg: Includes embedded sis packages component ID's as well for native installer + + "ErrCategory" - TInt + If returned in the custom results gives the error category, that is defined by USIF + + "ErrCode" - TInt + If returned in the custom results gives one of the USIF error code. + + "ExtendedErrCode" - TInt + If returned in the custom results gives the extended error information, that is specific to + a software component type. + + "ErrMessage" - TDesC + If returned in the custom results gives the localized error message + + "ErrMessageDetails" - TDesC + If returned in the custom results gives the localized error message details about error + + */ + _LIT(KSifInParam_InstallInactive, "InstallInactive"); + _LIT(KSifInParam_InstallSilently, "InstallSilently"); + _LIT(KSifInParam_Drive, "Drive"); + _LIT(KSifInParam_Languages, "Languages"); + _LIT(KSifInParam_OCSPUrl, "OCSPUrl"); + _LIT(KSifInParam_PerformOCSP, "PerformOCSP"); + _LIT(KSifInParam_IgnoreOCSPWarnings, "IgnoreOCSPWarnings"); + _LIT(KSifInParam_AllowUpgrade, "AllowUpgrade"); + _LIT(KSifInParam_AllowUpgradeData, "AllowUpgradeData"); + _LIT(KSifInParam_InstallOptionalItems, "InstallOptionalItems"); + _LIT(KSifInParam_AllowUntrusted, "AllowUntrusted"); + _LIT(KSifInParam_GrantCapabilities, "GrantCapabilities"); + _LIT(KSifInParam_AllowAppShutdown, "AllowAppShutdown"); + _LIT(KSifInParam_AllowAppBreakDependency, "AllowAppBreakDependency"); + _LIT(KSifInParam_AllowOverwrite, "AllowOverwrite"); + _LIT(KSifInParam_PackageInfo, "PackageInfo"); + _LIT(KSifInParam_AllowDownload, "AllowDownload"); + _LIT(KSifInParam_UserName, "UserName"); + _LIT(KSifInParam_Password, "Password"); + _LIT(KSifInParam_SourceUrl, "SourceUrl"); + _LIT(KSifInParam_IAP, "IAP"); + _LIT(KSifInParam_SNAP, "SNAP"); + _LIT(KSifInParam_MimeType, "MimeType"); + _LIT(KSifInParam_Charset, "Charset"); + _LIT(KSifInParam_AllowIncompatible, "AllowIncompatible"); + + _LIT(KSifOutParam_ComponentId, "ComponentId"); + _LIT(KSifOutParam_ErrCategory, "ErrCategory"); + _LIT(KSifOutParam_ErrCode, "ErrCode"); + _LIT(KSifOutParam_ExtendedErrCode, "ExtendedErrCode"); + _LIT(KSifOutParam_ErrMessage, "ErrMessage"); + _LIT(KSifOutParam_ErrMessageDetails, "ErrMessageDetails"); + + /** + SIF Server Secure ID + + Installers should use this id to verify that installation requests come from the SIF Server. + */ + _LIT_SECURE_ID(KSifServerUid,0x10285BCB); + + } // namespace Usif + +#endif // USIF_SIF_COMMON_H