epoc32/include/driveinfo.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
/*
williamr@2
     2
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2
     3
* All rights reserved.
williamr@2
     4
* This component and the accompanying materials are made available
williamr@2
     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
williamr@2
     6
* which accompanies this distribution, and is available
williamr@2
     7
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     8
*
williamr@2
     9
* Initial Contributors:
williamr@2
    10
* Nokia Corporation - initial contribution.
williamr@2
    11
*
williamr@2
    12
* Contributors:
williamr@2
    13
*
williamr@2
    14
* Description:  Interface for quering the drive information of the system.
williamr@2
    15
*
williamr@2
    16
*/
williamr@2
    17
williamr@2
    18
williamr@2
    19
williamr@2
    20
#ifndef DRIVE_INFO_H
williamr@2
    21
#define DRIVE_INFO_H
williamr@2
    22
williamr@2
    23
//  INCLUDES
williamr@2
    24
#include <e32std.h>
williamr@2
    25
#include <f32file.h>
williamr@2
    26
williamr@2
    27
// CLASS DECLARATION
williamr@2
    28
/**
williamr@2
    29
* Class holds the drive information of the system. Platform Environment API provides 
williamr@2
    30
* interface for quering the drive information of the system. Methods provided by the API should be
williamr@2
    31
* used instead of the hard coded drive identifiers. 
williamr@2
    32
* The API consist of the DriveInfo class, PathInfo class and system paths are defined
williamr@2
    33
* in PathConfiguration.hrh. The PathInfo class is defined in PathInfo.h.
williamr@2
    34
*
williamr@2
    35
* Usage:
williamr@2
    36
*
williamr@2
    37
* @code
williamr@2
    38
*  #include <DriveInfo.h>
williamr@2
    39
*
williamr@2
    40
*  // Get the drive identifier of the default removable mass storage.
williamr@2
    41
*  TInt drive;
williamr@2
    42
*  User::LeaveIfError( DriveInfo::GetDefaultDrive(
williamr@2
    43
*      DriveInfo::EDefaultRemovableMassStorage, drive ) );
williamr@2
    44
*
williamr@2
    45
*  // 'drive' contains now the drive identifier of the default removable mass storage.
williamr@2
    46
*
williamr@2
    47
*  // Get the drive status of the default removable mass storage.
williamr@2
    48
*  TUint status;
williamr@2
    49
*  User::LeaveIfError( DriveInfo::GetDriveStatus( fs, drive, status ) );
williamr@2
    50
*
williamr@2
    51
*  // 'status' contains now the drive status of the default removable mass storage.
williamr@2
    52
*
williamr@2
    53
*  // Get all drives that are visible to the user in TDriveList.
williamr@2
    54
*  TDriveList driveList;
williamr@2
    55
*  TInt driveCount;
williamr@2
    56
*  User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveList, driveCount ) );
williamr@2
    57
*
williamr@2
    58
*  // 'driveList' contains now the user visible drives.
williamr@2
    59
*  // 'driveCount'contains now the drive count i.e. number of non zero items in driveList.
williamr@2
    60
*
williamr@2
    61
*  // Access the drives stored in 'driveList'
williamr@2
    62
*  TInt driveListLen( driveList.Length() ); // The length of 'driveList'
williamr@2
    63
*  for( TInt i( 0 ); i < driveListLen; ++i )
williamr@2
    64
*      {
williamr@2
    65
*      if ( driveList[ i ] ) // Non zero items are valid drives
williamr@2
    66
*          {
williamr@2
    67
*          // 'i' contains drive identifier specified by TDriveNumber
williamr@2
    68
*          // ...
williamr@2
    69
*          }
williamr@2
    70
*      }
williamr@2
    71
*
williamr@2
    72
*  // Get all drives that are visible to the user in DriveInfo::TDriveArray.
williamr@2
    73
*  DriveInfo::TDriveArray driveArray;
williamr@2
    74
*  User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveArray ) );
williamr@2
    75
*
williamr@2
    76
*  // 'driveArray' contains now the user visible drives.
williamr@2
    77
*
williamr@2
    78
*  // Access the drives stored in 'driveArray'
williamr@2
    79
*  driveCount = driveArray.Count() ); // The number of drives stored in 'driveArray'
williamr@2
    80
*  for( TInt i( 0 ); i < driveCount; ++i )
williamr@2
    81
*      {
williamr@2
    82
*      TDriveNumber drive( driveArray[ i ] ); // The drive identifier at position 'i'
williamr@2
    83
*      TChar driveLetter( driveArray.LetterAt( i ) ); // The drive letter at position 'i'
williamr@2
    84
*      // ...
williamr@2
    85
*      }
williamr@2
    86
*
williamr@2
    87
* @endcode
williamr@2
    88
*
williamr@2
    89
* Error handling:
williamr@2
    90
*
williamr@2
    91
* System wide error codes are returned to indicate errors in methods that can fail.
williamr@2
    92
*
williamr@2
    93
*  @lib PlatformEnv.dll
williamr@2
    94
*  @since 3.2
williamr@2
    95
*/
williamr@2
    96
williamr@2
    97
NONSHARABLE_CLASS(DriveInfo)
williamr@2
    98
    {
williamr@2
    99
    public:
williamr@2
   100
        /**
williamr@2
   101
         * Enumeration Default Drives to be used with GetDefaultDrive() method.
williamr@2
   102
         * @since 3.2
williamr@2
   103
         */
williamr@2
   104
        enum TDefaultDrives
williamr@2
   105
            {
williamr@2
   106
            /** To get the default ROM drive.
williamr@2
   107
            */
williamr@2
   108
            EDefaultRom = 0,
williamr@2
   109
williamr@2
   110
            /** To get the default RAM drive.
williamr@2
   111
            */
williamr@2
   112
            EDefaultRam,
williamr@2
   113
williamr@2
   114
            /** To get the default system drive.
williamr@2
   115
            * The default system drive is the preferred drive for system specific functionalities.
williamr@2
   116
            */
williamr@2
   117
            EDefaultSystem,
williamr@2
   118
williamr@2
   119
            /** To get the default phone memory like FLASH memory, internal memory card, hard drive etc.
williamr@2
   120
            */
williamr@2
   121
            EDefaultPhoneMemory,
williamr@2
   122
williamr@2
   123
            /** To get the default mass storage like any kind of memory card, hard drive, USB stick etc.
williamr@2
   124
            * This definition should be always used, unless a removable mass storage is explicitly required.
williamr@2
   125
            * The default mass storage is the preferred drive for a large amount of user files.
williamr@2
   126
            */
williamr@2
   127
            EDefaultMassStorage,
williamr@2
   128
williamr@2
   129
            /** To get the default removable mass storage like memory card, USB stick etc.
williamr@2
   130
            * This definition should be used only when explicitly removable mass storage is required.
williamr@2
   131
            */
williamr@2
   132
            EDefaultRemovableMassStorage
williamr@2
   133
            };
williamr@2
   134
williamr@2
   135
       /**
williamr@2
   136
        * This method gets the default drive of requested type.
williamr@2
   137
        * If the device does not have the requested default drive, then KErrNotSupported is returned.
williamr@2
   138
        * This happens for example if device supports only internal drives and
williamr@2
   139
        * EDefaultRemovableMassStorage is requested.
williamr@2
   140
        *
williamr@2
   141
        * @since 3.2
williamr@2
   142
        * @param aDefaultDrive A default drive identifier specified by TDefaultDrives
williamr@2
   143
        * @param aDrive Stores a drive identifier specified by TDriveNumber
williamr@2
   144
        * @return A system wide error code.
williamr@2
   145
        *
williamr@2
   146
        * @see TDefaultDrives
williamr@2
   147
        * @see TDriveNumber
williamr@2
   148
        */
williamr@2
   149
        IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TInt& aDrive );
williamr@2
   150
williamr@2
   151
       /**
williamr@2
   152
        * This method gets the default drive of requested type.
williamr@2
   153
        * If the device does not have the requested default drive, then KErrNotSupported is returned.
williamr@2
   154
        * This happens for example if device supports only internal drives and
williamr@2
   155
        * EDefaultRemovableMassStorage is requested.
williamr@2
   156
        *
williamr@2
   157
        * @since 3.2
williamr@2
   158
        * @param aDefaultDrive A default drive identifier specified by TDefaultDrives
williamr@2
   159
        * @param aDriveLetter Stores a drive letter
williamr@2
   160
        * @return A system wide error code.
williamr@2
   161
        *
williamr@2
   162
        * @see TDefaultDrives
williamr@2
   163
        */
williamr@2
   164
        IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TChar& aDriveLetter );
williamr@2
   165
williamr@2
   166
        /**
williamr@2
   167
         * Enumeration bit mask Status used by GetDriveStatus() method.
williamr@2
   168
         * @since 3.2
williamr@2
   169
         */
williamr@2
   170
        enum TStatus
williamr@2
   171
            {
williamr@2
   172
            /** To indicate that the drive is internal and 
williamr@2
   173
            * cannot be physically removed.
williamr@2
   174
            */
williamr@2
   175
            EDriveInternal = 0x1,
williamr@2
   176
williamr@2
   177
            /** To indicate that the drive is physically removable.
williamr@2
   178
            */
williamr@2
   179
            EDriveRemovable = 0x2,
williamr@2
   180
williamr@2
   181
            /** To indicate that the drive is remote.
williamr@2
   182
            */
williamr@2
   183
            EDriveRemote = 0x4,
williamr@2
   184
williamr@2
   185
            /** To indicate that the drive is present.
williamr@2
   186
            */
williamr@2
   187
            EDrivePresent = 0x8,
williamr@2
   188
williamr@2
   189
            /** To indicate that the drive is locked.
williamr@2
   190
            */
williamr@2
   191
            EDriveLocked = 0x10,
williamr@2
   192
williamr@2
   193
            /** To indicate that the drive is corrupt.
williamr@2
   194
            */
williamr@2
   195
            EDriveCorrupt = 0x20,
williamr@2
   196
williamr@2
   197
            /** To indicate that the drive is in use i.e.
williamr@2
   198
            * reserved for some exclusive usage.
williamr@2
   199
            */
williamr@2
   200
            EDriveInUse = 0x40,
williamr@2
   201
williamr@2
   202
            /** To indicate that the drive is readonly.
williamr@2
   203
            */
williamr@2
   204
            EDriveReadOnly = 0x80,
williamr@2
   205
williamr@2
   206
            /** To indicate that the drive is substed.
williamr@2
   207
            */
williamr@2
   208
            EDriveSubsted = 0x100,
williamr@2
   209
williamr@2
   210
            /** To indicate that the drive is user visible.
williamr@2
   211
            * The UI is allowed to show the drive to the user.
williamr@2
   212
            */
williamr@2
   213
            EDriveUserVisible = 0x200,
williamr@2
   214
williamr@2
   215
            /** To indicate that the drive is externally mountable i.e.
williamr@2
   216
            * can be mounted from PC or from other devices.
williamr@2
   217
            */
williamr@2
   218
            EDriveExternallyMountable = 0x400,
williamr@2
   219
williamr@2
   220
            /** To indicate that the drive is software ejectable.
williamr@2
   221
            * The user can select software based eject from the UI for this drive.
williamr@2
   222
            */
williamr@2
   223
            EDriveSwEjectable = 0x800,
williamr@2
   224
williamr@2
   225
            /** To indicate that the drive is ROM drive.
williamr@2
   226
            */
williamr@2
   227
            EDriveRom = 0x1000,
williamr@2
   228
williamr@2
   229
            /** To indicate that the drive is RAM drive.
williamr@2
   230
            */
williamr@2
   231
            EDriveRam = 0x2000,
williamr@2
   232
williamr@2
   233
            /** To indicate that the drive has been formatted.
williamr@2
   234
            */
williamr@2
   235
            EDriveFormatted = 0x4000,
williamr@2
   236
williamr@2
   237
            /** To indicate that the drive is formattable.
williamr@2
   238
            */
williamr@2
   239
            EDriveFormattable = 0x8000,
williamr@2
   240
williamr@2
   241
            /** To indicate that the drive is lockable i.e. password can be set.
williamr@2
   242
            */
williamr@2
   243
            EDriveLockable = 0x10000,
williamr@2
   244
williamr@2
   245
            /** To indicate that the drive is password protected.
williamr@2
   246
            */
williamr@2
   247
            EDriveHasPassword = 0x20000
williamr@2
   248
williamr@2
   249
            };
williamr@2
   250
williamr@2
   251
       /**
williamr@2
   252
        * This method gets the drive status, a bit mask specified by TStatus.
williamr@2
   253
        *
williamr@2
   254
        * @since 3.2
williamr@2
   255
        * @param aFs An opened file server session
williamr@2
   256
        * @param aDrive A drive identifier specified by TDriveNumber
williamr@2
   257
        * @param aStatus Stores the drive status bit mask specified by TStatus
williamr@2
   258
        * @return A system wide error code.
williamr@2
   259
        *
williamr@2
   260
        * @see RFs
williamr@2
   261
        * @see TDriveNumber
williamr@2
   262
        * @see TStatus
williamr@2
   263
        */
williamr@2
   264
        IMPORT_C static TInt GetDriveStatus( RFs& aFs, TInt aDrive, TUint& aStatus );
williamr@2
   265
williamr@2
   266
       /**
williamr@2
   267
        * This method gets all the drives that are visible to the user.
williamr@2
   268
        *
williamr@2
   269
        * @since 3.2
williamr@2
   270
        * @param aFs An opened file server session
williamr@2
   271
        * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.
williamr@2
   272
        * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.
williamr@2
   273
        * @return A system wide error code.
williamr@2
   274
        *
williamr@2
   275
        * @see RFs
williamr@2
   276
        * @see TDriveList
williamr@2
   277
        */
williamr@2
   278
        IMPORT_C static TInt GetUserVisibleDrives(
williamr@2
   279
            RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount );
williamr@2
   280
williamr@2
   281
       /**
williamr@2
   282
        * This method gets the user visible drives with specified file server drive 
williamr@2
   283
        * attributes.
williamr@2
   284
        *
williamr@2
   285
        * Note that file server drive attributes are not equal with TStatus definitions.
williamr@2
   286
        *
williamr@2
   287
        * @since 3.2
williamr@2
   288
        * @param aFs An opened file server session
williamr@2
   289
        * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.
williamr@2
   290
        * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.
williamr@2
   291
        * @param aFlags The mask flags specified for RFs::DriveList() method.
williamr@2
   292
        * @return A system wide error code.
williamr@2
   293
        *
williamr@2
   294
        * @see RFs
williamr@2
   295
        * @see TDriveList
williamr@2
   296
        */
williamr@2
   297
        IMPORT_C static TInt GetUserVisibleDrives(
williamr@2
   298
            RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount, TUint aFlags );
williamr@2
   299
williamr@2
   300
       /**
williamr@2
   301
        * This method methods checks the given drive list and removes the drives hidden from the user.
williamr@2
   302
        * It is intended to be used with the drive lists that are not read by using GetUserVisibleDrives() method
williamr@2
   303
        * e.g. the drive list has been got as a parameter elsewhere.
williamr@2
   304
        *
williamr@2
   305
        * @since 3.2
williamr@2
   306
        * @param aDriveList A drive list where to remove the drives hidden from the user.
williamr@2
   307
        * @return A drive count i.e. number of non zero items in the given drive list after removal.
williamr@2
   308
        *
williamr@2
   309
        * @see TDriveList
williamr@2
   310
        */
williamr@2
   311
        IMPORT_C static TInt StripUserHiddenDrives( TDriveList& aDriveList );
williamr@2
   312
williamr@2
   313
       /**
williamr@2
   314
        * This method returns the number of drives in the given drive list.
williamr@2
   315
        *
williamr@2
   316
        * @since 3.2
williamr@2
   317
        * @param aDriveList A drive list where to count the number of drives.
williamr@2
   318
        * @return A drive count i.e. number of non zero items in the given drive list.
williamr@2
   319
        *
williamr@2
   320
        * @see TDriveList
williamr@2
   321
        */
williamr@2
   322
        IMPORT_C static TInt DriveCount( const TDriveList& aDriveList );
williamr@2
   323
williamr@2
   324
        /**
williamr@2
   325
         * Class TDriveArray provides easy-to-use access to drive identifiers.
williamr@2
   326
         * @since S60 5.0
williamr@2
   327
         */
williamr@2
   328
        class TDriveArray
williamr@2
   329
            {
williamr@2
   330
            public: // Constructors
williamr@2
   331
                inline TDriveArray();
williamr@2
   332
                inline TDriveArray( const TDriveList& aDriveList );
williamr@2
   333
williamr@2
   334
            public:
williamr@2
   335
                /**
williamr@2
   336
                 * This method sets the drive array data from given drive list.
williamr@2
   337
                 *
williamr@2
   338
                 * @since 3.2
williamr@2
   339
                 * @param aDriveList A drive list where to set the data from.
williamr@2
   340
                 *
williamr@2
   341
                 * @see TDriveList
williamr@2
   342
                 */
williamr@2
   343
                IMPORT_C void Set( const TDriveList& aDriveList );
williamr@2
   344
williamr@2
   345
                /**
williamr@2
   346
                 * This method resets the array.
williamr@2
   347
                 *
williamr@2
   348
                 * @since 3.2
williamr@2
   349
                 */
williamr@2
   350
                inline void Reset();
williamr@2
   351
williamr@2
   352
                /**
williamr@2
   353
                 * This method gets the number of drives in the array.
williamr@2
   354
                 *
williamr@2
   355
                 * @since 3.2
williamr@2
   356
                 * @return A number of drives in the array.
williamr@2
   357
                 */
williamr@2
   358
                inline TInt Count() const;
williamr@2
   359
williamr@2
   360
                /**
williamr@2
   361
                 * This method gets the drive identifier at given index within the array.
williamr@2
   362
                 *
williamr@2
   363
                 * @since 3.2
williamr@2
   364
                 * @param aIndex The position of drive within the array.
williamr@2
   365
                 * @return A drive identifier specified by TDriveNumber.
williamr@2
   366
                 *
williamr@2
   367
                 * @panic USER 21 if aIndex is negative or is greater than 
williamr@2
   368
                 * the number of drives in the array
williamr@2
   369
                 *
williamr@2
   370
                 * @see TDriveNumber
williamr@2
   371
                 */
williamr@2
   372
                inline TDriveNumber operator[]( TInt aIndex ) const;
williamr@2
   373
williamr@2
   374
                /**
williamr@2
   375
                 * This method gets the drive letter at given index within the array.
williamr@2
   376
                 *
williamr@2
   377
                 * @since 3.2
williamr@2
   378
                 * @param aIndex The position of drive within the array.
williamr@2
   379
                 * @return A drive letter.
williamr@2
   380
                 *
williamr@2
   381
                 * @panic USER 21 if aIndex is negative or is greater than 
williamr@2
   382
                 * the number of drives in the array
williamr@2
   383
                 */
williamr@2
   384
                IMPORT_C TChar LetterAt( TInt aIndex ) const;
williamr@2
   385
williamr@2
   386
            private:
williamr@2
   387
                TBuf8< KMaxDrives > iArray;
williamr@2
   388
            };
williamr@2
   389
williamr@2
   390
       /**
williamr@2
   391
        * This method gets all the drives that are visible to the user.
williamr@2
   392
        *
williamr@2
   393
        * @since 3.2
williamr@2
   394
        * @param aFs An opened file server session
williamr@2
   395
        * @param aDriveArray Stores the user visible drives
williamr@2
   396
        * @return A system wide error code.
williamr@2
   397
        *
williamr@2
   398
        * @see RFs
williamr@2
   399
        * @see TDriveArray
williamr@2
   400
        */
williamr@2
   401
        IMPORT_C static TInt GetUserVisibleDrives( RFs& aFs, TDriveArray& aDriveArray );
williamr@2
   402
williamr@2
   403
       /**
williamr@2
   404
        * This method gets the user visible drives with specified file server drive 
williamr@2
   405
        * attributes.
williamr@2
   406
        *
williamr@2
   407
        * Note that file server drive attributes are not equal with TStatus definitions.
williamr@2
   408
        *
williamr@2
   409
        * @since 3.2
williamr@2
   410
        * @param aFs An opened file server session
williamr@2
   411
        * @param aDriveArray Stores the user visible drives
williamr@2
   412
        * @param aFlags The mask flags specified for RFs::DriveList() method.
williamr@2
   413
        * @return A system wide error code.
williamr@2
   414
        *
williamr@2
   415
        * @see RFs
williamr@2
   416
        * @see TDriveArray
williamr@2
   417
        */
williamr@2
   418
        IMPORT_C static TInt GetUserVisibleDrives(
williamr@2
   419
            RFs& aFs, TDriveArray& aDriveArray, TUint aFlags );
williamr@2
   420
williamr@2
   421
    private:
williamr@2
   422
williamr@2
   423
        /**
williamr@2
   424
        * C++ default constructor.
williamr@2
   425
        */
williamr@2
   426
        DriveInfo();
williamr@2
   427
    };
williamr@2
   428
williamr@2
   429
#include "driveinfo.inl"
williamr@2
   430
williamr@2
   431
#endif      // DRIVE_INFO_H   
williamr@2
   432
williamr@2
   433
// End of File