williamr@2: /*
williamr@2: * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Interface for quering system paths.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef PATH_INFO_H
williamr@2: #define PATH_INFO_H
williamr@2: 
williamr@2: //  INCLUDES
williamr@2: #include <e32std.h>
williamr@2: #include <badesca.h>
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: /**
williamr@2: * Class holds information of system paths. Platform Environment API provides
williamr@2: * interface for quering system paths. Methods provided by the API should be
williamr@2: * used instead of hard coded path names. All paths have the trailing backslash
williamr@2: * included. The API consist of the PathInfo class, DriveInfo class and system paths are defined
williamr@2: * in PathConfiguration.hrh. The DriveInfo class is defined in DriveInfo.h.
williamr@2: *
williamr@2: * Usage:
williamr@2: *
williamr@2: * @code
williamr@2: *  #include <PathInfo.h>
williamr@2: *
williamr@2: *  // Get the root path of Phone Memory.
williamr@2: *  TFileName path = PathInfo::PhoneMemoryRootPath();
williamr@2: *
williamr@2: *  // Get the games path and append the path to the root path of Phone Memory.
williamr@2: *  path.Append( PathInfo::GamesPath() );
williamr@2: *
williamr@2: *  // 'path' contains now the games path in Phone Memory.
williamr@2: * @endcode
williamr@2: *
williamr@2: * Error handling:
williamr@2: *
williamr@2: * The panic mechanism is used to handle programming errors. 
williamr@2: * GetPath(TInt aPath) method will panic if invalid parameter is given as input. 
williamr@2: * The panic category is named PATHINFO and panic code is:
williamr@2: *
williamr@2: * - EInvalidParameter = 0 (Invalid parameter.)
williamr@2: *
williamr@2: *  @lib PlatformEnv.dll
williamr@2: *  @since 2.0
williamr@2: */
williamr@2: 
williamr@2: class PathInfo
williamr@2:     {
williamr@2:     public:
williamr@2: 
williamr@2:         /**
williamr@2: 		* Enumeration System Paths defines values to be used for the aPath parameter
williamr@2: 		* in GetPath and GetFullPath methods.
williamr@2:         * @since 3.2
williamr@2: 		*/
williamr@2: 		enum TSystemPaths
williamr@2: 			{
williamr@2:             /** This value is used only as a return value of PathType() to indicate that
williamr@2:             * the path is not a system path. It is not a valid system path to be given
williamr@2:             * as a parameter for GetPath() or GetFullPath()
williamr@2:             */
williamr@2: 			ENotSystemPath = -1,
williamr@2:             /** To get the root path in ROM.
williamr@2:             */
williamr@2: 			ERomRootPath = 0,
williamr@2: 			/** To get the root path in Phone Memory..
williamr@2:             */
williamr@2:             EPhoneMemoryRootPath,
williamr@2:             /** To get the root path in Memory Card.
williamr@2:             */
williamr@2: 			EMemoryCardRootPath, 
williamr@2: 			/** To get the games path to be appended to a root path.
williamr@2:             */
williamr@2:             EGamesPath,
williamr@2:             /** To get the installs path to be appended to a root path.
williamr@2:             */
williamr@2:             EInstallsPath,
williamr@2:             /** To get the others path to be appended to a root path.
williamr@2:             */
williamr@2:             EOthersPath,
williamr@2:             /** To get the videos path to be appended to a root path.
williamr@2:             */
williamr@2:             EVideosPath,
williamr@2:             /** To get the images path to be appended to a root path.
williamr@2:             */
williamr@2:             EImagesPath,
williamr@2:             /**  To get the GSM pictures path to be appended to a root path.
williamr@2:             */
williamr@2:             EGsmPicturesPath,
williamr@2:             /** To get the MMS pictures path to be appended to a root path.
williamr@2:             */
williamr@2:             EMmsBackgroundImagesPath,
williamr@2:             /** To get the presence logos path to be appended to a root path.
williamr@2:             */
williamr@2:             EPresenceLogosPath,
williamr@2:             /** To get the sounds path to be appended to a root path.
williamr@2:             */
williamr@2:             ESoundsPath,            
williamr@2:             /** To get the digital sounds path to be appended to a root path.
williamr@2:             */  
williamr@2:             EDigitalSoundsPath,
williamr@2:             /** To get the simple sounds path to be appended to a root path.
williamr@2:             */
williamr@2:             ESimpleSoundsPath,
williamr@2:             /** To get the images thumbnail path.
williamr@2:             * The thumbnail images directory exists under the same directory
williamr@2:             * where the corresponding image is. 
williamr@2:             * Do not try to append this to a root directory.
williamr@2:             */
williamr@2:             EImagesThumbnailPath,
williamr@2:             /** To get the full path of the contacts folder in the memory card.
williamr@2:             * The path also contains the drive letter. Do not try to append 
williamr@2:             * this to any root directory.
williamr@2:             */ 
williamr@2:             EMemoryCardContactsPath
williamr@2: 
williamr@2: 			};
williamr@2: 
williamr@2:         /**
williamr@2:         * This method returns the root path in ROM.
williamr@2:         * Corresponding TSystemPaths value of the returned path is ERomRootPath.
williamr@2:         *
williamr@2:         * @return The root path in ROM.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& RomRootPath();
williamr@2:         /**
williamr@2:         * This method returns the root path in Phone Memory.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EPhoneMemoryRootPath.
williamr@2:         *
williamr@2:         * @return The root path in Phone Memory.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& PhoneMemoryRootPath();
williamr@2:         /**
williamr@2:         * This method returns the root path in Memory Card.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EMemoryCardRootPath.
williamr@2:         *
williamr@2:         * @return The root path in Memory Card.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& MemoryCardRootPath();
williamr@2: 
williamr@2: 
williamr@2:         /**
williamr@2:         * This method returns the games path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EGamesPath.
williamr@2:         *
williamr@2:         * @return The games path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& GamesPath();
williamr@2:         /**
williamr@2:         * This method returns the installs path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EInstallsPath.
williamr@2:         *
williamr@2:         * @return The installs path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& InstallsPath();
williamr@2:         /**
williamr@2:         * This method returns the others path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EOthersPath.
williamr@2:         *
williamr@2:         * @return The installs path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& OthersPath();
williamr@2:         /**
williamr@2:         * This method returns the videos path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EVideosPath.
williamr@2:         *
williamr@2:         * @return The videos path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& VideosPath();
williamr@2:         /**
williamr@2:         * This method returns the images path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EImagesPath.
williamr@2:         *
williamr@2:         * @return The images path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& ImagesPath();  
williamr@2:         /**
williamr@2:         * This method returns the pictures path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EGsmPicturesPath.
williamr@2:         *
williamr@2:         * @return The pictures path.
williamr@2:         *
williamr@2:         * @deprecated Use GmsPicturesPath() instead.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& PicturesPath();       
williamr@2:         /**
williamr@2:         * This method returns the GMS pictures path to be appended to 
williamr@2:         * a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EGsmPicturesPath.
williamr@2:         *
williamr@2:         * @return The GSM pictures path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& GmsPicturesPath();
williamr@2:         /**
williamr@2:         * This method returns the MMS background images path to be appended to
williamr@2:         * a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EMmsBackgroundImagesPath.
williamr@2:         *
williamr@2:         * @return The MMS background images path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& MmsBackgroundImagesPath();
williamr@2:         /**
williamr@2:         * This method returns the presence logos path to be appended to 
williamr@2:         * a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EPresenceLogosPath.
williamr@2:         *
williamr@2:         * @return The presence logos path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& PresenceLogosPath();
williamr@2:         /**
williamr@2:         * This method returns the sounds path to be appended to a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is ESoundsPath.
williamr@2:         *
williamr@2:         * @return The sounds path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& SoundsPath();
williamr@2:         /**
williamr@2:         * This method returns the digital sounds path to be appended to 
williamr@2:         * a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EDigitalSoundsPath.
williamr@2:         *
williamr@2:         * @return The digital sounds path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& DigitalSoundsPath();
williamr@2:         /**
williamr@2:         * This method returns the simple sounds path to be appended to 
williamr@2:         * a root path.
williamr@2:         * Corresponding TSystemPaths value of the returned path is ESimpleSoundsPath.
williamr@2:         *
williamr@2:         * @return The simple sound path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& SimpleSoundsPath();
williamr@2: 
williamr@2:         // ---------------------------------------------------------------------
williamr@2:         // Paths that are not necessarily under root directories
williamr@2:         // ---------------------------------------------------------------------
williamr@2: 
williamr@2:         /**
williamr@2:         * This method returns a thumbnail images path. The thumbnail images 
williamr@2:         * directory exists under the same directory where the corresponding 
williamr@2:         * image is. Do not try to append this to a root directory.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EImagesThumbnailPath.
williamr@2:         *
williamr@2:         * @return The thumbnail images path.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& ImagesThumbnailPath();
williamr@2: 
williamr@2:         /**
williamr@2:         * This method returns the full path of the contacts folder in 
williamr@2:         * the memory card. The path also contains the drive letter. 
williamr@2:         * Do not try to append this to any root directory.
williamr@2:         * Corresponding TSystemPaths value of the returned path is EMemoryCardContactsPath.
williamr@2:         *
williamr@2:         * @return The full path of the contacts folder in the memory card.
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& MemoryCardContactsPath();
williamr@2: 
williamr@2:         /**
williamr@2:         * This method returns the requested system path.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aPath Defines the requested system path.
williamr@2:         * @return The requested system path.
williamr@2:         *
williamr@2:         * @panic EInvalidParameter Parameter aPath is invalid.
williamr@2:         *
williamr@2:         * One small sample describing the usage of the method.
williamr@2:         * @code
williamr@2:         *  #include <PathInfo.h>
williamr@2:         *
williamr@2:         *  // Get the the full path of the contacts folder in the memory card.
williamr@2:         *  TFileName path = PathInfo::GetPath( PathInfo::EMemoryCardContactsPath );
williamr@2:         *
williamr@2:         *  // 'path' contains now the full path of the contacts folder in the memory card..
williamr@2:         * @endcode
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static const TDesC& GetPath( TInt aPath );
williamr@2: 
williamr@2:         /**
williamr@2:         * This method gets the root path of the requested drive.
williamr@2:         * The root path is the path where the system paths are located.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aRootPath Stores the path, the maximum path length is KMaxPath.
williamr@2:         * @param aDrive A drive identifier specified by TDriveNumber.
williamr@2:         * @return A system wide error code.
williamr@2:         * 
williamr@2:         * One small sample describing the usage of the method.
williamr@2:         * @code
williamr@2:         *  #include <PathInfo.h>
williamr@2:         *  #include <DriveInfo.h>
williamr@2:         *
williamr@2:         *  // Get the root path of the default phone memory.
williamr@2:         *  TInt drive;
williamr@2:         *  User::LeaveIfError( DriveInfo::GetDefaultDrive(
williamr@2:         *      DriveInfo::EDefaultPhoneMemory, drive ) );
williamr@2:         *  TFileName path;
williamr@2:         *  User::LeaveIfError( PathInfo::GetRootPath( path, drive ) );
williamr@2:         *
williamr@2:         *  // 'path' contains now the default folder root path of the default phone memory.
williamr@2:         * @endcode
williamr@2:         *
williamr@2:         * @see TDriveNumber
williamr@2:         * @see KMaxPath
williamr@2:         * @see DriveInfo
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetRootPath( TDes& aRootPath, TInt aDrive );
williamr@2: 
williamr@2:         /**
williamr@2:         * This method gets the full path of the requested system path in the requested drive.
williamr@2:         * KErrNotFound is returned when the drive has no requested system path or 
williamr@2:         * the requested path cannot be added to the root path.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFullPath Stores the requested path, the maximum path length is KMaxPath.
williamr@2:         * @param aDrive A drive identifier specified by TDriveNumber.
williamr@2:         * @param aPath Defines the requested system path.
williamr@2:         * @return A system wide error codes.
williamr@2:         *
williamr@2:         * One small sample describing the usage of the method.
williamr@2:         * @code
williamr@2:         *  #include <PathInfo.h>
williamr@2:         *  #include <DriveInfo.h>
williamr@2:         *
williamr@2:         *  // Get the full path of the images folder in the default
williamr@2:         *  // phone memory drive.
williamr@2:         *  TFileName path;
williamr@2:         *  TInt drive;
williamr@2:         *  User::LeaveIfError( DriveInfo::GetDefaultDrive(
williamr@2:         *      DriveInfo::EDefaultPhoneMemory, drive ) );
williamr@2:         *  User::LeaveIfError( PathInfo::GetFullPath( path, drive, PathInfo::EImages ) );
williamr@2:         *
williamr@2:         *  // 'path' contains now the full path of the images folder in the default
williamr@2:         *  // phone memory drive.
williamr@2:         * @endcode
williamr@2:         *
williamr@2:         * @see TDriveNumber
williamr@2:         * @see KMaxPath
williamr@2:         * @see TSystemPaths
williamr@2:         * @see DriveInfo
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetFullPath( TDes& aFullPath, TInt aDrive, TInt aPath );
williamr@2: 
williamr@2:         /**
williamr@2:         * This method returns the system path type of the given path.
williamr@2:         * Thumbnail system path can exist in any folder.
williamr@2:         * Other paths must be exact system paths, not subfolders of a system path
williamr@2:         * ENotSystemPath is returned, if the path is not a system path.
williamr@2:         * The given path must have backslash ending.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFullPath A path to be type checked
williamr@2:         * @return A value specified by TSystemPaths
williamr@2:         * 
williamr@2:         * One small sample describing the usage of the method.
williamr@2:         * @code
williamr@2:         *  #include <PathInfo.h>
williamr@2:         *
williamr@2:         *  // Check the type of the system path.
williamr@2:         * _LIT( KImagesPath, "E:\\Images\\" );
williamr@2:         *  TInt type( PathInfo::PathType( KImagesPath ) );
williamr@2:         *
williamr@2:         *  // 'type' contains now the EImagesPath value.
williamr@2:         * @endcode
williamr@2:         *
williamr@2:         * @see TSystemPaths
williamr@2:         */
williamr@2:         IMPORT_C static TInt PathType( const TDesC& aFullPath );
williamr@2: 
williamr@2:         /**
williamr@2:         * This method gets the list of full system paths in the requested drive 
williamr@2:         * and leaves the returned pointer in cleanup stack.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aDrive A drive identifier specified by TDriveNumber.
williamr@2:         * @return A list of the system paths. Ownership is transferred.
williamr@2:         *
williamr@2:         * One small sample describing the usage of the method.
williamr@2:         * @code
williamr@2:         *  #include <PathInfo.h>
williamr@2:         *  #include <DriveInfo.h>
williamr@2:         *
williamr@2:         *  // Create the default path structure for default mass storage drive
williamr@2:         *  TInt drive;
williamr@2:         *  User::LeaveIfError( DriveInfo::GetDefaultDrive(
williamr@2:         *      DriveInfo::EDefaultMassStorage, drive ) );
williamr@2:         *  CDesCArray* paths = PathInfo::GetListOfPathsLC( drive );
williamr@2:         *  TInt count( paths->MdcaCount() );
williamr@2:         *  for ( TInt i( 0 ); i < count; ++i )
williamr@2:         *      {
williamr@2:         *      User::LeaveIfError( iFs.MkDirAll( paths->MdcaPoint( i ) );
williamr@2:         *      }
williamr@2:         * CleanupStack::PopAndDestroy( paths );
williamr@2:         * // The default mass storage drive contains now the default path structure
williamr@2:         * @endcode
williamr@2:         *
williamr@2:         * @see TDriveNumber
williamr@2:         * @see DriveInfo
williamr@2:         */
williamr@2:         IMPORT_C static CDesCArray* GetListOfPathsLC( TInt aDrive );
williamr@2: 
williamr@2:         /**
williamr@2:         * This method gets the list of full system paths in the requested drive.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aDrive A drive identifier specified by TDriveNumber.
williamr@2:         * @return A list of the system paths. Ownership is transferred.
williamr@2:         *
williamr@2:         * @see TDriveNumber
williamr@2:         */
williamr@2:         IMPORT_C static CDesCArray* GetListOfPathsL( TInt aDrive );
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         /**
williamr@2:         * C++ default constructor.
williamr@2:         */
williamr@2:         PathInfo();
williamr@2:     };
williamr@2: 
williamr@2: #endif      // PATH_INFO_H   
williamr@2:             
williamr@2: // End of File