/*

* 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