--- a/epoc32/include/driveinfo.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/driveinfo.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,433 @@
-driveinfo.h
+/*
+* 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