diff -r 000000000000 -r ba25891c3a9e ncdengine/inc/catalogsutils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ncdengine/inc/catalogsutils.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,840 @@ +/* +* 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 +#include +#include +#include + +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 +void IntToDes16( const T& aInt, TDes& aDes ); + + +template<> +void IntToDes16( 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 +void Des16ToInt( const TDesC& aDes, T& aInt ); + +template<> +void Des16ToInt( 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 +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 +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 +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 +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 +void ResetAndCloseArray( RPointerArray& aArray ); + +template +void ResetAndCloseArray( RArray& 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 +void ResetAndDestroyWithCast( RPointerArray& aArray ); + + +template +void DeleteFromArray( RPointerArray& aArray, TInt aIndex ); + +template +void DeleteFromArray( RPointerArray& aArray, TInt aIndex ); + + +/** + * Internalizes an enumeration from the given stream + * + * @note Enumeration is read as a TInt32 + */ +template +void InternalizeEnumL( EnumType& aTarget, RReadStream& aReadStream ); + +/** + * Externalizes an enumeration to the given stream + * + * @note Enumeration is written as a TInt32 + */ +template +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 +TBool IsOneOf( const T& aData, const T& aComp1, const T& aComp2 ); + +template +TBool IsOneOf( const T& aData, const T& aComp1, const T& aComp2, const T& aComp3 ); + +template +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 +void ReleasePtr( T*& aObject ); + + +/** + * Closes the object and sets the pointer as NULL + */ +template +void ClosePtr( T*& aObject ); + + +/** + * Deletes the object and sets the pointer as NULL + */ +template +void DeletePtr( T*& aObject ); + + +#include "catalogsutils.inl" + +#endif // T_CATALOGSUTILS_H