/*

* 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.

 */