/*
* Copyright (c) 2006-2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/
#ifndef T_CATALOGSUTILS_H
#define T_CATALOGSUTILS_H
#include <badesca.h>
#include <s32strm.h>
#include <s32mem.h>
#include <f32file.h>
class RFs;
class RWriteStream;
class RReadStream;
class MCatalogsBaseMessage;
class RFile;
/**
* TVersion class has size restrictions and is not suitable to represent SIS
* file versions. TCatalogsVersion has higher limits for the version values.
*/
class TCatalogsVersion
{
public:
/**
* Converts a descriptor to TCatalogsVersion
*
* @leave KErrArgument if at least major number is not in aVersion
* @leave KErrGeneral if aVersion doesn't contain valid characters
*/
static void ConvertL( TCatalogsVersion& aTarget, const TDesC& aVersion );
/**
* Converts a version string to a descriptor
*/
static HBufC* ConvertLC( const TCatalogsVersion& aSource );
/**
* Initializes version to 0.0.0
*/
TCatalogsVersion();
/**
* Initializes version
*
* @param aMajor Major version number
* @param aMinor Minor version number
* @param aBuild Build version number
* @return
*/
TCatalogsVersion( TUint16 aMajor, TUint16 aMinor, TUint32 aBuild );
/**
* Comparison operator
*
* @aVersion Version to compare with
* @param ETrue if the versions are equal
*/
TBool operator==( const TCatalogsVersion& aVersion ) const;
/**
* Greater than -operator
*
* @param aVersion Version to compare with
* @return ETrue if the current version is greater than
* the version given as a parameter
*/
TBool operator>( const TCatalogsVersion& aVersion ) const;
/**
* Equar or greater than -operator
*
* @param aVersion Version to compare with
* @return ETrue if the current version is equal with or greater than
* the version given as a parameter
*/
TBool operator>=( const TCatalogsVersion& aVersion ) const;
inline TBool operator!=( const TCatalogsVersion& aVersion ) const
{
return !operator==( aVersion );
}
public:
TUint16 iMajor;
TUint16 iMinor;
TUint32 iBuild;
};
#ifndef NCD_STORAGE_TESTING
/**
* Utility class for reading data from MCatalogsBaseMessages
*
* Use CleanupClosePushL when pushing this object to cleanupstack
*
* Basic usage:
*
* @code
* void FunctionThatUsesAMessage( MCatalogsBaseMessage& aMessage )
* {
* ...
* RCatalogsMessageReader reader;
* reader.OpenLC( aMessage );
* TInt32 intFromMessage = reader().ReadInt32();
* ...
* CleanupStack::PopAndDestroy( &reader );
* ...
* @endcode
*/
class RCatalogsMessageReader
{
public:
/**
* Constructor
*/
RCatalogsMessageReader();
/**
* Opens the stream for reading.
*
* @param aMessage Message to read from
* @note This object must be Closed when it's not used anymore
*/
void OpenL( MCatalogsBaseMessage& aMessage );
/**
* Opens the stream for reading and pushes the reader to cleanupstack
*
* @param aMessage Message to read from
*/
void OpenLC( MCatalogsBaseMessage& aMessage );
/**
* Closes the object
*/
void Close();
/**
* Destructor
*/
virtual ~RCatalogsMessageReader();
/**
* Stream getter
*/
RReadStream& operator()()
{
return iStream;
}
protected:
RCatalogsMessageReader( const RCatalogsMessageReader& );
RCatalogsMessageReader& operator=( const RCatalogsMessageReader& );
private:
RBuf8 iBuf;
RDesReadStream iStream;
};
#endif
/**
* Utility class for writing to a buffer
*
* Usage:
*
* @code
* RCatalogsBufferWriter writer;
* writer.OpenLC();
* writer().WriteInt32L( 64 );
* ExternalizeDesL( myDescriptor, writer() );
* ...
* TPtr8 ptr( writer->PtrL() );
* // use the pointer
* ...
* CleanupStack::PopAndDestroy( &writer );
* @endcode
*/
class RCatalogsBufferWriter
{
public:
/**
* Constructor
*/
RCatalogsBufferWriter();
/**
* Opens the stream for writing.
*
* @note This object must be Closed when it's not used anymore
*/
void OpenL();
/**
* Opens the stream for writing and pushes the writer to cleanupstack
*
*/
void OpenLC();
/**
* Closes the object
*/
void Close();
/**
* Destructor
*/
virtual ~RCatalogsBufferWriter();
/**
* Stream getter
*/
RWriteStream& operator()()
{
return iStream;
}
/**
* Written buffer
*/
TPtr8 PtrL()
{
iStream.CommitL();
return iBuf->Ptr( 0 );
}
protected:
RCatalogsBufferWriter( const RCatalogsBufferWriter& );
RCatalogsBufferWriter& operator=( const RCatalogsBufferWriter& );
private:
CBufBase* iBuf;
RBufWriteStream iStream;
};
/**
* Copies a descriptor to a heap descriptor.
*
* @param aDes Destination heap descriptor.
* @param aSource Source descriptor.
*/
void AssignDesL( HBufC8*& aDes, const TDesC8& aSource );
/**
* Copies a descriptor to a heap descriptor.
*
* @param aDes Destination heap descriptor.
* @param aSource Source descriptor.
*/
void AssignDesL( HBufC16*& aDes, const TDesC16& aSource );
/**
* Copies a UTF-8 descriptor to a unicode heap descriptor.
*
* @param aDes Destination heap descriptor.
* @param aSource Source descriptor.
*/
void AssignDesL( HBufC16*& aDes, const TDesC8& aSource );
/**
* Converts a utf8 descriptor into unicode.
*
* @param aUtfText Source data
* @return HBufC16* Converted data
*/
HBufC16* ConvertUtf8ToUnicodeL( const TDesC8& aUtfText );
/**
* Converts a unicode descriptor into utf8.
*
* @param aUnicodeText Source data
* @return HBufC8* Converted data
*/
HBufC8* ConvertUnicodeToUtf8L( const TDesC16& aUnicodeText );
/**
* Converts a 16-bit des to a 8-bit des by TRUNCATING(!) data.
* Creates readable text: _L16("abc") -> _L8("abc")
*
* @param aDes Source data
* @return HBufC8* Dynamically allocated buffer containing the converted data.
*/
HBufC8* Des16ToDes8LC( const TDesC16& aDes );
/**
* Converts a 16-bit des to a 8-bit des by TRUNCATING(!) data.
* Creates readable text: _L16("abc") -> _L8("abc")
*
* @param aDes Source data
* @return HBufC8* Dynamically allocated buffer containing the converted data.
*/
HBufC8* Des16ToDes8L( const TDesC16& aDes );
/**
* Converts a 8-bit des to a 16-bit des by adding empty 8 bits to every byte.
* Creates readable text: _L8("abc") -> _L16("abc")
*
* @param aDes Source data
* @return HBufC16* Dynamically allocated buffer containing the converted data.
*/
HBufC16* Des8ToDes16LC( const TDesC8& aDes );
/**
* Converts a 8-bit des to a 16-bit des by adding empty 8 bits to every byte.
* Creates readable text: _L8("abc") -> _L16("abc")
*
* @param aDes Source data
* @return HBufC16* Dynamically allocated buffer containing the converted data.
*/
HBufC16* Des8ToDes16L( const TDesC8& aDes );
/**
* Converts descriptor containing decimal number to an integer.
*
* @param aDes Descriptor representation of a decimal.
* @return TInt Converted integer.
*/
TInt DesDecToIntL( const TDesC& aDes );
/**
* Converts descriptor containing decimal number to an integer.
*
* @param aDes Descriptor containing the decimal number.
* @param aValue Integer where the outcome is put.
* @return Symbian error-code as a conversion outcome.
*/
TInt DesDecToInt( const TDesC8& aDes, TInt& aValue );
/**
* Converts descriptor containing decimal number to an integer.
*
* @param aDes Descriptor containing the decimal number.
* @param aValue Integer where the outcome is put.
* @return Symbian error-code as a conversion outcome.
*/
TInt DesDecToInt( const TDesC16& aDes, TInt& aValue );
/**
* Converts descriptor containing hexadecimal number to an integer.
* Accepts "ABCD" and "0xABCD" format numbers.
* Leaves if corrupt parameter.
* @param aDes Descriptor representation of a hexadecimal.
* @return TInt Converted integer.
*/
TInt DesHexToIntL( const TDesC& aDes );
/**
* Converts the raw contents of a 8-bit descriptor into an integer.
*
* @param aDes Descriptor containing a raw number.
* @return Int Converted number
*/
TInt Des8ToInt( const TDesC8& aDes );
/**
* Converts the raw contents of a 8-bit descriptor into an unsigned integer.
*
* @param aDes Descriptor containing a raw number.
* @return Uint Converted number
*/
TUint Des8ToUint( const TDesC8& aDes );
/**
* Converts an integer into a 8-bit descriptor.
* NOTE: the number will not be in text format.
*
* @param aInt Number to convert
* @return Dynamically allocated buffer containing the data
*/
HBufC8* IntToDes8LC( TInt aInt );
/**
* Converts an integer into a 8-bit descriptor.
* NOTE: the number will not be in text format.
*
* @param aInt Number to convert
* @return Dynamically allocated buffer containing the data
*/
HBufC8* IntToDes8L( TInt aInt );
/**
* Converts an unsigned integer into a 8-bit descriptor.
* NOTE: the number will not be in text format.
*
* @param aUint Number to convert
* @return Dynamically allocated buffer containing the data
*/
HBufC8* UintToDes8LC( TUint aUint );
/**
* Converts an unsigned integer into a 8-bit descriptor.
* NOTE: the number will not be in text format.
*
* @param aUint Number to convert
* @return Dynamically allocated buffer containing the data
*/
HBufC8* UintToDes8L( TUint aUint );
/**
* Converts an integer into a 16-bit descriptor.
*
* The required length for the target descriptor depends on the used integer.
*
* For 8- and 16-bit integers the length of the descriptor must be at least 1
* For 32-bit integers the length of the descriptor must be at least 2
* and for 64-bit integers it must be at least 4.
*
* @note The number will not be in text format.
* @note The number can be unsigned or signed and 8, 16, 32 or 64 bit.
*
*
* @param aInt Number to convert.
* @param aDes Target descriptor. Length must be at least
*/
template<typename T>
void IntToDes16( const T& aInt, TDes& aDes );
template<>
void IntToDes16<TInt64>( const TInt64& aInt, TDes& aDes );
/**
* Converts the raw contents of a 16-bit descriptor into an integer.
* @note The number will not be in text format.
* @note The number can be unsigned or signed and 8, 16, 32 or 64 bit.
*
* @param aDes Source descriptor. Length must be at least 1 for 8 and 16-bit
* integers, 2 for 32-bit integers and 4 for 64-bit integers.
* @param aInt Number to convert.
*/
template<typename T>
void Des16ToInt( const TDesC& aDes, T& aInt );
template<>
void Des16ToInt<TInt64>( const TDesC& aDes, TInt64& aInt );
/**
* Externalizes the descriptor to the stream with length information
*
* @param aDes Descriptor to externalize
* @param aStream Target stream
*/
void ExternalizeDesL( const TDesC16& aDes, RWriteStream& aStream );
/**
* Internalizes a descriptor written with ExternalizeDesL() from the stream
*
* @param Target descriptor pointer. Old descriptor is deleted if the read is
* successful and the length of the data was > 0.
* @param aStream Source stream
* @return Length of the read data
*/
TInt InternalizeDesL( HBufC16*& aDes, RReadStream& aStream );
/**
* Externalizes the descriptor to the stream with length information
*
* @param aDes Descriptor to externalize
* @param aStream Target stream
*/
void ExternalizeDesL( const TDesC8& aDes, RWriteStream& aStream );
/**
* Internalizes a descriptor written with ExternalizeDesL() from the stream
*
* @param Target descriptor pointer. Old descriptor is deleted if the read is
* successful and the length of the data was > 0.
* @param aStream Source stream
* @return Length of the read data
*/
TInt InternalizeDesL( HBufC8*& aDes, RReadStream& aStream );
/**
* Returns the path where the Engine data has been installed.
* Examples:
* c:\private\12345678\
* z:\private\DEADBEEF\
*
* @return TPath Engine path.
*/
TPath EnginePathL( RFs& aFs );
/**
* Returns the path where the Engine may write data.
* Examples:
* c:\private\12345678\
*
* @return TPath Path where the engine may write data.
*/
TPath WritableEnginePathL( RFs& aFs );
/**
* Searches for the given file from engine's private paths
*
* @param aFs File server session
* @param aFilename File to search for
* @return Path to the file
* @leave KErrNotFound if the file was not found
*/
HBufC* FindEngineFileL( RFs& aFs, const TDesC& aFilename );
/**
* Checks whether a drive is a rom drive, and thus not writable.
*
* @param aFs File server session
* @param aDriveChar Drive to check, ie. C,D,E,..,Z
* @return ETrue if drive is ROM.
*/
TBool IsRomDriveL( RFs& aFs, TChar aDriveChar );
/**
* Converts a drive number into a drive letter.
*
* @param aDrive Drive number
* @return TChar Drive letter
*/
TChar DriveToCharL( TInt aDrive );
/**
* Gives the root path of a given drive.
*
* @param aFs File server session
* @param aDriveChar Drive to check, ie. C,D,E,..,Z
* @return HBufC* Root path of the drive.
* (Notice, this is not necessarily C:\ but can be, for example,
* C:\data.)
*/
HBufC* DriveRootPathLC( RFs& aFs, const TChar& aDriveLetter );
/**
* Converts symbian language codes to java form (e.g. ELangEnglish -> "en-EN")
*
* @param aLang Language code
* @return HBufC* Language string in java form.
*/
HBufC* LangCodeToDescLC( TLanguage aLang );
/**
* Removes [ and ] from the UID name
*
* @param aUid UID
* @return UID in a descriptor without [ and ]
*/
TUidName CleanUidName( const TUid& aUid );
/**
* Encodes a filename so that it can safely be used within
* the filesystem by replacing certain characters.
* @param aFileName Filename to be encoded
* @return HBufC* Encoded filename
*/
HBufC* EncodeFilenameLC( const TDesC& aFileName, RFs& aFs );
/**
* Creates a private directory on the designated drive
* @param aFs File server session
* @param aDriveAndColon Drive letter and a colon, eg. "C:"
* @param aPath Created directory path including drive
*/
void CreatePrivatePathL( RFs& aFs, const TDesC& aDriveAndColon, TDes& aPath );
/**
* Returns maximum amount of free space on devices drive (flash or hd).
*
* @param aFs File server session
* @param aDriveNumber Drive number.
* @return TInt64 Amount of free space.
*/
TInt64 FreeDiskSpaceL( RFs& aFs, TInt aDriveNumber );
#ifndef USE_MMF_RESET_AND_DESTROY_PUSHL
/**
* A utility class used by the templated function CleanupResetAndDestroyPushL()
* to create a TCleanupItem item that will perform a ResetAndDestroy type
* operation on the class T type object.
*
* @see CleanupResetAndDestroyPushL()
*/
template <typename T>
class CleanupResetAndDestroy
{
public:
inline static void PushL(T& aRef);
private:
static void ResetAndDestroy(TAny *aPtr);
};
/**
* Pushes the given item to cleanupstack and calls ResetAndDestroy() to it
* in PopAndDestroy or in case a leave occurs.
*/
template <typename T>
inline void CleanupResetAndDestroyPushL(T& aRef);
#endif // USE_MMF_RESET_AND_DESTROY_PUSHL
/**
* A utility class used by the templated function CleanupInternalReleasePushL()
* to create a TCleanupItem item that will perform a InternalRelease operation
* on th eclass T type object.
*
* @see CleanupInternalReleasePushL()
*/
template <typename T>
class CleanupInternalRelease
{
public:
inline static void PushL( T& aRef );
private:
static void InternalRelease( TAny* aPtr );
};
/**
* Pushes the given item to cleanupstack and calls InternalRelease() to it
* in PopAndDestroy or in case a leave occurs.
*/
template <typename T>
inline void CleanupInternalReleasePushL( T& aRef );
/**
* Checks whether the given uri uses https shceme.
*
* @return ETrue if uri is https, EFalse if not.
*/
TBool IsHttpsUri( const TDesC& aUri );
/**
* Retrieves the bytes allocated by the directory in the filesystem.
* @param aFs File server session
* @param aDir Directory
* @return TInt Allocation in bytes.
*/
TInt FileSystemAllocationL( RFs& aFs, const TDesC& aDir );
/**
* Reads a file to the 8-bit descriptor.
*
* @param aFs Reference to the fileserver session.
* @param aFileName File name.
* @return HBufC8* Dynamically allocated descriptor containing the file data.
*/
HBufC8* ReadFileL( RFs& aFs, const TDesC& aFileName );
/**
* Reads a file to the 8-bit descriptor.
*
* @param aFile An opened file handle. Must be closed by the caller
* @return HBufC8* Dynamically allocated descriptor containing the file data.
*/
HBufC8* ReadFileL( RFile& aFile );
/**
* Checks if the disk space would go below critical if the given amount
* of data was written to disk
*
* @param aPath Path to check (only drive letter is mandatory)
* @param aFs File server session
* @param aSpaceNeeded Needed space
* @leave KErrDiskFull if there is not enough space
*/
void WouldDiskSpaceGoBelowCriticalLevelL( const TDesC& aPath,
RFs& aFs,
TInt aSpaceNeeded );
/**
* Converts a version string of format "1.2.3" or "1.2" or "1" to version components.
*
* @param aStr Version string
* @param aMajor On return contains the major version
* @param aMinor On return contains the minor version or 0 it not available
* @param aBuild On return contains the build number or 0 if not available.
*/
void DesToVersionL( const TDesC& aVersion,
TUint16& aMajor, TUint16& aMinor, TUint32& aBuild );
/**
* Function that calls close for each element of given array once.
* In the end this function calls reset for the array.
*
*/
template <typename T>
void ResetAndCloseArray( RPointerArray<T>& aArray );
template <typename T>
void ResetAndCloseArray( RArray<T>& aArray );
/**
* Function that casts each element as T and then calls delete for it.
* In the end this function calls reset for the array.
*/
template <typename Casted, typename T >
void ResetAndDestroyWithCast( RPointerArray<T>& aArray );
template <typename T>
void DeleteFromArray( RPointerArray<T>& aArray, TInt aIndex );
template <typename Casted, typename T>
void DeleteFromArray( RPointerArray<T>& aArray, TInt aIndex );
/**
* Internalizes an enumeration from the given stream
*
* @note Enumeration is read as a TInt32
*/
template <typename EnumType>
void InternalizeEnumL( EnumType& aTarget, RReadStream& aReadStream );
/**
* Externalizes an enumeration to the given stream
*
* @note Enumeration is written as a TInt32
*/
template <typename EnumType>
void ExternalizeEnumL( const EnumType& aSource, RWriteStream& aWriteStream );
/**
* Appends aRoot with aAppendPath and puts them to aPath
*
* @param aPath RBuf without any allocated memory. This is put to CleanupStack
* @param aRoot First path. Should contain the path delimiter at the end.
* @param aAppendPath Second path. Appended to aRoot
*/
void AppendPathsLC(
RBuf& aPath,
const TDesC& aRoot,
const TDesC& aAppendPath );
/**
* Helper methods that leave if aError != KErrNone and aError != aAcceptErr
*/
void LeaveIfNotErrorL( TInt aError, TInt aAcceptErr );
void LeaveIfNotErrorL( TInt aError, TInt aAcceptErr, TInt aAcceptErr2 );
void LeaveIfNotErrorL( TInt aError, TInt aAcceptErr, TInt aAcceptErr2,
TInt aAcceptErr3 );
/**
* Opens a file or creates it if it doesn't already exist
*/
void OpenOrCreateFileL(
RFs& aFs, RFile& aFile, const TDesC& aFilePath, TUint aFileMode );
/**
* Checks if aData == aComp1 or aData == aComp2
* Can be used for simplifying horrendous if-clauses
*/
template <typename T>
TBool IsOneOf( const T& aData, const T& aComp1, const T& aComp2 );
template <typename T>
TBool IsOneOf( const T& aData, const T& aComp1, const T& aComp2, const T& aComp3 );
template <typename T>
TBool IsOneOf( const T& aData, const T& aComp1, const T& aComp2,
const T& aComp3, const T& aComp4 );
/**
* Releases the object and sets the pointer as NULL
*/
template <typename T>
void ReleasePtr( T*& aObject );
/**
* Closes the object and sets the pointer as NULL
*/
template <typename T>
void ClosePtr( T*& aObject );
/**
* Deletes the object and sets the pointer as NULL
*/
template <typename T>
void DeletePtr( T*& aObject );
#include "catalogsutils.inl"
#endif // T_CATALOGSUTILS_H