--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/installationservices/swinstallationfw/inc/sifcommon.h Fri Mar 19 09:33:35 2010 +0200
@@ -0,0 +1,575 @@
+/*
+* Copyright (c) 2008-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:
+* This file defines common types for the SIF APIs.
+*
+*/
+
+
+/**
+ @file
+ @publishedAll
+ @released
+*/
+
+#ifndef SIFCOMMON_H
+#define SIFCOMMON_H
+
+#include <ct/rcpointerarray.h>
+#include <s32strm.h>
+#include <usif/usifcommon.h>
+
+namespace Usif
+ {
+
+ /**
+ 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 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 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,
+ RPointerArray<CNode>* 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<CNode>& 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;
+
+ 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
+ RCPointerArray<CNode> 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.
+ */
+ 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 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 the integer 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 AddIntL(const TDesC& aName, TInt aValue);
+
+ /**
+ 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<HBufC>. The caller must also destroy all the elements of aNames added
+ by this method.
+ @leave System wide error code
+ */
+ IMPORT_C void GetNamesL(RPointerArray<HBufC>& 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;
+
+ /**
+ 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;
+
+ /**
+ 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 VerifyExternalizedSizeForNewParamL(TInt aNameSize, TInt aValueSize) const;
+ void VerifyExternalizedSizeForExistingParamL(TInt aOldValueSize, TInt aNewValueSize) const;
+
+ struct TItem
+ {
+ HBufC* iName;
+ HBufC* iValue;
+ };
+ RArray<TItem> iParams;
+
+ mutable HBufC8* iExternalBuffer;
+ mutable TPtr8 iExternalBufferPtr;
+ mutable TBool iDeferredInternalization;
+ mutable TInt iExternalizedSize;
+
+ enum
+ {
+ // An arbitrary limit for the length of a single descriptor (the name or value of a param)
+ KMaxDescriptorLength = 128,
+ // An arbitrary size of the internal buffer for sending the component info across the process boundary
+ KMaxExternalizedSize = 512
+ };
+
+ };
+
+ /**
+ Pre-defined opaque arguments and results:
+ "InstallInactive" - 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" - 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.
+ "ComponentId" - If returned in the custom results, provides the id of the newly added component
+ after an install. Please note that not all installers (i.e. SIF Plugins) may support this.
+ "ExtendedErrCode" - If returned in the custom results gives the extended error information, that is
+ specific to a software component type.
+ */
+ _LIT(KSifInParam_InstallInactive, "InstallInactive");
+ _LIT(KSifInParam_InstallSilently, "InstallSilently");
+ _LIT(KSifOutParam_ComponentId, "ComponentId");
+ _LIT(KSifOutParam_ExtendedErrCode, "ExtendedErrCode");
+
+ /**
+ 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