1.1 --- a/epoc32/include/driveinfo.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/driveinfo.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,433 @@
1.4 -driveinfo.h
1.5 +/*
1.6 +* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Interface for quering the drive information of the system.
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +#ifndef DRIVE_INFO_H
1.25 +#define DRIVE_INFO_H
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32std.h>
1.29 +#include <f32file.h>
1.30 +
1.31 +// CLASS DECLARATION
1.32 +/**
1.33 +* Class holds the drive information of the system. Platform Environment API provides
1.34 +* interface for quering the drive information of the system. Methods provided by the API should be
1.35 +* used instead of the hard coded drive identifiers.
1.36 +* The API consist of the DriveInfo class, PathInfo class and system paths are defined
1.37 +* in PathConfiguration.hrh. The PathInfo class is defined in PathInfo.h.
1.38 +*
1.39 +* Usage:
1.40 +*
1.41 +* @code
1.42 +* #include <DriveInfo.h>
1.43 +*
1.44 +* // Get the drive identifier of the default removable mass storage.
1.45 +* TInt drive;
1.46 +* User::LeaveIfError( DriveInfo::GetDefaultDrive(
1.47 +* DriveInfo::EDefaultRemovableMassStorage, drive ) );
1.48 +*
1.49 +* // 'drive' contains now the drive identifier of the default removable mass storage.
1.50 +*
1.51 +* // Get the drive status of the default removable mass storage.
1.52 +* TUint status;
1.53 +* User::LeaveIfError( DriveInfo::GetDriveStatus( fs, drive, status ) );
1.54 +*
1.55 +* // 'status' contains now the drive status of the default removable mass storage.
1.56 +*
1.57 +* // Get all drives that are visible to the user in TDriveList.
1.58 +* TDriveList driveList;
1.59 +* TInt driveCount;
1.60 +* User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveList, driveCount ) );
1.61 +*
1.62 +* // 'driveList' contains now the user visible drives.
1.63 +* // 'driveCount'contains now the drive count i.e. number of non zero items in driveList.
1.64 +*
1.65 +* // Access the drives stored in 'driveList'
1.66 +* TInt driveListLen( driveList.Length() ); // The length of 'driveList'
1.67 +* for( TInt i( 0 ); i < driveListLen; ++i )
1.68 +* {
1.69 +* if ( driveList[ i ] ) // Non zero items are valid drives
1.70 +* {
1.71 +* // 'i' contains drive identifier specified by TDriveNumber
1.72 +* // ...
1.73 +* }
1.74 +* }
1.75 +*
1.76 +* // Get all drives that are visible to the user in DriveInfo::TDriveArray.
1.77 +* DriveInfo::TDriveArray driveArray;
1.78 +* User::LeaveIfError( DriveInfo::GetUserVisibleDrives( fs, driveArray ) );
1.79 +*
1.80 +* // 'driveArray' contains now the user visible drives.
1.81 +*
1.82 +* // Access the drives stored in 'driveArray'
1.83 +* driveCount = driveArray.Count() ); // The number of drives stored in 'driveArray'
1.84 +* for( TInt i( 0 ); i < driveCount; ++i )
1.85 +* {
1.86 +* TDriveNumber drive( driveArray[ i ] ); // The drive identifier at position 'i'
1.87 +* TChar driveLetter( driveArray.LetterAt( i ) ); // The drive letter at position 'i'
1.88 +* // ...
1.89 +* }
1.90 +*
1.91 +* @endcode
1.92 +*
1.93 +* Error handling:
1.94 +*
1.95 +* System wide error codes are returned to indicate errors in methods that can fail.
1.96 +*
1.97 +* @lib PlatformEnv.dll
1.98 +* @since 3.2
1.99 +*/
1.100 +
1.101 +NONSHARABLE_CLASS(DriveInfo)
1.102 + {
1.103 + public:
1.104 + /**
1.105 + * Enumeration Default Drives to be used with GetDefaultDrive() method.
1.106 + * @since 3.2
1.107 + */
1.108 + enum TDefaultDrives
1.109 + {
1.110 + /** To get the default ROM drive.
1.111 + */
1.112 + EDefaultRom = 0,
1.113 +
1.114 + /** To get the default RAM drive.
1.115 + */
1.116 + EDefaultRam,
1.117 +
1.118 + /** To get the default system drive.
1.119 + * The default system drive is the preferred drive for system specific functionalities.
1.120 + */
1.121 + EDefaultSystem,
1.122 +
1.123 + /** To get the default phone memory like FLASH memory, internal memory card, hard drive etc.
1.124 + */
1.125 + EDefaultPhoneMemory,
1.126 +
1.127 + /** To get the default mass storage like any kind of memory card, hard drive, USB stick etc.
1.128 + * This definition should be always used, unless a removable mass storage is explicitly required.
1.129 + * The default mass storage is the preferred drive for a large amount of user files.
1.130 + */
1.131 + EDefaultMassStorage,
1.132 +
1.133 + /** To get the default removable mass storage like memory card, USB stick etc.
1.134 + * This definition should be used only when explicitly removable mass storage is required.
1.135 + */
1.136 + EDefaultRemovableMassStorage
1.137 + };
1.138 +
1.139 + /**
1.140 + * This method gets the default drive of requested type.
1.141 + * If the device does not have the requested default drive, then KErrNotSupported is returned.
1.142 + * This happens for example if device supports only internal drives and
1.143 + * EDefaultRemovableMassStorage is requested.
1.144 + *
1.145 + * @since 3.2
1.146 + * @param aDefaultDrive A default drive identifier specified by TDefaultDrives
1.147 + * @param aDrive Stores a drive identifier specified by TDriveNumber
1.148 + * @return A system wide error code.
1.149 + *
1.150 + * @see TDefaultDrives
1.151 + * @see TDriveNumber
1.152 + */
1.153 + IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TInt& aDrive );
1.154 +
1.155 + /**
1.156 + * This method gets the default drive of requested type.
1.157 + * If the device does not have the requested default drive, then KErrNotSupported is returned.
1.158 + * This happens for example if device supports only internal drives and
1.159 + * EDefaultRemovableMassStorage is requested.
1.160 + *
1.161 + * @since 3.2
1.162 + * @param aDefaultDrive A default drive identifier specified by TDefaultDrives
1.163 + * @param aDriveLetter Stores a drive letter
1.164 + * @return A system wide error code.
1.165 + *
1.166 + * @see TDefaultDrives
1.167 + */
1.168 + IMPORT_C static TInt GetDefaultDrive( TInt aDefaultDrive, TChar& aDriveLetter );
1.169 +
1.170 + /**
1.171 + * Enumeration bit mask Status used by GetDriveStatus() method.
1.172 + * @since 3.2
1.173 + */
1.174 + enum TStatus
1.175 + {
1.176 + /** To indicate that the drive is internal and
1.177 + * cannot be physically removed.
1.178 + */
1.179 + EDriveInternal = 0x1,
1.180 +
1.181 + /** To indicate that the drive is physically removable.
1.182 + */
1.183 + EDriveRemovable = 0x2,
1.184 +
1.185 + /** To indicate that the drive is remote.
1.186 + */
1.187 + EDriveRemote = 0x4,
1.188 +
1.189 + /** To indicate that the drive is present.
1.190 + */
1.191 + EDrivePresent = 0x8,
1.192 +
1.193 + /** To indicate that the drive is locked.
1.194 + */
1.195 + EDriveLocked = 0x10,
1.196 +
1.197 + /** To indicate that the drive is corrupt.
1.198 + */
1.199 + EDriveCorrupt = 0x20,
1.200 +
1.201 + /** To indicate that the drive is in use i.e.
1.202 + * reserved for some exclusive usage.
1.203 + */
1.204 + EDriveInUse = 0x40,
1.205 +
1.206 + /** To indicate that the drive is readonly.
1.207 + */
1.208 + EDriveReadOnly = 0x80,
1.209 +
1.210 + /** To indicate that the drive is substed.
1.211 + */
1.212 + EDriveSubsted = 0x100,
1.213 +
1.214 + /** To indicate that the drive is user visible.
1.215 + * The UI is allowed to show the drive to the user.
1.216 + */
1.217 + EDriveUserVisible = 0x200,
1.218 +
1.219 + /** To indicate that the drive is externally mountable i.e.
1.220 + * can be mounted from PC or from other devices.
1.221 + */
1.222 + EDriveExternallyMountable = 0x400,
1.223 +
1.224 + /** To indicate that the drive is software ejectable.
1.225 + * The user can select software based eject from the UI for this drive.
1.226 + */
1.227 + EDriveSwEjectable = 0x800,
1.228 +
1.229 + /** To indicate that the drive is ROM drive.
1.230 + */
1.231 + EDriveRom = 0x1000,
1.232 +
1.233 + /** To indicate that the drive is RAM drive.
1.234 + */
1.235 + EDriveRam = 0x2000,
1.236 +
1.237 + /** To indicate that the drive has been formatted.
1.238 + */
1.239 + EDriveFormatted = 0x4000,
1.240 +
1.241 + /** To indicate that the drive is formattable.
1.242 + */
1.243 + EDriveFormattable = 0x8000,
1.244 +
1.245 + /** To indicate that the drive is lockable i.e. password can be set.
1.246 + */
1.247 + EDriveLockable = 0x10000,
1.248 +
1.249 + /** To indicate that the drive is password protected.
1.250 + */
1.251 + EDriveHasPassword = 0x20000
1.252 +
1.253 + };
1.254 +
1.255 + /**
1.256 + * This method gets the drive status, a bit mask specified by TStatus.
1.257 + *
1.258 + * @since 3.2
1.259 + * @param aFs An opened file server session
1.260 + * @param aDrive A drive identifier specified by TDriveNumber
1.261 + * @param aStatus Stores the drive status bit mask specified by TStatus
1.262 + * @return A system wide error code.
1.263 + *
1.264 + * @see RFs
1.265 + * @see TDriveNumber
1.266 + * @see TStatus
1.267 + */
1.268 + IMPORT_C static TInt GetDriveStatus( RFs& aFs, TInt aDrive, TUint& aStatus );
1.269 +
1.270 + /**
1.271 + * This method gets all the drives that are visible to the user.
1.272 + *
1.273 + * @since 3.2
1.274 + * @param aFs An opened file server session
1.275 + * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.
1.276 + * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.
1.277 + * @return A system wide error code.
1.278 + *
1.279 + * @see RFs
1.280 + * @see TDriveList
1.281 + */
1.282 + IMPORT_C static TInt GetUserVisibleDrives(
1.283 + RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount );
1.284 +
1.285 + /**
1.286 + * This method gets the user visible drives with specified file server drive
1.287 + * attributes.
1.288 + *
1.289 + * Note that file server drive attributes are not equal with TStatus definitions.
1.290 + *
1.291 + * @since 3.2
1.292 + * @param aFs An opened file server session
1.293 + * @param aDriveList Stores the user visible drives in the same format than RFs::DriveList() method.
1.294 + * @param aDriveCount Stores the drive count i.e. number of non zero items in aDriveList.
1.295 + * @param aFlags The mask flags specified for RFs::DriveList() method.
1.296 + * @return A system wide error code.
1.297 + *
1.298 + * @see RFs
1.299 + * @see TDriveList
1.300 + */
1.301 + IMPORT_C static TInt GetUserVisibleDrives(
1.302 + RFs& aFs, TDriveList& aDriveList, TInt& aDriveCount, TUint aFlags );
1.303 +
1.304 + /**
1.305 + * This method methods checks the given drive list and removes the drives hidden from the user.
1.306 + * It is intended to be used with the drive lists that are not read by using GetUserVisibleDrives() method
1.307 + * e.g. the drive list has been got as a parameter elsewhere.
1.308 + *
1.309 + * @since 3.2
1.310 + * @param aDriveList A drive list where to remove the drives hidden from the user.
1.311 + * @return A drive count i.e. number of non zero items in the given drive list after removal.
1.312 + *
1.313 + * @see TDriveList
1.314 + */
1.315 + IMPORT_C static TInt StripUserHiddenDrives( TDriveList& aDriveList );
1.316 +
1.317 + /**
1.318 + * This method returns the number of drives in the given drive list.
1.319 + *
1.320 + * @since 3.2
1.321 + * @param aDriveList A drive list where to count the number of drives.
1.322 + * @return A drive count i.e. number of non zero items in the given drive list.
1.323 + *
1.324 + * @see TDriveList
1.325 + */
1.326 + IMPORT_C static TInt DriveCount( const TDriveList& aDriveList );
1.327 +
1.328 + /**
1.329 + * Class TDriveArray provides easy-to-use access to drive identifiers.
1.330 + * @since S60 5.0
1.331 + */
1.332 + class TDriveArray
1.333 + {
1.334 + public: // Constructors
1.335 + inline TDriveArray();
1.336 + inline TDriveArray( const TDriveList& aDriveList );
1.337 +
1.338 + public:
1.339 + /**
1.340 + * This method sets the drive array data from given drive list.
1.341 + *
1.342 + * @since 3.2
1.343 + * @param aDriveList A drive list where to set the data from.
1.344 + *
1.345 + * @see TDriveList
1.346 + */
1.347 + IMPORT_C void Set( const TDriveList& aDriveList );
1.348 +
1.349 + /**
1.350 + * This method resets the array.
1.351 + *
1.352 + * @since 3.2
1.353 + */
1.354 + inline void Reset();
1.355 +
1.356 + /**
1.357 + * This method gets the number of drives in the array.
1.358 + *
1.359 + * @since 3.2
1.360 + * @return A number of drives in the array.
1.361 + */
1.362 + inline TInt Count() const;
1.363 +
1.364 + /**
1.365 + * This method gets the drive identifier at given index within the array.
1.366 + *
1.367 + * @since 3.2
1.368 + * @param aIndex The position of drive within the array.
1.369 + * @return A drive identifier specified by TDriveNumber.
1.370 + *
1.371 + * @panic USER 21 if aIndex is negative or is greater than
1.372 + * the number of drives in the array
1.373 + *
1.374 + * @see TDriveNumber
1.375 + */
1.376 + inline TDriveNumber operator[]( TInt aIndex ) const;
1.377 +
1.378 + /**
1.379 + * This method gets the drive letter at given index within the array.
1.380 + *
1.381 + * @since 3.2
1.382 + * @param aIndex The position of drive within the array.
1.383 + * @return A drive letter.
1.384 + *
1.385 + * @panic USER 21 if aIndex is negative or is greater than
1.386 + * the number of drives in the array
1.387 + */
1.388 + IMPORT_C TChar LetterAt( TInt aIndex ) const;
1.389 +
1.390 + private:
1.391 + TBuf8< KMaxDrives > iArray;
1.392 + };
1.393 +
1.394 + /**
1.395 + * This method gets all the drives that are visible to the user.
1.396 + *
1.397 + * @since 3.2
1.398 + * @param aFs An opened file server session
1.399 + * @param aDriveArray Stores the user visible drives
1.400 + * @return A system wide error code.
1.401 + *
1.402 + * @see RFs
1.403 + * @see TDriveArray
1.404 + */
1.405 + IMPORT_C static TInt GetUserVisibleDrives( RFs& aFs, TDriveArray& aDriveArray );
1.406 +
1.407 + /**
1.408 + * This method gets the user visible drives with specified file server drive
1.409 + * attributes.
1.410 + *
1.411 + * Note that file server drive attributes are not equal with TStatus definitions.
1.412 + *
1.413 + * @since 3.2
1.414 + * @param aFs An opened file server session
1.415 + * @param aDriveArray Stores the user visible drives
1.416 + * @param aFlags The mask flags specified for RFs::DriveList() method.
1.417 + * @return A system wide error code.
1.418 + *
1.419 + * @see RFs
1.420 + * @see TDriveArray
1.421 + */
1.422 + IMPORT_C static TInt GetUserVisibleDrives(
1.423 + RFs& aFs, TDriveArray& aDriveArray, TUint aFlags );
1.424 +
1.425 + private:
1.426 +
1.427 + /**
1.428 + * C++ default constructor.
1.429 + */
1.430 + DriveInfo();
1.431 + };
1.432 +
1.433 +#include "driveinfo.inl"
1.434 +
1.435 +#endif // DRIVE_INFO_H
1.436 +
1.437 +// End of File