/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* 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

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Interface for quering the drive information of the system.

*

*/

#ifndef DRIVE_INFO_H

#define DRIVE_INFO_H

//  INCLUDES

#include <e32std.h>

#include <f32file.h>

// CLASS DECLARATION

/**

* Class holds the drive information of the system. Platform Environment API provides 

* interface for quering the drive information of the system. Methods provided by the API should be

* used instead of the hard coded drive identifiers. 

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

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

*

* Usage:

*

* @code

*  #include <DriveInfo.h>

*

*  // Get the drive identifier of the default removable mass storage.

*  TInt drive;

*  User::LeaveIfError( DriveInfo::GetDefaultDrive(

*      DriveInfo::EDefaultRemovableMassStorage, drive ) );

*

*  // 'drive' contains now the drive identifier of the default removable mass storage.

*

*  // Get the drive status of the default removable mass storage.

*  TUint status;

*  User::LeaveIfError( DriveInfo::GetDriveStatus( fs, drive, status ) );

*

*  // 'status' contains now the drive status of the default removable mass storage.

*

*  // Get all drives that are visible to the user in TDriveList.

*  TDriveList driveList;

*  TInt driveCount;

*  User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveList, driveCount ) );

*

*  // 'driveList' contains now the user visible drives.

*  // 'driveCount'contains now the drive count i.e. number of non zero items in driveList.

*

*  // Access the drives stored in 'driveList'

*  TInt driveListLen( driveList.Length() ); // The length of 'driveList'

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

*      {

*      if ( driveList[ i ] ) // Non zero items are valid drives

*          {

*          // 'i' contains drive identifier specified by TDriveNumber

*          // ...

*          }

*      }

*

*  // Get all drives that are visible to the user in DriveInfo::TDriveArray.

*  DriveInfo::TDriveArray driveArray;

*  User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveArray ) );

*

*  // 'driveArray' contains now the user visible drives.

*

*  // Access the drives stored in 'driveArray'

*  driveCount = driveArray.Count() ); // The number of drives stored in 'driveArray'

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

*      {

*      TDriveNumber drive( driveArray[ i ] ); // The drive identifier at position 'i'

*      TChar driveLetter( driveArray.LetterAt( i ) ); // The drive letter at position 'i'

*      // ...

*      }

*

* @endcode

*

* Error handling:

*

* System wide error codes are returned to indicate errors in methods that can fail.

*

*  @lib PlatformEnv.dll

*  @since 3.2

*/

NONSHARABLE_CLASS(DriveInfo)

    {

    public:

        /**

         * Enumeration Default Drives to be used with GetDefaultDrive() method.

         * @since 3.2

         */

        enum TDefaultDrives

            {

            /** To get the default ROM drive.

            */

            EDefaultRom = 0,

            /** To get the default RAM drive.

            */

            EDefaultRam,

            /** To get the default system drive.

            * The default system drive is the preferred drive for system specific functionalities.

            */

            EDefaultSystem,

            /** To get the default phone memory like FLASH memory, internal memory card, hard drive etc.

            */

            EDefaultPhoneMemory,

            /** To get the default mass storage like any kind of memory card, hard drive, USB stick etc.

            * This definition should be always used, unless a removable mass storage is explicitly required.

            * The default mass storage is the preferred drive for a large amount of user files.

            */

            EDefaultMassStorage,

            /** To get the default removable mass storage like memory card, USB stick etc.

            * This definition should be used only when explicitly removable mass storage is required.

            */

            EDefaultRemovableMassStorage

            };

       /**

        * This method gets the default drive of requested type.

        * If the device does not have the requested default drive, then KErrNotSupported is returned.

        * This happens for example if device supports only internal drives and

        * EDefaultRemovableMassStorage is requested.

        *

        * @since 3.2

        * @param aDefaultDrive A default drive identifier specified by TDefaultDrives

        * @param aDrive Stores a drive identifier specified by TDriveNumber

        * @return A system wide error code.

        *

        * @see TDefaultDrives

        * @see TDriveNumber

        */

        IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TInt& aDrive );

       /**

        * This method gets the default drive of requested type.

        * If the device does not have the requested default drive, then KErrNotSupported is returned.

        * This happens for example if device supports only internal drives and

        * EDefaultRemovableMassStorage is requested.

        *

        * @since 3.2

        * @param aDefaultDrive A default drive identifier specified by TDefaultDrives

        * @param aDriveLetter Stores a drive letter

        * @return A system wide error code.

        *

        * @see TDefaultDrives

        */

        IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TChar& aDriveLetter );

        /**

         * Enumeration bit mask Status used by GetDriveStatus() method.

         * @since 3.2

         */

        enum TStatus

            {

            /** To indicate that the drive is internal and 

            * cannot be physically removed.

            */

            EDriveInternal = 0x1,

            /** To indicate that the drive is physically removable.

            */

            EDriveRemovable = 0x2,

            /** To indicate that the drive is remote.

            */

            EDriveRemote = 0x4,

            /** To indicate that the drive is present.

            */

            EDrivePresent = 0x8,

            /** To indicate that the drive is locked.

            */

            EDriveLocked = 0x10,

            /** To indicate that the drive is corrupt.

            */

            EDriveCorrupt = 0x20,

            /** To indicate that the drive is in use i.e.

            * reserved for some exclusive usage.

            */

            EDriveInUse = 0x40,

            /** To indicate that the drive is readonly.

            */

            EDriveReadOnly = 0x80,

            /** To indicate that the drive is substed.

            */

            EDriveSubsted = 0x100,

            /** To indicate that the drive is user visible.

            * The UI is allowed to show the drive to the user.

            */

            EDriveUserVisible = 0x200,

            /** To indicate that the drive is externally mountable i.e.

            * can be mounted from PC or from other devices.

            */

            EDriveExternallyMountable = 0x400,

            /** To indicate that the drive is software ejectable.

            * The user can select software based eject from the UI for this drive.

            */

            EDriveSwEjectable = 0x800,

            /** To indicate that the drive is ROM drive.

            */

            EDriveRom = 0x1000,

            /** To indicate that the drive is RAM drive.

            */

            EDriveRam = 0x2000,

            /** To indicate that the drive has been formatted.

            */

            EDriveFormatted = 0x4000,

            /** To indicate that the drive is formattable.

            */

            EDriveFormattable = 0x8000,

            /** To indicate that the drive is lockable i.e. password can be set.

            */

            EDriveLockable = 0x10000,

            /** To indicate that the drive is password protected.

            */

            EDriveHasPassword = 0x20000

            };

       /**

        * This method gets the drive status, a bit mask specified by TStatus.

        *

        * @since 3.2

        * @param aFs An opened file server session

        * @param aDrive A drive identifier specified by TDriveNumber

        * @param aStatus Stores the drive status bit mask specified by TStatus

        * @return A system wide error code.

        *

        * @see RFs

        * @see TDriveNumber

        * @see TStatus

        */

        IMPORT_C static TInt GetDriveStatus( RFs& aFs, TInt aDrive, TUint& aStatus );

       /**

        * This method gets all the drives that are visible to the user.

        *

        * @since 3.2

        * @param aFs An opened file server session

        * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.

        * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.

        * @return A system wide error code.

        *

        * @see RFs

        * @see TDriveList

        */

        IMPORT_C static TInt GetUserVisibleDrives(

            RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount );

       /**

        * This method gets the user visible drives with specified file server drive 

        * attributes.

        *

        * Note that file server drive attributes are not equal with TStatus definitions.

        *

        * @since 3.2

        * @param aFs An opened file server session

        * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.

        * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.

        * @param aFlags The mask flags specified for RFs::DriveList() method.

        * @return A system wide error code.

        *

        * @see RFs

        * @see TDriveList

        */

        IMPORT_C static TInt GetUserVisibleDrives(

            RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount, TUint aFlags );

       /**

        * This method methods checks the given drive list and removes the drives hidden from the user.

        * It is intended to be used with the drive lists that are not read by using GetUserVisibleDrives() method

        * e.g. the drive list has been got as a parameter elsewhere.

        *

        * @since 3.2

        * @param aDriveList A drive list where to remove the drives hidden from the user.

        * @return A drive count i.e. number of non zero items in the given drive list after removal.

        *

        * @see TDriveList

        */

        IMPORT_C static TInt StripUserHiddenDrives( TDriveList& aDriveList );

       /**

        * This method returns the number of drives in the given drive list.

        *

        * @since 3.2

        * @param aDriveList A drive list where to count the number of drives.

        * @return A drive count i.e. number of non zero items in the given drive list.

        *

        * @see TDriveList

        */

        IMPORT_C static TInt DriveCount( const TDriveList& aDriveList );

        /**

         * Class TDriveArray provides easy-to-use access to drive identifiers.

         * @since S60 5.0

         */

        class TDriveArray

            {

            public: // Constructors

                inline TDriveArray();

                inline TDriveArray( const TDriveList& aDriveList );

            public:

                /**

                 * This method sets the drive array data from given drive list.

                 *

                 * @since 3.2

                 * @param aDriveList A drive list where to set the data from.

                 *

                 * @see TDriveList

                 */

                IMPORT_C void Set( const TDriveList& aDriveList );

                /**

                 * This method resets the array.

                 *

                 * @since 3.2

                 */

                inline void Reset();

                /**

                 * This method gets the number of drives in the array.

                 *

                 * @since 3.2

                 * @return A number of drives in the array.

                 */

                inline TInt Count() const;

                /**

                 * This method gets the drive identifier at given index within the array.

                 *

                 * @since 3.2

                 * @param aIndex The position of drive within the array.

                 * @return A drive identifier specified by TDriveNumber.

                 *

                 * @panic USER 21 if aIndex is negative or is greater than 

                 * the number of drives in the array

                 *

                 * @see TDriveNumber

                 */

                inline TDriveNumber operator[]( TInt aIndex ) const;

                /**

                 * This method gets the drive letter at given index within the array.

                 *

                 * @since 3.2

                 * @param aIndex The position of drive within the array.

                 * @return A drive letter.

                 *

                 * @panic USER 21 if aIndex is negative or is greater than 

                 * the number of drives in the array

                 */

                IMPORT_C TChar LetterAt( TInt aIndex ) const;

            private:

                TBuf8< KMaxDrives > iArray;

            };

       /**

        * This method gets all the drives that are visible to the user.

        *

        * @since 3.2

        * @param aFs An opened file server session

        * @param aDriveArray Stores the user visible drives

        * @return A system wide error code.

        *

        * @see RFs

        * @see TDriveArray

        */

        IMPORT_C static TInt GetUserVisibleDrives( RFs& aFs, TDriveArray& aDriveArray );

       /**

        * This method gets the user visible drives with specified file server drive 

        * attributes.

        *

        * Note that file server drive attributes are not equal with TStatus definitions.

        *

        * @since 3.2

        * @param aFs An opened file server session

        * @param aDriveArray Stores the user visible drives

        * @param aFlags The mask flags specified for RFs::DriveList() method.

        * @return A system wide error code.

        *

        * @see RFs

        * @see TDriveArray

        */

        IMPORT_C static TInt GetUserVisibleDrives(

            RFs& aFs, TDriveArray& aDriveArray, TUint aFlags );

    private:

        /**

        * C++ default constructor.

        */

        DriveInfo();

    };

#include "driveinfo.inl"

#endif      // DRIVE_INFO_H   

// End of File