williamr@2: /*
williamr@2: * Copyright (c) 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@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 the drive information of the system.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef DRIVE_INFO_H
williamr@2: #define DRIVE_INFO_H
williamr@2: 
williamr@2: //  INCLUDES
williamr@2: #include <e32std.h>
williamr@2: #include <f32file.h>
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: /**
williamr@2: * Class holds the drive information of the system. Platform Environment API provides 
williamr@2: * interface for quering the drive information of the system. Methods provided by the API should be
williamr@2: * used instead of the hard coded drive identifiers. 
williamr@2: * The API consist of the DriveInfo class, PathInfo class and system paths are defined
williamr@2: * in PathConfiguration.hrh. The PathInfo class is defined in PathInfo.h.
williamr@2: *
williamr@2: * Usage:
williamr@2: *
williamr@2: * @code
williamr@2: *  #include <DriveInfo.h>
williamr@2: *
williamr@2: *  // Get the drive identifier of the default removable mass storage.
williamr@2: *  TInt drive;
williamr@2: *  User::LeaveIfError( DriveInfo::GetDefaultDrive(
williamr@2: *      DriveInfo::EDefaultRemovableMassStorage, drive ) );
williamr@2: *
williamr@2: *  // 'drive' contains now the drive identifier of the default removable mass storage.
williamr@2: *
williamr@2: *  // Get the drive status of the default removable mass storage.
williamr@2: *  TUint status;
williamr@2: *  User::LeaveIfError( DriveInfo::GetDriveStatus( fs, drive, status ) );
williamr@2: *
williamr@2: *  // 'status' contains now the drive status of the default removable mass storage.
williamr@2: *
williamr@2: *  // Get all drives that are visible to the user in TDriveList.
williamr@2: *  TDriveList driveList;
williamr@2: *  TInt driveCount;
williamr@2: *  User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveList, driveCount ) );
williamr@2: *
williamr@2: *  // 'driveList' contains now the user visible drives.
williamr@2: *  // 'driveCount'contains now the drive count i.e. number of non zero items in driveList.
williamr@2: *
williamr@2: *  // Access the drives stored in 'driveList'
williamr@2: *  TInt driveListLen( driveList.Length() ); // The length of 'driveList'
williamr@2: *  for( TInt i( 0 ); i < driveListLen; ++i )
williamr@2: *      {
williamr@2: *      if ( driveList[ i ] ) // Non zero items are valid drives
williamr@2: *          {
williamr@2: *          // 'i' contains drive identifier specified by TDriveNumber
williamr@2: *          // ...
williamr@2: *          }
williamr@2: *      }
williamr@2: *
williamr@2: *  // Get all drives that are visible to the user in DriveInfo::TDriveArray.
williamr@2: *  DriveInfo::TDriveArray driveArray;
williamr@2: *  User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveArray ) );
williamr@2: *
williamr@2: *  // 'driveArray' contains now the user visible drives.
williamr@2: *
williamr@2: *  // Access the drives stored in 'driveArray'
williamr@2: *  driveCount = driveArray.Count() ); // The number of drives stored in 'driveArray'
williamr@2: *  for( TInt i( 0 ); i < driveCount; ++i )
williamr@2: *      {
williamr@2: *      TDriveNumber drive( driveArray[ i ] ); // The drive identifier at position 'i'
williamr@2: *      TChar driveLetter( driveArray.LetterAt( i ) ); // The drive letter at position 'i'
williamr@2: *      // ...
williamr@2: *      }
williamr@2: *
williamr@2: * @endcode
williamr@2: *
williamr@2: * Error handling:
williamr@2: *
williamr@2: * System wide error codes are returned to indicate errors in methods that can fail.
williamr@2: *
williamr@2: *  @lib PlatformEnv.dll
williamr@2: *  @since 3.2
williamr@2: */
williamr@2: 
williamr@2: NONSHARABLE_CLASS(DriveInfo)
williamr@2:     {
williamr@2:     public:
williamr@2:         /**
williamr@2:          * Enumeration Default Drives to be used with GetDefaultDrive() method.
williamr@2:          * @since 3.2
williamr@2:          */
williamr@2:         enum TDefaultDrives
williamr@2:             {
williamr@2:             /** To get the default ROM drive.
williamr@2:             */
williamr@2:             EDefaultRom = 0,
williamr@2: 
williamr@2:             /** To get the default RAM drive.
williamr@2:             */
williamr@2:             EDefaultRam,
williamr@2: 
williamr@2:             /** To get the default system drive.
williamr@2:             * The default system drive is the preferred drive for system specific functionalities.
williamr@2:             */
williamr@2:             EDefaultSystem,
williamr@2: 
williamr@2:             /** To get the default phone memory like FLASH memory, internal memory card, hard drive etc.
williamr@2:             */
williamr@2:             EDefaultPhoneMemory,
williamr@2: 
williamr@2:             /** To get the default mass storage like any kind of memory card, hard drive, USB stick etc.
williamr@2:             * This definition should be always used, unless a removable mass storage is explicitly required.
williamr@2:             * The default mass storage is the preferred drive for a large amount of user files.
williamr@2:             */
williamr@2:             EDefaultMassStorage,
williamr@2: 
williamr@2:             /** To get the default removable mass storage like memory card, USB stick etc.
williamr@2:             * This definition should be used only when explicitly removable mass storage is required.
williamr@2:             */
williamr@2:             EDefaultRemovableMassStorage
williamr@2:             };
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets the default drive of requested type.
williamr@2:         * If the device does not have the requested default drive, then KErrNotSupported is returned.
williamr@2:         * This happens for example if device supports only internal drives and
williamr@2:         * EDefaultRemovableMassStorage is requested.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aDefaultDrive A default drive identifier specified by TDefaultDrives
williamr@2:         * @param aDrive Stores a drive identifier specified by TDriveNumber
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see TDefaultDrives
williamr@2:         * @see TDriveNumber
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TInt& aDrive );
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets the default drive of requested type.
williamr@2:         * If the device does not have the requested default drive, then KErrNotSupported is returned.
williamr@2:         * This happens for example if device supports only internal drives and
williamr@2:         * EDefaultRemovableMassStorage is requested.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aDefaultDrive A default drive identifier specified by TDefaultDrives
williamr@2:         * @param aDriveLetter Stores a drive letter
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see TDefaultDrives
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TChar& aDriveLetter );
williamr@2: 
williamr@2:         /**
williamr@2:          * Enumeration bit mask Status used by GetDriveStatus() method.
williamr@2:          * @since 3.2
williamr@2:          */
williamr@2:         enum TStatus
williamr@2:             {
williamr@2:             /** To indicate that the drive is internal and 
williamr@2:             * cannot be physically removed.
williamr@2:             */
williamr@2:             EDriveInternal = 0x1,
williamr@2: 
williamr@2:             /** To indicate that the drive is physically removable.
williamr@2:             */
williamr@2:             EDriveRemovable = 0x2,
williamr@2: 
williamr@2:             /** To indicate that the drive is remote.
williamr@2:             */
williamr@2:             EDriveRemote = 0x4,
williamr@2: 
williamr@2:             /** To indicate that the drive is present.
williamr@2:             */
williamr@2:             EDrivePresent = 0x8,
williamr@2: 
williamr@2:             /** To indicate that the drive is locked.
williamr@2:             */
williamr@2:             EDriveLocked = 0x10,
williamr@2: 
williamr@2:             /** To indicate that the drive is corrupt.
williamr@2:             */
williamr@2:             EDriveCorrupt = 0x20,
williamr@2: 
williamr@2:             /** To indicate that the drive is in use i.e.
williamr@2:             * reserved for some exclusive usage.
williamr@2:             */
williamr@2:             EDriveInUse = 0x40,
williamr@2: 
williamr@2:             /** To indicate that the drive is readonly.
williamr@2:             */
williamr@2:             EDriveReadOnly = 0x80,
williamr@2: 
williamr@2:             /** To indicate that the drive is substed.
williamr@2:             */
williamr@2:             EDriveSubsted = 0x100,
williamr@2: 
williamr@2:             /** To indicate that the drive is user visible.
williamr@2:             * The UI is allowed to show the drive to the user.
williamr@2:             */
williamr@2:             EDriveUserVisible = 0x200,
williamr@2: 
williamr@2:             /** To indicate that the drive is externally mountable i.e.
williamr@2:             * can be mounted from PC or from other devices.
williamr@2:             */
williamr@2:             EDriveExternallyMountable = 0x400,
williamr@2: 
williamr@2:             /** To indicate that the drive is software ejectable.
williamr@2:             * The user can select software based eject from the UI for this drive.
williamr@2:             */
williamr@2:             EDriveSwEjectable = 0x800,
williamr@2: 
williamr@2:             /** To indicate that the drive is ROM drive.
williamr@2:             */
williamr@2:             EDriveRom = 0x1000,
williamr@2: 
williamr@2:             /** To indicate that the drive is RAM drive.
williamr@2:             */
williamr@2:             EDriveRam = 0x2000,
williamr@2: 
williamr@2:             /** To indicate that the drive has been formatted.
williamr@2:             */
williamr@2:             EDriveFormatted = 0x4000,
williamr@2: 
williamr@2:             /** To indicate that the drive is formattable.
williamr@2:             */
williamr@2:             EDriveFormattable = 0x8000,
williamr@2: 
williamr@2:             /** To indicate that the drive is lockable i.e. password can be set.
williamr@2:             */
williamr@2:             EDriveLockable = 0x10000,
williamr@2: 
williamr@2:             /** To indicate that the drive is password protected.
williamr@2:             */
williamr@2:             EDriveHasPassword = 0x20000
williamr@2: 
williamr@2:             };
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets the drive status, a bit mask specified by TStatus.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFs An opened file server session
williamr@2:         * @param aDrive A drive identifier specified by TDriveNumber
williamr@2:         * @param aStatus Stores the drive status bit mask specified by TStatus
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see RFs
williamr@2:         * @see TDriveNumber
williamr@2:         * @see TStatus
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetDriveStatus( RFs& aFs, TInt aDrive, TUint& aStatus );
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets all the drives that are visible to the user.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFs An opened file server session
williamr@2:         * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.
williamr@2:         * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see RFs
williamr@2:         * @see TDriveList
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetUserVisibleDrives(
williamr@2:             RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount );
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets the user visible drives with specified file server drive 
williamr@2:         * attributes.
williamr@2:         *
williamr@2:         * Note that file server drive attributes are not equal with TStatus definitions.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFs An opened file server session
williamr@2:         * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.
williamr@2:         * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.
williamr@2:         * @param aFlags The mask flags specified for RFs::DriveList() method.
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see RFs
williamr@2:         * @see TDriveList
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetUserVisibleDrives(
williamr@2:             RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount, TUint aFlags );
williamr@2: 
williamr@2:        /**
williamr@2:         * This method methods checks the given drive list and removes the drives hidden from the user.
williamr@2:         * It is intended to be used with the drive lists that are not read by using GetUserVisibleDrives() method
williamr@2:         * e.g. the drive list has been got as a parameter elsewhere.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aDriveList A drive list where to remove the drives hidden from the user.
williamr@2:         * @return A drive count i.e. number of non zero items in the given drive list after removal.
williamr@2:         *
williamr@2:         * @see TDriveList
williamr@2:         */
williamr@2:         IMPORT_C static TInt StripUserHiddenDrives( TDriveList& aDriveList );
williamr@2: 
williamr@2:        /**
williamr@2:         * This method returns the number of drives in the given drive list.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aDriveList A drive list where to count the number of drives.
williamr@2:         * @return A drive count i.e. number of non zero items in the given drive list.
williamr@2:         *
williamr@2:         * @see TDriveList
williamr@2:         */
williamr@2:         IMPORT_C static TInt DriveCount( const TDriveList& aDriveList );
williamr@2: 
williamr@2:         /**
williamr@2:          * Class TDriveArray provides easy-to-use access to drive identifiers.
williamr@2:          * @since S60 5.0
williamr@2:          */
williamr@2:         class TDriveArray
williamr@2:             {
williamr@2:             public: // Constructors
williamr@2:                 inline TDriveArray();
williamr@2:                 inline TDriveArray( const TDriveList& aDriveList );
williamr@2: 
williamr@2:             public:
williamr@2:                 /**
williamr@2:                  * This method sets the drive array data from given drive list.
williamr@2:                  *
williamr@2:                  * @since 3.2
williamr@2:                  * @param aDriveList A drive list where to set the data from.
williamr@2:                  *
williamr@2:                  * @see TDriveList
williamr@2:                  */
williamr@2:                 IMPORT_C void Set( const TDriveList& aDriveList );
williamr@2: 
williamr@2:                 /**
williamr@2:                  * This method resets the array.
williamr@2:                  *
williamr@2:                  * @since 3.2
williamr@2:                  */
williamr@2:                 inline void Reset();
williamr@2: 
williamr@2:                 /**
williamr@2:                  * This method gets the number of drives in the array.
williamr@2:                  *
williamr@2:                  * @since 3.2
williamr@2:                  * @return A number of drives in the array.
williamr@2:                  */
williamr@2:                 inline TInt Count() const;
williamr@2: 
williamr@2:                 /**
williamr@2:                  * This method gets the drive identifier at given index within the array.
williamr@2:                  *
williamr@2:                  * @since 3.2
williamr@2:                  * @param aIndex The position of drive within the array.
williamr@2:                  * @return A drive identifier specified by TDriveNumber.
williamr@2:                  *
williamr@2:                  * @panic USER 21 if aIndex is negative or is greater than 
williamr@2:                  * the number of drives in the array
williamr@2:                  *
williamr@2:                  * @see TDriveNumber
williamr@2:                  */
williamr@2:                 inline TDriveNumber operator[]( TInt aIndex ) const;
williamr@2: 
williamr@2:                 /**
williamr@2:                  * This method gets the drive letter at given index within the array.
williamr@2:                  *
williamr@2:                  * @since 3.2
williamr@2:                  * @param aIndex The position of drive within the array.
williamr@2:                  * @return A drive letter.
williamr@2:                  *
williamr@2:                  * @panic USER 21 if aIndex is negative or is greater than 
williamr@2:                  * the number of drives in the array
williamr@2:                  */
williamr@2:                 IMPORT_C TChar LetterAt( TInt aIndex ) const;
williamr@2: 
williamr@2:             private:
williamr@2:                 TBuf8< KMaxDrives > iArray;
williamr@2:             };
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets all the drives that are visible to the user.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFs An opened file server session
williamr@2:         * @param aDriveArray Stores the user visible drives
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see RFs
williamr@2:         * @see TDriveArray
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetUserVisibleDrives( RFs& aFs, TDriveArray& aDriveArray );
williamr@2: 
williamr@2:        /**
williamr@2:         * This method gets the user visible drives with specified file server drive 
williamr@2:         * attributes.
williamr@2:         *
williamr@2:         * Note that file server drive attributes are not equal with TStatus definitions.
williamr@2:         *
williamr@2:         * @since 3.2
williamr@2:         * @param aFs An opened file server session
williamr@2:         * @param aDriveArray Stores the user visible drives
williamr@2:         * @param aFlags The mask flags specified for RFs::DriveList() method.
williamr@2:         * @return A system wide error code.
williamr@2:         *
williamr@2:         * @see RFs
williamr@2:         * @see TDriveArray
williamr@2:         */
williamr@2:         IMPORT_C static TInt GetUserVisibleDrives(
williamr@2:             RFs& aFs, TDriveArray& aDriveArray, TUint aFlags );
williamr@2: 
williamr@2:     private:
williamr@2: 
williamr@2:         /**
williamr@2:         * C++ default constructor.
williamr@2:         */
williamr@2:         DriveInfo();
williamr@2:     };
williamr@2: 
williamr@2: #include "driveinfo.inl"
williamr@2: 
williamr@2: #endif      // DRIVE_INFO_H   
williamr@2: 
williamr@2: // End of File