1 driveinfo.h

     1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

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

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef DRIVE_INFO_H

    21 #define DRIVE_INFO_H

    22 

    23 //  INCLUDES

    24 #include <e32std.h>

    25 #include <f32file.h>

    26 

    27 // CLASS DECLARATION

    28 /**

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

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

    31 * used instead of the hard coded drive identifiers. 

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

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

    34 *

    35 * Usage:

    36 *

    37 * @code

    38 *  #include <DriveInfo.h>

    39 *

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

    41 *  TInt drive;

    42 *  User::LeaveIfError( DriveInfo::GetDefaultDrive(

    43 *      DriveInfo::EDefaultRemovableMassStorage, drive ) );

    44 *

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

    46 *

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

    48 *  TUint status;

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

    50 *

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

    52 *

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

    54 *  TDriveList driveList;

    55 *  TInt driveCount;

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

    57 *

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

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

    60 *

    61 *  // Access the drives stored in 'driveList'

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

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

    64 *      {

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

    66 *          {

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

    68 *          // ...

    69 *          }

    70 *      }

    71 *

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

    73 *  DriveInfo::TDriveArray driveArray;

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

    75 *

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

    77 *

    78 *  // Access the drives stored in 'driveArray'

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

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

    81 *      {

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

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

    84 *      // ...

    85 *      }

    86 *

    87 * @endcode

    88 *

    89 * Error handling:

    90 *

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

    92 *

    93 *  @lib PlatformEnv.dll

    94 *  @since 3.2

    95 */

    96 

    97 NONSHARABLE_CLASS(DriveInfo)

    98     {

    99     public:

   100         /**

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

   102          * @since 3.2

   103          */

   104         enum TDefaultDrives

   105             {

   106             /** To get the default ROM drive.

   107             */

   108             EDefaultRom = 0,

   109 

   110             /** To get the default RAM drive.

   111             */

   112             EDefaultRam,

   113 

   114             /** To get the default system drive.

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

   116             */

   117             EDefaultSystem,

   118 

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

   120             */

   121             EDefaultPhoneMemory,

   122 

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

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

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

   126             */

   127             EDefaultMassStorage,

   128 

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

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

   131             */

   132             EDefaultRemovableMassStorage

   133             };

   134 

   135        /**

   136         * This method gets the default drive of requested type.

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

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

   139         * EDefaultRemovableMassStorage is requested.

   140         *

   141         * @since 3.2

   142         * @param aDefaultDrive A default drive identifier specified by TDefaultDrives

   143         * @param aDrive Stores a drive identifier specified by TDriveNumber

   144         * @return A system wide error code.

   145         *

   146         * @see TDefaultDrives

   147         * @see TDriveNumber

   148         */

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

   150 

   151        /**

   152         * This method gets the default drive of requested type.

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

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

   155         * EDefaultRemovableMassStorage is requested.

   156         *

   157         * @since 3.2

   158         * @param aDefaultDrive A default drive identifier specified by TDefaultDrives

   159         * @param aDriveLetter Stores a drive letter

   160         * @return A system wide error code.

   161         *

   162         * @see TDefaultDrives

   163         */

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

   165 

   166         /**

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

   168          * @since 3.2

   169          */

   170         enum TStatus

   171             {

   172             /** To indicate that the drive is internal and 

   173             * cannot be physically removed.

   174             */

   175             EDriveInternal = 0x1,

   176 

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

   178             */

   179             EDriveRemovable = 0x2,

   180 

   181             /** To indicate that the drive is remote.

   182             */

   183             EDriveRemote = 0x4,

   184 

   185             /** To indicate that the drive is present.

   186             */

   187             EDrivePresent = 0x8,

   188 

   189             /** To indicate that the drive is locked.

   190             */

   191             EDriveLocked = 0x10,

   192 

   193             /** To indicate that the drive is corrupt.

   194             */

   195             EDriveCorrupt = 0x20,

   196 

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

   198             * reserved for some exclusive usage.

   199             */

   200             EDriveInUse = 0x40,

   201 

   202             /** To indicate that the drive is readonly.

   203             */

   204             EDriveReadOnly = 0x80,

   205 

   206             /** To indicate that the drive is substed.

   207             */

   208             EDriveSubsted = 0x100,

   209 

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

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

   212             */

   213             EDriveUserVisible = 0x200,

   214 

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

   216             * can be mounted from PC or from other devices.

   217             */

   218             EDriveExternallyMountable = 0x400,

   219 

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

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

   222             */

   223             EDriveSwEjectable = 0x800,

   224 

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

   226             */

   227             EDriveRom = 0x1000,

   228 

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

   230             */

   231             EDriveRam = 0x2000,

   232 

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

   234             */

   235             EDriveFormatted = 0x4000,

   236 

   237             /** To indicate that the drive is formattable.

   238             */

   239             EDriveFormattable = 0x8000,

   240 

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

   242             */

   243             EDriveLockable = 0x10000,

   244 

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

   246             */

   247             EDriveHasPassword = 0x20000

   248 

   249             };

   250 

   251        /**

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

   253         *

   254         * @since 3.2

   255         * @param aFs An opened file server session

   256         * @param aDrive A drive identifier specified by TDriveNumber

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

   258         * @return A system wide error code.

   259         *

   260         * @see RFs

   261         * @see TDriveNumber

   262         * @see TStatus

   263         */

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

   265 

   266        /**

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

   268         *

   269         * @since 3.2

   270         * @param aFs An opened file server session

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

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

   273         * @return A system wide error code.

   274         *

   275         * @see RFs

   276         * @see TDriveList

   277         */

   278         IMPORT_C static TInt GetUserVisibleDrives(

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

   280 

   281        /**

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

   283         * attributes.

   284         *

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

   286         *

   287         * @since 3.2

   288         * @param aFs An opened file server session

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

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

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

   292         * @return A system wide error code.

   293         *

   294         * @see RFs

   295         * @see TDriveList

   296         */

   297         IMPORT_C static TInt GetUserVisibleDrives(

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

   299 

   300        /**

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

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

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

   304         *

   305         * @since 3.2

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

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

   308         *

   309         * @see TDriveList

   310         */

   311         IMPORT_C static TInt StripUserHiddenDrives( TDriveList& aDriveList );

   312 

   313        /**

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

   315         *

   316         * @since 3.2

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

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

   319         *

   320         * @see TDriveList

   321         */

   322         IMPORT_C static TInt DriveCount( const TDriveList& aDriveList );

   323 

   324         /**

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

   326          * @since S60 5.0

   327          */

   328         class TDriveArray

   329             {

   330             public: // Constructors

   331                 inline TDriveArray();

   332                 inline TDriveArray( const TDriveList& aDriveList );

   333 

   334             public:

   335                 /**

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

   337                  *

   338                  * @since 3.2

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

   340                  *

   341                  * @see TDriveList

   342                  */

   343                 IMPORT_C void Set( const TDriveList& aDriveList );

   344 

   345                 /**

   346                  * This method resets the array.

   347                  *

   348                  * @since 3.2

   349                  */

   350                 inline void Reset();

   351 

   352                 /**

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

   354                  *

   355                  * @since 3.2

   356                  * @return A number of drives in the array.

   357                  */

   358                 inline TInt Count() const;

   359 

   360                 /**

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

   362                  *

   363                  * @since 3.2

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

   365                  * @return A drive identifier specified by TDriveNumber.

   366                  *

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

   368                  * the number of drives in the array

   369                  *

   370                  * @see TDriveNumber

   371                  */

   372                 inline TDriveNumber operator[]( TInt aIndex ) const;

   373 

   374                 /**

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

   376                  *

   377                  * @since 3.2

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

   379                  * @return A drive letter.

   380                  *

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

   382                  * the number of drives in the array

   383                  */

   384                 IMPORT_C TChar LetterAt( TInt aIndex ) const;

   385 

   386             private:

   387                 TBuf8< KMaxDrives > iArray;

   388             };

   389 

   390        /**

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

   392         *

   393         * @since 3.2

   394         * @param aFs An opened file server session

   395         * @param aDriveArray Stores the user visible drives

   396         * @return A system wide error code.

   397         *

   398         * @see RFs

   399         * @see TDriveArray

   400         */

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

   402 

   403        /**

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

   405         * attributes.

   406         *

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

   408         *

   409         * @since 3.2

   410         * @param aFs An opened file server session

   411         * @param aDriveArray Stores the user visible drives

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

   413         * @return A system wide error code.

   414         *

   415         * @see RFs

   416         * @see TDriveArray

   417         */

   418         IMPORT_C static TInt GetUserVisibleDrives(

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

   420 

   421     private:

   422 

   423         /**

   424         * C++ default constructor.

   425         */

   426         DriveInfo();

   427     };

   428 

   429 #include "driveinfo.inl"

   430 

   431 #endif      // DRIVE_INFO_H   

   432 

   433 // End of File