/*
* Copyright (c) 2002-2003 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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:  Definition of the MInstalledAppsRegistry.
*
*/


#ifndef MINSTALLEDAPPSREGISTRY_H
#define MINSTALLEDAPPSREGISTRY_H

// INCLUDE FILES

#include <e32base.h>
#include <appversion.h>

#include "installtypes.h"

// FORWARD DECLARATIONS

class MInstalledAppsRegistryEntry;

// CLASS DECLARATIONS

/**
* The registry of installed applications. This registry allows read access
* to entries. Each entry is defined by class MInstalledAppsRegistryEntry.
*
* The client implementation marshals the requests to the server. Access
* is only read only. The server implementation allows additionally for
* write access.
*/
class MInstalledAppsRegistry
{
public:
    /**
    * Release destroys this object (or removes the reference to
    * a reference counted implementation).
    */
    virtual void Release() = 0;

    /**
    * Returns an array of installed UIDs. The array is supplied by the client
    * which is then populated. There is no guarantee about the order in which
    * the uids are put in the array.
    * @param aUidArray The array object to be populated. This array should be
    * empty before passing it in. The result is undefined if the array is
    * not empty.
    */
    virtual void InstalledUidsL(RArray<TUid>& aUidArray) const = 0;

    /**
    * API call to check if an entry with the given UID is present in the
    * registry.
    * @param aUid The UID to query.
    * @return ETrue if there exists an entry present with the given UID,
    *         EFalse otherwise.
    */
    virtual TBool EntryPresentL(const TUid& aUid) const = 0;

    /**
    * Returns an entry from the registry whose UID is equal to aUid
    * @param aUid The UID of the entry to be found.
    * @return A pointer to the entry. Note that ownership of this object
    *         is transferred to the calling client and is therefore
    *         required to destroy it. The pointer is guarenteed to be
    *         non-NULL.
    */
    virtual MInstalledAppsRegistryEntry* EntryLC
    (const TUid& aUid) const = 0;
    virtual MInstalledAppsRegistryEntry* EntryL
    (const TUid& aUid) const = 0;

    /**
    * Returns an entry from the registry with a given package name and
    * vendor name for a given language.
    * @return A pointer to the entry. Note that ownership of this object
    *         is transferred to the calling client and is therefore
    *         required to destroy it. The pointer is guarenteed to be
    *         non-NULL.
    */
    virtual MInstalledAppsRegistryEntry* EntryLC
    (TLanguage aLang,
     const TDesC& aPackage,
     const TDesC& aVendor) const = 0;
    virtual MInstalledAppsRegistryEntry* EntryL
    (TLanguage aLang,
     const TDesC& aPackage,
     const TDesC& aVendor) const = 0;

    /**
    * Returns the system property given by the UID. Leaves with KErrNotFound
    * if the property was not found.
    * @param aPropertyId The UID of the given property.
    * @return The value - ownership of the buffer is transferred to client.
    */
    virtual HBufC8* GetSystemPropertyL(TUid aPropertyId) const = 0;

    /**
    * Function to create a registry. This returns a server registry or client
    * registry, depending on which library is linked
    */
    IMPORT_C static MInstalledAppsRegistry* CreateL();

protected:
    // Forces client to use the Release method
    inline virtual ~MInstalledAppsRegistry();
};


/**
* An entry of an installed application. These entries created and retrieved
* using the MInstalledAppsRegistry API.
*
* Each entry is keyed by a UID, and contains various fields and parameters.
* It also contains a list of files which make up the application, and
* a list of languages the application supports.
*/
class MInstalledAppsRegistryEntry
{
public:
    /**
    * Release destroys this object (or removes the reference to
    * a reference counted implementation)
    */
    virtual void Release() = 0;

    // API attribute getters - synchronous
    virtual TUid UidL() const = 0;
    virtual TAppVersion VersionL() const = 0;
    virtual TChar DriveL() const = 0;
    virtual TInstallType TypeL() const = 0;

    /**
    * Given a language, return the package name. If the language is not
    * found, it will leave with KErrNotFound.
    * @param aLanguage Language of the package.
    * @return The returned package name in the given language.
    */
    virtual const TDesC& PackageNameL(TLanguage aLanguage) const = 0;

    /**
    * Given a language, return the vendor name. If the language is not found,
    * it will leave with KErrNotFound.
    * @param aLanguage Language of the package.
    * @return The returned vendor name
    */
    virtual const TDesC& VendorNameL(TLanguage aLanguage) const = 0;

    /**
    * Populates a client owned array with the list of languages.
    * @param[out] aLangArray List of supported languages.
    */
    virtual void LanguagesL(RArray<TLanguage>& aLangArray) const = 0;

    /**
    * Returns whether or not a particular language is supported.
    * @param aLanguage Language support to check.
    */
    virtual TBool LanguageSupportedL(TLanguage aLanguage) const = 0;

    /**
    * Populates the input array with the list of files used by the
    * application - synchronous.
    * @param[out] aFileArray The array to be populated.
    */
    virtual void ListFilesL(RPointerArray<HBufC>& aFileArray) const = 0;

    /**
    * Given a filename (with a full path specifier), this function
    * returns whether or not this application uses the file.
    * @param aFileName Name of the file to check.
    * @return ETrue if the specified file is used by this application,
    * EFalse otherwise.
    */
    virtual TBool UsesFileL(const TDesC& aFileName) const = 0;

    /**
    * Populates the input array with the list of directories "owned" by the
    * application.
    * @param[out] aDirArray The array to be populated.
    */
    virtual void ListDirectoriesL
    (RPointerArray<HBufC>& aDirArray) const = 0;

    /**
    * Returns the number of certificate chains.
    */
    virtual TInt NumberOfCertificateChainsL() const = 0;

    /**
    * Returns the n-th chain.
    */
    virtual const TDesC8& CertificateChainL(TInt aChain) const = 0;

    /**
    * Returns the size in bytes used by the installed application.
    * The size is computed dynamically by adding the size of the files owned
    * by this entry. If a file is not found (it may be on an absent removable
    * media) its size is considered to be 0. Entries may own directories,
    * in this case all the files in these directories are considered to be
    * owned and are included in the computation.
    */
    virtual TInt SizeL() const = 0;

    /**
    * Given a file extension, return a single filename with that
    * extension. Leaves if not found. It is generally used to find
    * a .jad or .jar file location in the registry.
    * @param aExtension The extension to search for (eg ".app").
    * @param aFileName The returned file name with the extension.
    */
    virtual void FindFileWithExtL(const TDesC& aExtension,
                                  TFileName& aFileName) const = 0;

    /**
    * Returns a boolean which indicates whether or not this entry is
    * located in ROM. An entry located in ROM cannot be uninstalled.
    * @return ETrue if located in ROM, EFalse otherwise.
    */
    virtual TBool IsInRomL() const = 0;

    /**
    * Returns property of the entry keyed by the supplied UID. Leaves with
    * KErrNotFound if the property was not found in the entry.
    * @param aPropertyId The UID of the given property.
    * @return The value - ownership of the buffer is transferred to client.
    */
    virtual HBufC8* GetPropertyL(TUid aPropertyId) const = 0;

    /**
    * Populates the array parameter with the list of Apparc registration
    * file "ID"-s.
    * @param aApparcIdentifiersArray The array to be populated.
    */
    virtual void ListApparcIdentifiersL
    (RPointerArray<HBufC>& aApparcIdentifiersArray) const = 0;

protected:
    inline virtual ~MInstalledAppsRegistryEntry();
};

#include <swi/minstalledappsregistry.inl>

#endif // MINSTALLEDAPPSREGISTRY_H