1.1 --- a/epoc32/include/bafl/sysutil.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/bafl/sysutil.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,210 +1,193 @@
1.4 /*
1.5 -* Copyright (c) 2000-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* Copyright (c) 2006-2009 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 +* under the terms of "Eclipse Public License v1.0"
1.11 * which accompanies this distribution, and is available
1.12 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.13 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.14 *
1.15 * Initial Contributors:
1.16 * Nokia Corporation - initial contribution.
1.17 *
1.18 * Contributors:
1.19 *
1.20 -* Description: SysUtil API provides functions for applications to retrieve
1.21 -* SW and language package versions and check whether there is
1.22 -* free space on a disk drive.
1.23 +* Description:
1.24 *
1.25 */
1.26
1.27
1.28 +
1.29 #ifndef SYSUTIL_H
1.30 #define SYSUTIL_H
1.31
1.32 #include <e32base.h>
1.33
1.34 +class RFs;
1.35 +class CDeviceTypeInformation;
1.36 +
1.37 /**
1.38 -* Helper constant to allocate buffers for GetSWVersion, GetLangSWVersion,
1.39 -* GetLangVersion.
1.40 +Constant conveying the size of the preallocated descriptor buffers used with
1.41 +the SysUtil version APIs.
1.42 +
1.43 +@see SysUtil::GetSWVersion
1.44 +@see SysUtil::GetLangSWVersion
1.45 +@see SysUtil::GetLangVersion
1.46 +@publishedAll
1.47 +@released
1.48 */
1.49 const TInt KSysUtilVersionTextLength = 64;
1.50
1.51 -class RFs;
1.52
1.53 /**
1.54 - * SysUtil provides various utility methods for applications.
1.55 - *
1.56 - * SysUtil API provides functions for applications to retrieve SW and language
1.57 - * package versions and check whether there is free space on a disk drive.
1.58 - *
1.59 - * @lib sysutil.lib
1.60 - * @since S60 v2.0
1.61 - */
1.62 +SysUtil provides various system utility methods, as follows:
1.63 + - Functions for applications to retrieve SW and language package versions
1.64 + strings for display purposes
1.65 + - Functions to check whether there is free space on a disk drive before
1.66 + file creation or writing.
1.67 + - Functions to retrieve Device Type information (e.g. phone model) for display
1.68 + purposes.
1.69 +
1.70 +Version, Attribute strings and free space thresholds are provisioned by
1.71 +the device creator into the ROM. For details on this see the
1.72 +'SGL.TS0017.324 BAFL How-To FAQ Document' in the OS Developer Library.
1.73 +
1.74 +@publishedAll
1.75 +@released
1.76 +*/
1.77 class SysUtil
1.78 {
1.79 -
1.80 public:
1.81 -
1.82 - /**
1.83 - * Obtains the software version string.
1.84 - *
1.85 - * @since S60 v2.0
1.86 - *
1.87 - * Usage example:
1.88 - * @code
1.89 - * TBuf<KSysUtilVersionTextLength> version;
1.90 - * if ( SysUtil::GetSWVersion( version ) == KErrNone )
1.91 - * {
1.92 - * // Use the version string.
1.93 - * ...
1.94 - * }
1.95 - * @endcode
1.96 - *
1.97 - * @param aValue On return, contains the software version string.
1.98 - * The buffer should have space for KSysUtilVersionTextLength
1.99 - * characters.
1.100 - *
1.101 - * @return KErrNone on success, or one of the Symbian error codes if reading
1.102 - * the version string fails.
1.103 - */
1.104 IMPORT_C static TInt GetSWVersion( TDes& aValue );
1.105 -
1.106 - /**
1.107 - * Returns software version which the currently installed language package
1.108 - * is compatible with.
1.109 - *
1.110 - * @since S60 v2.0
1.111 - *
1.112 - * @param aValue On return, contains the version string.
1.113 - * The buffer should have space for KSysUtilVersionTextLength
1.114 - * characters.
1.115 - *
1.116 - * @return KErrNone on success, or one of the Symbian error codes if reading
1.117 - * the version string fails.
1.118 - */
1.119 IMPORT_C static TInt GetLangSWVersion( TDes& aValue );
1.120 -
1.121 - /**
1.122 - * Obtains the version of the currently installed language package.
1.123 - *
1.124 - * @since S60 v2.0
1.125 - *
1.126 - * @param aValue On return, contains the language package version string.
1.127 - * The buffer should have space for KSysUtilVersionTextLength
1.128 - * characters.
1.129 - *
1.130 - * @return KErrNone on success, or one of the Symbian error codes if reading
1.131 - * the version string fails.
1.132 - */
1.133 IMPORT_C static TInt GetLangVersion( TDes& aValue );
1.134 -
1.135 - /**
1.136 - * Checks if free FFS (internal flash file system) storage space is or will
1.137 - * fall below critical level. Static configuration value stored in Central
1.138 - * Repository is used to determine the critical level for the FFS drive.
1.139 - *
1.140 - * @since S60 v2.0
1.141 - *
1.142 - * @param aFs File server session. Must be given if available, e.g. from
1.143 - * EIKON environment. If NULL, this method will create a
1.144 - * temporary session, which causes the method to consume more
1.145 - * time and system resources.
1.146 - * @param aBytesToWrite Number of bytes the caller is about to write to
1.147 - * FFS. If value 0 is given, this method checks
1.148 - * if the current FFS space is already below critical
1.149 - * level.
1.150 - *
1.151 - * @return ETrue if FFS space would go below critical level after writing
1.152 - * aBytesToWrite more data, EFalse otherwise.
1.153 - *
1.154 - * @leave Leaves with one of the Symbian error codes if checking the FFS
1.155 - * space fails, for instance if there is not enough free memory to
1.156 - * create a temporary connection to file server.
1.157 - */
1.158 - IMPORT_C static TBool FFSSpaceBelowCriticalLevelL(
1.159 + IMPORT_C static TInt GetPRInformation( TDes& aValue );
1.160 +
1.161 +private:
1.162 + IMPORT_C static TBool FFSSpaceBelowCriticalLevel_OldL(
1.163 RFs* aFs,
1.164 TInt aBytesToWrite = 0 );
1.165 -
1.166 -
1.167 - /**
1.168 - * Checks if free MMC storage space is or will fall below critical
1.169 - * level. Static configuration value stored in Central Repository is
1.170 - * used to determine the critical level for the MMC drive.
1.171 - * PathInfo API is used to determine the drive letter for the MMC drive.
1.172 - *
1.173 - * @since S60 v2.0
1.174 - *
1.175 - * @param aFs File server session. Must be given if available, e.g. from
1.176 - * EIKON environment. If NULL, this method will create a
1.177 - * temporary session, which causes the method to consume more
1.178 - * time and system resources.
1.179 - * @param aBytesToWrite Number of bytes the caller is about to write to
1.180 - * MMC. If value 0 is given, this method checks
1.181 - * if the current MMC space is already below critical
1.182 - * level.
1.183 - *
1.184 - * @return ETrue if MMC space would go below critical level after writing
1.185 - * aBytesToWrite more data, EFalse otherwise.
1.186 - * EFalse if the system has no MMC drive support.
1.187 - *
1.188 - * @leave Leaves with one of the Symbian error codes if checking the MMC
1.189 - * space fails, for instance if the MMC drive contains no media or
1.190 - * there is not enough free memory to create a temporary connection to
1.191 - * file server.
1.192 - */
1.193 - IMPORT_C static TBool MMCSpaceBelowCriticalLevelL(
1.194 + IMPORT_C static TBool MMCSpaceBelowCriticalLevel_OldL(
1.195 RFs* aFs,
1.196 TInt aBytesToWrite = 0 );
1.197 -
1.198 - /**
1.199 - * Checks if free disk drive storage space is or will fall below critical
1.200 - * level. Static configuration values stored in Central Repository are
1.201 - * used to determine a critical level for each drive.
1.202 - *
1.203 - * Usage example:
1.204 - * @code
1.205 - * TInt dataSize = 500;
1.206 - * if ( SysUtil::DiskSpaceBelowCriticalLevelL( &iFsSession, dataSize, EDriveC ) )
1.207 - * {
1.208 - * // Can not write the data, there's not enough free space on disk.
1.209 - * ...
1.210 - * }
1.211 - * else
1.212 - * {
1.213 - * // It's ok to actually write the data.
1.214 - * ...
1.215 - * }
1.216 - * @endcode
1.217 - *
1.218 - * @since S60 v2.0
1.219 - *
1.220 - * @param aFs File server session. Must be given if available, e.g. from
1.221 - * EIKON environment. If NULL, this method will create a
1.222 - * temporary session, which causes the method to consume more
1.223 - * time and system resources.
1.224 - * @param aBytesToWrite Number of bytes the caller is about to write to
1.225 - * disk. If value 0 is given, this method checks
1.226 - * if the current disk space is already below critical
1.227 - * level.
1.228 - * @param aDrive Identifies the disk drive to be checked. Numeric values
1.229 - * for identifying disk drives are defined in TDriveNumber
1.230 - * enumeration.
1.231 - *
1.232 - * @see TDriveNumber in f32file.h.
1.233 - *
1.234 - * @return ETrue if disk space would go below critical level after writing
1.235 - * aBytesToWrite more data, EFalse otherwise.
1.236 - *
1.237 - * @leave Leaves with one of the Symbian error codes if checking the disk
1.238 - * space fails, for instance if the drive contains no media or there
1.239 - * is not enough free memory to create a temporary connection to
1.240 - * file server.
1.241 - */
1.242 - IMPORT_C static TBool DiskSpaceBelowCriticalLevelL(
1.243 + IMPORT_C static TBool DiskSpaceBelowCriticalLevel_OldL(
1.244 RFs* aFs,
1.245 TInt aBytesToWrite,
1.246 TInt aDrive );
1.247 +public:
1.248 + IMPORT_C static TInt GetMMCDriveLetter( RFs & aFs );
1.249 + IMPORT_C static TInt GetFFSDriveLetter( RFs & aFs );
1.250 +
1.251 +public:
1.252 + IMPORT_C static CDeviceTypeInformation* GetDeviceTypeInfoL();
1.253 +
1.254 + IMPORT_C static TBool FFSSpaceBelowCriticalLevelL(
1.255 + RFs* aFs,
1.256 + TInt64 aBytesToWrite = 0 );
1.257 + IMPORT_C static TBool MMCSpaceBelowCriticalLevelL(
1.258 + RFs* aFs,
1.259 + TInt64 aBytesToWrite = 0 );
1.260 + IMPORT_C static TBool DiskSpaceBelowCriticalLevelL(
1.261 + RFs* aFs,
1.262 + TInt64 aBytesToWrite,
1.263 + TInt aDrive );
1.264 + };
1.265
1.266 - };
1.267 +/**
1.268 +This class is used to hold the device type information attributes and provides
1.269 +member functions to return the attribute values. These values are strings of
1.270 +UTF-16 characters and no format must be assumed or implied as it varies from
1.271 +one device manufacturer to the next. Please note that this information does not
1.272 +identify a unique device but identifies the type of device.
1.273 +
1.274 +An instance of this class cannot be created by user code. If device type
1.275 +information attributes are required then the user should use
1.276 +SysUtil::GetDeviceTypeInfoL which will return a pointer to an instance of this
1.277 +class. This instance will contain a full set of device type information
1.278 +attributes that have been provisioned by the device creator. For
1.279 +details of how these are provisioned see 'XXX xxx' document in the OS Developer
1.280 +Library.
1.281 +
1.282 +For standard device type information attributes (attributes which are common
1.283 +to all device creators) named functions have been provided. These functions
1.284 +also offer the advantage of a default value being provided when an attribute
1.285 +has not been provisioned by the device creator. If a default value has been
1.286 +retrieved KDefaultValue will be returned.
1.287 +
1.288 +Callers who do not care about whether a default value is retrieved or not can
1.289 +use the API as follows:
1.290 +
1.291 +@code
1.292 + TPtrC16 modelNamePtrC;
1.293 + User::LeaveIfError( deviceTypeInfo->GetModelName(modelNamePtrC) );
1.294 +@endcode
1.295 +
1.296 +Where callers wish to avoid the default value it can be tested for as follows:
1.297 +
1.298 +@code
1.299 + TPtrC16 modelNamePtrC;
1.300 + if (User::LeaveIfError( deviceTypeInfo->GetModelName(modelNamePtrC)) == CDeviceTypeInformation::KDefaultValue)
1.301 + {
1.302 + // We have a default attribute value, do something else
1.303 + ...
1.304 + }
1.305 + else
1.306 + {
1.307 + // We have a device creator supplied attribute value.
1.308 + ...
1.309 + }
1.310 +@endcode
1.311 +
1.312 +In addition to named functions, two additional generic functions are provided
1.313 +that can be used to retrieve any additional device type information attributes
1.314 +which may be provided by a device creator. These functions can also be used to
1.315 +retrieve the standard attributes; however, it is recommended that the named
1.316 +functions be used instead.
1.317 +
1.318 +Any code which owns an instance of this class has the responsibility of
1.319 +destroying it. This may be achieved by calling delete on the pointer or using
1.320 +the CleanupStack.
1.321 +
1.322 +@publishedAll
1.323 +@released
1.324 +*/
1.325 +NONSHARABLE_CLASS(CDeviceTypeInformation) : public CBase
1.326 + {
1.327 +public: //publishedAll
1.328 + /**
1.329 + The maximum length of a device attribute string value.
1.330 + */
1.331 + static const TInt KMaxAttributeLength = 64;
1.332 +
1.333 + /**
1.334 + This const is a value returned from calls to the named
1.335 + CDeviceTypeInformation APIs. It indicates to the caller that the returned
1.336 + device type information attribute, stored in CDeviceTypeInformation, is a
1.337 + default value. This occurs when the device creator does not provision the
1.338 + attribute value.
1.339 + */
1.340 + static const TInt KDefaultValue = 1;
1.341 +public: // publishedAll
1.342 + IMPORT_C ~CDeviceTypeInformation();
1.343 + static CDeviceTypeInformation* NewL();
1.344 + IMPORT_C TInt GetManufacturerName( TPtrC16& aValue ) const;
1.345 + IMPORT_C TInt GetModelName( TPtrC16& aValue ) const;
1.346 + IMPORT_C TInt GetModelCode( TPtrC16& aValue ) const;
1.347 + IMPORT_C TInt GetRevisionID( TPtrC16& aValue ) const;
1.348 + IMPORT_C TInt GetDefaultDeviceName( TPtrC16& aValue ) const;
1.349 + IMPORT_C TInt GetUIPlatformName( TPtrC16& aValue ) const;
1.350 + IMPORT_C TInt GetUIPlatformVersion( TPtrC16& aValue ) const;
1.351 + IMPORT_C TInt GetUIPlatformVersion( TUint16& aMajor, TUint16& aMinor ) const;
1.352 + IMPORT_C TInt GetOSVersion( TPtrC16& aValue ) const;
1.353 + IMPORT_C TInt GetOSVersion( TUint16& aMajor, TUint16& aMinor ) const;
1.354 +
1.355 +public: // publishedPartner
1.356 + IMPORT_C TInt GetAttribute( const TUid& aAttributeUid, TPtrC16& aValue ) const;
1.357 +private:
1.358 + CDeviceTypeInformation();
1.359 + void ConstructL();
1.360 +private:
1.361 + class TImpl;
1.362 + TImpl* iImpl;
1.363 + };
1.364
1.365 #endif // SYSUTIL_H