/*

* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* which accompanies this distribution, and is available

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Interface for quering system paths.

*

*/

#ifndef PATH_INFO_H

#define PATH_INFO_H

//  INCLUDES

#include <e32std.h>

#include <badesca.h>

// CLASS DECLARATION

/**

* Class holds information of system paths. Platform Environment API provides

* interface for quering system paths. Methods provided by the API should be

* used instead of hard coded path names. All paths have the trailing backslash

* included. The API consist of the PathInfo class, DriveInfo class and system paths are defined

* in PathConfiguration.hrh. The DriveInfo class is defined in DriveInfo.h.

*

* Usage:

*

* @code

*  #include <PathInfo.h>

*

*  // Get the root path of Phone Memory.

*  TFileName path = PathInfo::PhoneMemoryRootPath();

*

*  // Get the games path and append the path to the root path of Phone Memory.

*  path.Append( PathInfo::GamesPath() );

*

*  // 'path' contains now the games path in Phone Memory.

* @endcode

*

* Error handling:

*

* The panic mechanism is used to handle programming errors. 

* GetPath(TInt aPath) method will panic if invalid parameter is given as input. 

* The panic category is named PATHINFO and panic code is:

*

* - EInvalidParameter = 0 (Invalid parameter.)

*

*  @lib PlatformEnv.dll

*  @since 2.0

*/

class PathInfo

    {

    public:

        /**

		* Enumeration System Paths defines values to be used for the aPath parameter

		* in GetPath and GetFullPath methods.

        * @since 3.2

		*/

		enum TSystemPaths

			{

            /** This value is used only as a return value of PathType() to indicate that

            * the path is not a system path. It is not a valid system path to be given

            * as a parameter for GetPath() or GetFullPath()

            */

			ENotSystemPath = -1,

            /** To get the root path in ROM.

            */

			ERomRootPath = 0,

			/** To get the root path in Phone Memory..

            */

            EPhoneMemoryRootPath,

            /** To get the root path in Memory Card.

            */

			EMemoryCardRootPath, 

			/** To get the games path to be appended to a root path.

            */

            EGamesPath,

            /** To get the installs path to be appended to a root path.

            */

            EInstallsPath,

            /** To get the others path to be appended to a root path.

            */

            EOthersPath,

            /** To get the videos path to be appended to a root path.

            */

            EVideosPath,

            /** To get the images path to be appended to a root path.

            */

            EImagesPath,

            /**  To get the GSM pictures path to be appended to a root path.

            */

            EGsmPicturesPath,

            /** To get the MMS pictures path to be appended to a root path.

            */

            EMmsBackgroundImagesPath,

            /** To get the presence logos path to be appended to a root path.

            */

            EPresenceLogosPath,

            /** To get the sounds path to be appended to a root path.

            */

            ESoundsPath,            

            /** To get the digital sounds path to be appended to a root path.

            */  

            EDigitalSoundsPath,

            /** To get the simple sounds path to be appended to a root path.

            */

            ESimpleSoundsPath,

            /** To get the images thumbnail path.

            * The thumbnail images directory exists under the same directory

            * where the corresponding image is. 

            * Do not try to append this to a root directory.

            */

            EImagesThumbnailPath,

            /** To get the full path of the contacts folder in the memory card.

            * The path also contains the drive letter. Do not try to append 

            * this to any root directory.

            */ 

            EMemoryCardContactsPath

			};

        /**

        * This method returns the root path in ROM.

        * Corresponding TSystemPaths value of the returned path is ERomRootPath.

        *

        * @return The root path in ROM.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& RomRootPath();

        /**

        * This method returns the root path in Phone Memory.

        * Corresponding TSystemPaths value of the returned path is EPhoneMemoryRootPath.

        *

        * @return The root path in Phone Memory.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& PhoneMemoryRootPath();

        /**

        * This method returns the root path in Memory Card.

        * Corresponding TSystemPaths value of the returned path is EMemoryCardRootPath.

        *

        * @return The root path in Memory Card.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& MemoryCardRootPath();

        /**

        * This method returns the games path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is EGamesPath.

        *

        * @return The games path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& GamesPath();

        /**

        * This method returns the installs path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is EInstallsPath.

        *

        * @return The installs path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& InstallsPath();

        /**

        * This method returns the others path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is EOthersPath.

        *

        * @return The installs path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& OthersPath();

        /**

        * This method returns the videos path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is EVideosPath.

        *

        * @return The videos path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& VideosPath();

        /**

        * This method returns the images path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is EImagesPath.

        *

        * @return The images path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& ImagesPath();  

        /**

        * This method returns the pictures path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is EGsmPicturesPath.

        *

        * @return The pictures path.

        *

        * @deprecated Use GmsPicturesPath() instead.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& PicturesPath();       

        /**

        * This method returns the GMS pictures path to be appended to 

        * a root path.

        * Corresponding TSystemPaths value of the returned path is EGsmPicturesPath.

        *

        * @return The GSM pictures path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& GmsPicturesPath();

        /**

        * This method returns the MMS background images path to be appended to

        * a root path.

        * Corresponding TSystemPaths value of the returned path is EMmsBackgroundImagesPath.

        *

        * @return The MMS background images path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& MmsBackgroundImagesPath();

        /**

        * This method returns the presence logos path to be appended to 

        * a root path.

        * Corresponding TSystemPaths value of the returned path is EPresenceLogosPath.

        *

        * @return The presence logos path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& PresenceLogosPath();

        /**

        * This method returns the sounds path to be appended to a root path.

        * Corresponding TSystemPaths value of the returned path is ESoundsPath.

        *

        * @return The sounds path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& SoundsPath();

        /**

        * This method returns the digital sounds path to be appended to 

        * a root path.

        * Corresponding TSystemPaths value of the returned path is EDigitalSoundsPath.

        *

        * @return The digital sounds path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& DigitalSoundsPath();

        /**

        * This method returns the simple sounds path to be appended to 

        * a root path.

        * Corresponding TSystemPaths value of the returned path is ESimpleSoundsPath.

        *

        * @return The simple sound path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& SimpleSoundsPath();

        // ---------------------------------------------------------------------

        // Paths that are not necessarily under root directories

        // ---------------------------------------------------------------------

        /**

        * This method returns a thumbnail images path. The thumbnail images 

        * directory exists under the same directory where the corresponding 

        * image is. Do not try to append this to a root directory.

        * Corresponding TSystemPaths value of the returned path is EImagesThumbnailPath.

        *

        * @return The thumbnail images path.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& ImagesThumbnailPath();

        /**

        * This method returns the full path of the contacts folder in 

        * the memory card. The path also contains the drive letter. 

        * Do not try to append this to any root directory.

        * Corresponding TSystemPaths value of the returned path is EMemoryCardContactsPath.

        *

        * @return The full path of the contacts folder in the memory card.

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& MemoryCardContactsPath();

        /**

        * This method returns the requested system path.

        *

        * @since 3.2

        * @param aPath Defines the requested system path.

        * @return The requested system path.

        *

        * @panic EInvalidParameter Parameter aPath is invalid.

        *

        * One small sample describing the usage of the method.

        * @code

        *  #include <PathInfo.h>

        *

        *  // Get the the full path of the contacts folder in the memory card.

        *  TFileName path = PathInfo::GetPath( PathInfo::EMemoryCardContactsPath );

        *

        *  // 'path' contains now the full path of the contacts folder in the memory card..

        * @endcode

        *

        * @see TSystemPaths

        */

        IMPORT_C static const TDesC& GetPath( TInt aPath );

        /**

        * This method gets the root path of the requested drive.

        * The root path is the path where the system paths are located.

        *

        * @since 3.2

        * @param aRootPath Stores the path, the maximum path length is KMaxPath.

        * @param aDrive A drive identifier specified by TDriveNumber.

        * @return A system wide error code.

        * 

        * One small sample describing the usage of the method.

        * @code

        *  #include <PathInfo.h>

        *  #include <DriveInfo.h>

        *

        *  // Get the root path of the default phone memory.

        *  TInt drive;

        *  User::LeaveIfError( DriveInfo::GetDefaultDrive(

        *      DriveInfo::EDefaultPhoneMemory, drive ) );

        *  TFileName path;

        *  User::LeaveIfError( PathInfo::GetRootPath( path, drive ) );

        *

        *  // 'path' contains now the default folder root path of the default phone memory.

        * @endcode

        *

        * @see TDriveNumber

        * @see KMaxPath

        * @see DriveInfo

        */

        IMPORT_C static TInt GetRootPath( TDes& aRootPath, TInt aDrive );

        /**

        * This method gets the full path of the requested system path in the requested drive.

        * KErrNotFound is returned when the drive has no requested system path or 

        * the requested path cannot be added to the root path.

        *

        * @since 3.2

        * @param aFullPath Stores the requested path, the maximum path length is KMaxPath.

        * @param aDrive A drive identifier specified by TDriveNumber.

        * @param aPath Defines the requested system path.

        * @return A system wide error codes.

        *

        * One small sample describing the usage of the method.

        * @code

        *  #include <PathInfo.h>

        *  #include <DriveInfo.h>

        *

        *  // Get the full path of the images folder in the default

        *  // phone memory drive.

        *  TFileName path;

        *  TInt drive;

        *  User::LeaveIfError( DriveInfo::GetDefaultDrive(

        *      DriveInfo::EDefaultPhoneMemory, drive ) );

        *  User::LeaveIfError( PathInfo::GetFullPath( path, drive, PathInfo::EImages ) );

        *

        *  // 'path' contains now the full path of the images folder in the default

        *  // phone memory drive.

        * @endcode

        *

        * @see TDriveNumber

        * @see KMaxPath

        * @see TSystemPaths

        * @see DriveInfo

        */

        IMPORT_C static TInt GetFullPath( TDes& aFullPath, TInt aDrive, TInt aPath );

        /**

        * This method returns the system path type of the given path.

        * Thumbnail system path can exist in any folder.

        * Other paths must be exact system paths, not subfolders of a system path

        * ENotSystemPath is returned, if the path is not a system path.

        * The given path must have backslash ending.

        *

        * @since 3.2

        * @param aFullPath A path to be type checked

        * @return A value specified by TSystemPaths

        * 

        * One small sample describing the usage of the method.

        * @code

        *  #include <PathInfo.h>

        *

        *  // Check the type of the system path.

        * _LIT( KImagesPath, "E:\\Images\\" );

        *  TInt type( PathInfo::PathType( KImagesPath ) );

        *

        *  // 'type' contains now the EImagesPath value.

        * @endcode

        *

        * @see TSystemPaths

        */

        IMPORT_C static TInt PathType( const TDesC& aFullPath );

        /**

        * This method gets the list of full system paths in the requested drive 

        * and leaves the returned pointer in cleanup stack.

        *

        * @since 3.2

        * @param aDrive A drive identifier specified by TDriveNumber.

        * @return A list of the system paths. Ownership is transferred.

        *

        * One small sample describing the usage of the method.

        * @code

        *  #include <PathInfo.h>

        *  #include <DriveInfo.h>

        *

        *  // Create the default path structure for default mass storage drive

        *  TInt drive;

        *  User::LeaveIfError( DriveInfo::GetDefaultDrive(

        *      DriveInfo::EDefaultMassStorage, drive ) );

        *  CDesCArray* paths = PathInfo::GetListOfPathsLC( drive );

        *  TInt count( paths->MdcaCount() );

        *  for ( TInt i( 0 ); i < count; ++i )

        *      {

        *      User::LeaveIfError( iFs.MkDirAll( paths->MdcaPoint( i ) );

        *      }

        * CleanupStack::PopAndDestroy( paths );

        * // The default mass storage drive contains now the default path structure

        * @endcode

        *

        * @see TDriveNumber

        * @see DriveInfo

        */

        IMPORT_C static CDesCArray* GetListOfPathsLC( TInt aDrive );

        /**

        * This method gets the list of full system paths in the requested drive.

        *

        * @since 3.2

        * @param aDrive A drive identifier specified by TDriveNumber.

        * @return A list of the system paths. Ownership is transferred.

        *

        * @see TDriveNumber

        */

        IMPORT_C static CDesCArray* GetListOfPathsL( TInt aDrive );

    private:

        /**

        * C++ default constructor.

        */

        PathInfo();

    };

#endif      // PATH_INFO_H   

// End of File