SysUtil Class Reference

#include <bafl/sysutil.h>

Link against: sysutil.lib

class SysUtil
Public Member Functions
IMPORT_C TBoolDiskSpaceBelowCriticalLevelL(RFs *, TInt64, TInt)
IMPORT_C TBoolFFSSpaceBelowCriticalLevelL(RFs *, TInt64)
IMPORT_C CDeviceTypeInformation *GetDeviceTypeInfoL()
IMPORT_C TIntGetFFSDriveLetter(RFs &)
IMPORT_C TIntGetLangSWVersion(TDes &)
IMPORT_C TIntGetLangVersion(TDes &)
IMPORT_C TIntGetMMCDriveLetter(RFs &)
IMPORT_C TIntGetPRInformation(TDes &)
IMPORT_C TIntGetSWVersion(TDes &)
IMPORT_C TBoolMMCSpaceBelowCriticalLevelL(RFs *, TInt64)

Detailed Description

SysUtil provides various system utility methods, as follows:

  • Functions for applications to retrieve SW and language package versions strings for display purposes

  • Functions to check whether there is free space on a disk drive before file creation or writing.

  • Functions to retrieve Device Type information (e.g. phone model) for display purposes.

Version, Attribute strings and free space thresholds are provisioned by the device creator into the ROM. For details on this see the 'SGL.TS0017.324 BAFL How-To FAQ Document' in the OS Developer Library.

Member Function Documentation

DiskSpaceBelowCriticalLevelL ( RFs *, TInt64, TInt )

IMPORT_C TBoolDiskSpaceBelowCriticalLevelL(RFs *aFs,
TInt64aBytesToWrite,
TIntaDrive
)[static]

Checks if free disk drive storage space is or will fall below critical level.

To calculate if a critical level has been reached the critical level threshold setting will be used. This setting is available in the patchable data.

RAM drives and non-RAM drives have different threshold levels, so the corresponding setting will be used for the calculation depending on the drive type.

RAM drives are defined to be drives that have the media type of EMediaRam as returned by RFs.

See also: RFs::Drive

To set the patchdata for the RAM drive threshold set the MACRO SYMBIAN_BAFL_SYSUTIL_RAM_DRIVE_CRITICAL_THRESHOLD at ROM build time to an appropriate level. To set the patchdata for the non-RAM drive threshold set the MACRO SYMBIAN_BAFL_SYSUTIL_OTHER_DISK_CRITICAL_THRESHOLD at ROM build time to an appropriate level.

Usage example: 
TInt64 dataSize = 500000000;
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.
    ...
    }

See also: TDriveNumber in f32file.h.

leave
System wide error codes
ParameterDescription
aFsFile 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.
aBytesToWriteNumber 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.
aDriveIdentifies the disk drive to be checked. Numeric values for identifying disk drives are defined in TDriveNumber enumeration.

Returns: ETrue if disk space would go below critical level after writing aBytesToWrite more data, EFalse otherwise.

FFSSpaceBelowCriticalLevelL ( RFs *, TInt64 )

IMPORT_C TBoolFFSSpaceBelowCriticalLevelL(RFs *aFs,
TInt64aBytesToWrite = 0
)[static]

Checks if free system drive storage space is or will fall below critical level. The system drive (internal, read/write, persistent drive) is also known as the FFS (internal flash file system).

To calculate if a critical level has been reached the critical level threshold setting will be used. This setting is available in the patchable data.

RAM drives and non-RAM drives have different threshold levels, so the corresponding setting will be used for the calculation depending on the drive type.

RAM drives are defined to be drives that have the media type of EMediaRam as returned by RFs.

See also: RFs::Drive

To set the patchdata for the RAM drive threshold set the MACRO SYMBIAN_BAFL_SYSUTIL_RAM_DRIVE_CRITICAL_THRESHOLD at ROM build time to an appropriate level. To set the patchdata for the non-RAM drive threshold set the MACRO SYMBIAN_BAFL_SYSUTIL_OTHER_DISK_CRITICAL_THRESHOLD at ROM build time to an appropriate level.

This method also needs to determine which drive is the FFS drive. To do this patchable data has been provided. If the patchable data has not been set, then RFs::GetSystemDrive() will be used to determine the FFS drive.

To set the patchdata to the FFS drive set the MACRO SYMBIAN_BAFL_SYSUTIL_DEFAULT_FFS_DRIVE to the appropriate drive letter.

See also: TDriveNumber

leave
System wide error codes
ParameterDescription
aFsFile 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.
aBytesToWriteNumber of bytes the caller is about to write to the system drive. If value 0 is given, this method checks if the current system drive space is already below critical level.

Returns: ETrue if system drive space would go below critical level after writing aBytesToWrite more data, EFalse otherwise.

GetDeviceTypeInfoL ( )

IMPORT_C CDeviceTypeInformation *GetDeviceTypeInfoL()[static]

Creates and returns a populated CDeviceTypeInformation object which is used to access the device type information attributes.

All the attributes are provisioned by the device creator.

The returned object is owned by the calling code and so it is the calling codes responsibility to delete this object when it no longer requires it.

leave
KErrNoMemory If there is not enough memory to create the object.
leave
KErrNotReady If there was a problem retrieving the device type information attributes.
leave

  • Otherwise one of the other system-wide error codes.

See also: CDeviceTypeInformation

Returns: CDeviceTypeInformation* A pointer to an instance of CDeviceTypeInformation.

GetFFSDriveLetter ( RFs & )

IMPORT_C TIntGetFFSDriveLetter(RFs &aFs)[static]

Returns the FFS drive letter

This method determines which drive is the FFS drive. To do this a patchable data has been provided. If the patchable data has not been set, then the drive will be fetched via a call to GetSystemDrive().

To set the patchdata to the FFS drive set the MACRO SYMBIAN_BAFL_SYSUTIL_DEFAULT_FFS_DRIVE to the appropriate drive letter.

See also: TDriveNumber

Returns: TInt the integer value equivalent of the TDriveNumber

GetLangSWVersion ( TDes & )

IMPORT_C TIntGetLangSWVersion(TDes &aValue)[static]

Returns displayable software version which the currently installed language package is compatible with.

This version text is provisioned by the device creator into the ROM as a Unicode UTF16 format displayable string, for example:

V 1.0\n29-07-07\nBuild12345\n(c) Symbian Software

This provisioned text string contains only one line of text with "\n" sequences in the text which indicate a new line. This API will parse the text and remove any "\n" sequences that it finds and replace it with the Unicode newline sequence - 0x000A. The resulting buffer is then a unicode string with newline sequences built in. This then can for example, allow the buffer to be displayed directly to the screen already formatted on multiple lines.

ParameterDescription
aValueOn return, contains the software version string. The buffer should have space for KSysUtilVersionTextLength characters. If the buffer is insufficient the descriptor is filled to its maximum length. If a buffer is provided that is longer than 64 characters, and the provisioned text is larger than 64 characters, the returned buffer is truncated at 64 characters (see error codes below).

Returns: KErrNone on success, KErrTooBig if the maximum length of the descriptor is insufficient to hold the provisioned text, or has been truncated (see above). In both cases new-line processing is done on the buffers. If a zero length text string has been provisioned KErrEof is returned, and the length of the buffer is set to zero. If none of these cases apply then one of the Symbian error codes is returned if reading the version string fails.

GetLangVersion ( TDes & )

IMPORT_C TIntGetLangVersion(TDes &aValue)[static]

Obtains the displayable version of the currently installed language package. This does NOT do any newline processing on the version text. (unlike, for example GetLangSWVersion() or GetSWVersion()).

This version text is provisioned by the device creator into the ROM as a Unicode UTF16 format displayable string.

ParameterDescription
aValueOn return, contains the software version string. The buffer should have space for KSysUtilVersionTextLength characters. If the buffer is insufficient the descriptor is filled to its maximum length. If a buffer is provided that is longer than 64 characters, and the provisioned text is larger than 64 characters, the returned buffer is truncated at 64 characters (see error codes below).

Returns: KErrNone on success, KErrTooBig if the maximum length of the descriptor is insufficient to hold the provisioned text, or has been truncated (see above). In both cases new-line processing is done on the buffers. If a zero length text string has been provisioned KErrEof is returned, and the length of the buffer is set to zero. If none of these cases apply then one of the Symbian error codes is returned if reading the version string fails.

GetMMCDriveLetter ( RFs & )

IMPORT_C TIntGetMMCDriveLetter(RFs &aFs)[static]

Returns the MMC drive letter

This method determines which drive is the MMC drive. To do this a patchable data has been provided.

To set the patchdata to the MMC drive set the MACRO SYMBIAN_BAFL_SYSUTIL_DEFAULT_MMC_DRIVE to the appropriate drive letter.

See also: TDriveNumber

Returns: TInt the integer value equivalent of the TDriveNumber

GetPRInformation ( TDes & )

IMPORT_C TIntGetPRInformation(TDes &aValue)[static]

Obtains the displayable product release information string.

Usage example: 
TBuf<KSysUtilVersionTextLength> prInfo;
if ( SysUtil::GetPRInformation( prInfo ) == KErrNone )
    {
    // Use the version string.
    ...
    }
The product release information is provisioned by the device creator into the ROM as a Unicode UTF16 format displayable string, for example:

custom build fix xyz or PR1.0 or PR1.1

This provisioned text string contains only one line of text with "\n" sequences in the text which indicate a new line. This API will parse the text and remove any "\n" sequences that it finds and replace it with the Unicode newline sequence - 0x000A. The resulting buffer is then a unicode string with newline sequences built in. This then can for example, allow the buffer to be displayed directly to the screen already formatted on multiple lines.

ParameterDescription
aValueOn return, contains the product release information string. The buffer should have space for KSysUtilVersionTextLength characters. If the buffer is insufficient the descriptor is filled to its maximum length. If a buffer is provided that is longer than 64 characters, and the provisioned text is larger than 64 characters, the returned buffer is truncated at 64 characters.

Returns: KErrNone on success, KErrTooBig if the maximum length of the descriptor is insufficient to hold the provisioned text, or has been truncated. In both cases new-line processing is done on the buffers. If a zero length text string has been provisioned KErrEof is returned, and the length of the buffer is set to zero. If none of these cases apply then one of the Symbian error codes is returned if reading the product release string fails.

GetSWVersion ( TDes & )

IMPORT_C TIntGetSWVersion(TDes &aValue)[static]

Obtains the displayable software version string.

Usage example: 
TBuf<KSysUtilVersionTextLength> version;
if ( SysUtil::GetSWVersion( version ) == KErrNone )
	{
	// Use the version string.
	...
	}
The software version is provisioned by the device creator into the ROM as a Unicode UTF16 format displayable string, for example:

V 1.0\n29-07-07\nBuild12345\n(c) Symbian Software

This provisioned text string contains only one line of text with "\n" sequences in the text which indicate a new line. This API will parse the text and remove any "\n" sequences that it finds and replace it with the Unicode newline sequence - 0x000A. The resulting buffer is then a unicode string with newline sequences built in. This then can for example, allow the buffer to be displayed directly to the screen already formatted on multiple lines.

ParameterDescription
aValueOn return, contains the software version string. The buffer should have space for KSysUtilVersionTextLength characters. If the buffer is insufficient the descriptor is filled to its maximum length. If a buffer is provided that is longer than 64 characters, and the provisioned text is larger than 64 characters, the returned buffer is truncated at 64 characters (see error codes below).

Returns: KErrNone on success, KErrTooBig if the maximum length of the descriptor is insufficient to hold the provisioned text, or has been truncated (see above). In both cases new-line processing is done on the buffers. If a zero length text string has been provisioned KErrEof is returned, and the length of the buffer is set to zero. If none of these cases apply then one of the Symbian error codes is returned if reading the version string fails.

MMCSpaceBelowCriticalLevelL ( RFs *, TInt64 )

IMPORT_C TBoolMMCSpaceBelowCriticalLevelL(RFs *aFs,
TInt64aBytesToWrite = 0
)[static]

Checks if free MMC storage space is or will fall below critical level.

To calculate if a critical level has been reached the critical level threshold setting will be used. This setting is available in the patchable data.

RAM drives and non-RAM drives have different threshold levels, so the corresponding setting will be used for the calculation depending on the drive type.

RAM drives are defined to be drives that have the media type of EMediaRam as returned by RFs.

See also: RFs::Drive

This method also needs to determine which drive is the MMC drive. To do this a patchable data has been provided. If the patchable data has not been set, then the drive will be fetched using BSUL.

See also: CCachedDriveInfo

To set the patchdata for the RAM drive threshold set the MACRO SYMBIAN_BAFL_SYSUTIL_RAM_DRIVE_CRITICAL_THRESHOLD at ROM build time to an appropriate level. To set the patchdata for the non-RAM drive threshold set the MACRO SYMBIAN_BAFL_SYSUTIL_OTHER_DISK_CRITICAL_THRESHOLD at ROM build time to an appropriate level.

To set the patchdata to the MMC drive set the MACRO SYMBIAN_BAFL_SYSUTIL_DEFAULT_MMC_DRIVE to the appropriate drive letter.

See also: TDriveNumber

leave
KErrNotFound if the MMC drive cannot be found, otherwise one of the system-wide error codes.
ParameterDescription
aFsFile 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.
aBytesToWriteNumber 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.

Returns: ETrue if MMC space would go below critical level after writing aBytesToWrite more data, EFalse otherwise.

© Nokia 2011.