--- a/epoc32/include/sysutil.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/sysutil.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,210 @@
-sysutil.h
+/*
+* Copyright (c) 2000-2006 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: SysUtil API provides functions for applications to retrieve
+* SW and language package versions and check whether there is
+* free space on a disk drive.
+*
+*/
+
+
+#ifndef SYSUTIL_H
+#define SYSUTIL_H
+
+#include <e32base.h>
+
+/**
+* Helper constant to allocate buffers for GetSWVersion, GetLangSWVersion,
+* GetLangVersion.
+*/
+const TInt KSysUtilVersionTextLength = 64;
+
+class RFs;
+
+/**
+ * SysUtil provides various utility methods for applications.
+ *
+ * SysUtil API provides functions for applications to retrieve SW and language
+ * package versions and check whether there is free space on a disk drive.
+ *
+ * @lib sysutil.lib
+ * @since S60 v2.0
+ */
+class SysUtil
+ {
+
+public:
+
+ /**
+ * Obtains the software version string.
+ *
+ * @since S60 v2.0
+ *
+ * Usage example:
+ * @code
+ * TBuf<KSysUtilVersionTextLength> version;
+ * if ( SysUtil::GetSWVersion( version ) == KErrNone )
+ * {
+ * // Use the version string.
+ * ...
+ * }
+ * @endcode
+ *
+ * @param aValue On return, contains the software version string.
+ * The buffer should have space for KSysUtilVersionTextLength
+ * characters.
+ *
+ * @return KErrNone on success, or one of the Symbian error codes if reading
+ * the version string fails.
+ */
+ IMPORT_C static TInt GetSWVersion( TDes& aValue );
+
+ /**
+ * Returns software version which the currently installed language package
+ * is compatible with.
+ *
+ * @since S60 v2.0
+ *
+ * @param aValue On return, contains the version string.
+ * The buffer should have space for KSysUtilVersionTextLength
+ * characters.
+ *
+ * @return KErrNone on success, or one of the Symbian error codes if reading
+ * the version string fails.
+ */
+ IMPORT_C static TInt GetLangSWVersion( TDes& aValue );
+
+ /**
+ * Obtains the version of the currently installed language package.
+ *
+ * @since S60 v2.0
+ *
+ * @param aValue On return, contains the language package version string.
+ * The buffer should have space for KSysUtilVersionTextLength
+ * characters.
+ *
+ * @return KErrNone on success, or one of the Symbian error codes if reading
+ * the version string fails.
+ */
+ IMPORT_C static TInt GetLangVersion( TDes& aValue );
+
+ /**
+ * Checks if free FFS (internal flash file system) storage space is or will
+ * fall below critical level. Static configuration value stored in Central
+ * Repository is used to determine the critical level for the FFS drive.
+ *
+ * @since S60 v2.0
+ *
+ * @param aFs File server session. Must be given if available, e.g. from
+ * EIKON environment. If NULL, this method will create a
+ * temporary session, which causes the method to consume more
+ * time and system resources.
+ * @param aBytesToWrite Number of bytes the caller is about to write to
+ * FFS. If value 0 is given, this method checks
+ * if the current FFS space is already below critical
+ * level.
+ *
+ * @return ETrue if FFS space would go below critical level after writing
+ * aBytesToWrite more data, EFalse otherwise.
+ *
+ * @leave Leaves with one of the Symbian error codes if checking the FFS
+ * space fails, for instance if there is not enough free memory to
+ * create a temporary connection to file server.
+ */
+ IMPORT_C static TBool FFSSpaceBelowCriticalLevelL(
+ RFs* aFs,
+ TInt aBytesToWrite = 0 );
+
+
+ /**
+ * Checks if free MMC storage space is or will fall below critical
+ * level. Static configuration value stored in Central Repository is
+ * used to determine the critical level for the MMC drive.
+ * PathInfo API is used to determine the drive letter for the MMC drive.
+ *
+ * @since S60 v2.0
+ *
+ * @param aFs File server session. Must be given if available, e.g. from
+ * EIKON environment. If NULL, this method will create a
+ * temporary session, which causes the method to consume more
+ * time and system resources.
+ * @param aBytesToWrite Number of bytes the caller is about to write to
+ * MMC. If value 0 is given, this method checks
+ * if the current MMC space is already below critical
+ * level.
+ *
+ * @return ETrue if MMC space would go below critical level after writing
+ * aBytesToWrite more data, EFalse otherwise.
+ * EFalse if the system has no MMC drive support.
+ *
+ * @leave Leaves with one of the Symbian error codes if checking the MMC
+ * space fails, for instance if the MMC drive contains no media or
+ * there is not enough free memory to create a temporary connection to
+ * file server.
+ */
+ IMPORT_C static TBool MMCSpaceBelowCriticalLevelL(
+ RFs* aFs,
+ TInt aBytesToWrite = 0 );
+
+ /**
+ * Checks if free disk drive storage space is or will fall below critical
+ * level. Static configuration values stored in Central Repository are
+ * used to determine a critical level for each drive.
+ *
+ * Usage example:
+ * @code
+ * TInt dataSize = 500;
+ * if ( SysUtil::DiskSpaceBelowCriticalLevelL( &iFsSession, dataSize, EDriveC ) )
+ * {
+ * // Can not write the data, there's not enough free space on disk.
+ * ...
+ * }
+ * else
+ * {
+ * // It's ok to actually write the data.
+ * ...
+ * }
+ * @endcode
+ *
+ * @since S60 v2.0
+ *
+ * @param aFs File server session. Must be given if available, e.g. from
+ * EIKON environment. If NULL, this method will create a
+ * temporary session, which causes the method to consume more
+ * time and system resources.
+ * @param aBytesToWrite Number of bytes the caller is about to write to
+ * disk. If value 0 is given, this method checks
+ * if the current disk space is already below critical
+ * level.
+ * @param aDrive Identifies the disk drive to be checked. Numeric values
+ * for identifying disk drives are defined in TDriveNumber
+ * enumeration.
+ *
+ * @see TDriveNumber in f32file.h.
+ *
+ * @return ETrue if disk space would go below critical level after writing
+ * aBytesToWrite more data, EFalse otherwise.
+ *
+ * @leave Leaves with one of the Symbian error codes if checking the disk
+ * space fails, for instance if the drive contains no media or there
+ * is not enough free memory to create a temporary connection to
+ * file server.
+ */
+ IMPORT_C static TBool DiskSpaceBelowCriticalLevelL(
+ RFs* aFs,
+ TInt aBytesToWrite,
+ TInt aDrive );
+
+ };
+
+#endif // SYSUTIL_H