/*

* 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 <ct/rcpointerarray.h>

#include <s32strm.h>

#include <usif/usifcommon.h>

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<CApplicationInfo>* aApplications = NULL, 

                                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;

            /**

            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<CApplicationInfo>& 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<CApplicationInfo> iApplications;     ///< The array of application info of the component being queried

            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.

    */

    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<HBufC>& 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.

        */