Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
/*
* Copyright (c) 2002-2007 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: 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