/*
* Copyright (c) 2003-2009 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:
* Name        : SigComp.h
* Part of     : SigComp
* Interface   : 
* main sigcomp class, sigcomp public API.
* Version     : 1.0
*
*/



#ifndef CSIGCOMP_H
#define CSIGCOMP_H

//  INCLUDES
#include <e32base.h>

// FORWARD DECLARATIONS
class CSigCompCompartment;
class TSigCompStateItem;
class CUdvm;
class CStateMgr;
class CSigCompCompressor;
class TStateItem;

// CONSTANTS
const TInt KSigCompVersion = 0x0001;

// CLASS DECLARATION
/**
* @publishedPartner
* @released
* 
* @class CSigComp sigcomp.h "sigcomp.h"
*
* This class is used for compressing and decompressing text-based protocols
* using static or dynamic compression. Different algorithms can be used in
* order to compress the signalling messages. 
*
* The user of the class must call AllowL() or Deny() immediately after
* verification
* of the decompressed message. If the user fails to call AllowL()/Deny()
* the UDVM memory will be freed next time the user will use SigComp services.
* It is the user's responsibility to map the decompressed
* message under appropriate compartment.
*
* The user is supposed to use only one instance of the class while using
* the compression of the particular text-based protocol e.g. SIP/SDP. The
* compression algorithm and static dictionary to be used are chosen while
* creating the instance of the class The static dictionary will be shared
* between different compartments. All compartments created will use the
* compression algorithm defined during the instantion of the class.
*
* If the precondintions are not met the function will leave with KErrArgument
* system wide error code.
*/
class CSigComp : public CBase
    {
    public: 

        /** Error codes*/
        enum TError 
            {

            /** Decompression failure occurred*/
            EDecompressionFailure = -3000,
            /** The SigComp message was incomplete*/
            EIncompleteMessage,
            /**Compression failure occured*/
            ECompressionFailure

            };


        /** 
          * The number of "UDVM cycles" available to decompress each
          * bit in a SigComp message.
          */
        enum TCyclesPerBit
            {

            /** 16 cycles */
            E16 = 16,        
            /** 32 cycles */
            E32 = 32,
            /** 64 cycles */
            E64 = 64,
            /** 128 cycles */
            E128 = 128

            };


        /**
          * The number of bytes offered
          * to a particular compartment for the creation of state;
          * also defines the amount of memory available to decompress
          * SigComp message.
          */
        enum TMemorySize
            {
            /** 0 bytes */
            E0 = 0,
            /** 2048 bytes */
            E2048 = 2048,
            /** 4096 bytes */
            E4096 = 4096,
            /** 8192 bytes */
            E8192 = 8192,
            /** 16384 bytes */
            E16384 = 16384,
            /** 32768 bytes */
            E32768 = 32768,
            /** 65536 bytes */
            E65536 = 65536,
            /** 131072 bytes */
            E131072 = 131072

            };
    



    public:

        /**
         * Destructor
         */

        IMPORT_C ~CSigComp();

        /**
         * Constructs an object; leaves on failure. If the algorithm is
         * not supported, the function leaves with KErrNotFound
         * error code.
         *
         * @pre aDecompressionMemSize != TMemorySize::E0
         *
         * @param aDecompressionMemSize The amount of memory in bytes
         *                available decompress one
         *                SigComp message.
         * @param aCyclesPerBit The amount of "UDVM cycles" available to
         *                      decompress each bit in SigComp message
         * @param aStateMemorySize The default amount of memory offered for
         *                         each compartment for saving the states.
         * @param aAlgorithm       an algorithm to be used for the compression
         *                         e.g. DEFLATE
         *
         * @return new instance
         */

        IMPORT_C static CSigComp* NewL(TMemorySize aDecompressionMemSize,
                       TCyclesPerBit aCyclesPerBit,
                       TMemorySize aStateMemorySize,
                       const TDesC8& aAlgorithm);

        /**
         * Constructs an object; leaves on failure. If the algorithm is not
         * supported, the function leaves with KErrNotFound error code.
         * If the state item value is not found, the function leaves with
         * KErrNotFound error code.
         *
         * @pre aDecompressionMemSize != TMemorySize::E0
         *
         * @param aDecompressionMemSize The amount of memory in bytes available
         *                              to decompress one SigComp message.
         * @param aCyclesPerBit The amount of "UDVM cycles" available to
         *                      decompress each bit in SigComp message
         * @param aStateMemorySize The default amount of memory offered for
         *                         each compartment for saving the states.
         * @param aAlgorithm       an algorithm to be used for the compression
         *                         e.g. DEFLATE
         * @param aStateItem       the local state to be used with every
         *                         compartment e.g. static dictionary
         * @param aUploadState     If set to ETrue, the state item will be
         *                         uploaded to the remote endpoint in the first
         *                         SigComp message sent within the compartment.
         *                         
         * @return new instance
         */


        IMPORT_C static CSigComp* NewL(TMemorySize aDecompressionMemSize,
                       TCyclesPerBit aCyclesPerBit,
                       TMemorySize aStateMemorySize,
                       const TDesC8& aAlgorithm,
                       const TSigCompStateItem& aStateItem,
                       TBool aUploadState = EFalse);


                                       

        /**
         * Constructs an object and adds the pointer to the cleanup stack;
         * leaves on failure.
         * If the algorithm is not
         * supported, the function leaves with KErrNotFound error code.
         *
         * @pre aDecompressionMemSize != TMemorySize::E0
         *
         * @param aDecompressionMemSize The amount of memory in bytes available
         *                              to decompress one SigComp message.
         * @param aCyclesPerBit The amount of "UDVM cycles" available to
         *                      decompress each bit in SigComp message
         * @param aStateMemorySize The default amount of memory offered for
         *                         each compartment for saving the states.
         * @param aAlgorithm       an algorithm to be used for the compression
         *                         e.g. DEFLATE
         *
         * @return new instance
         */

        IMPORT_C static CSigComp* NewLC(TMemorySize aDecompressionMemSize,
                        TCyclesPerBit aCyclesPerBit,
                        TMemorySize aStateMemorySize,
                        const TDesC8& aAlgorithm);



        /**
         * Constructs an object and adds the pointer to the cleanupstack;
         * leaves on failure. 
         * If the algorithm is not supported, the function leaves with
         * KErrNotFound error code.
         * If the state item value is not found, the function leaves
         * with KErrNotFound error code.
         *
         * @pre aDecompressionMemSize != TMemorySize::E0
         *
         * @param aDecompressionMemSize The amount of memory in bytes available
         *                              to decompress one SigComp message.
         * @param aCyclesPerBit The amount of "UDVM cycles" available to
         *                      decompress each bit in SigComp message
         * @param aStateMemorySize The default amount of memory offered for
         *                         each compartment for saving the states.
         * @param aAlgorithm       an algorithm to be used for the compression
         *                         e.g. DEFLATE
         * @param aStateItem       the local state to be used with every
         *                         compartment e.g. static dictionary
         * @param aUploadState     If set to ETrue, the state item will be
         *                         uploaded to the remote endpoint in the
         *                         first SigComp message sent within the
         *                         compartment.
         *                         
         * @return new instance
         */


        IMPORT_C static CSigComp* NewLC(TMemorySize aDecompressionMemSize,
                            TCyclesPerBit aCyclesPerBit,
                            TMemorySize aStateMemorySize,
                            const TDesC8& aAlgorithm,
                            const TSigCompStateItem& aStateItem,
                            TBool aUploadState = EFalse);

        /**
         * Checks if the first byte contains bit pattern indicating the start
         * of the SigComp message. Function examines only the first byte.
         *
         * @param aMessage a message
         * @return ETrue if the first byte indicates the start of the SigComp
         *          message, EFalse otherwise
         */

        IMPORT_C TBool IsSigCompMsg(const TDesC8& aMessage) const;


        /**
         * Checks if the message contains the delimeter indicating SigComp
         * message end. This function must be used only with stream-based
         * transports, otherwise it will always return EFalse.
         *
         * @pre IsSigCompMsg()==ETrue
         *
         * @param aMessage a message
         * @return ETrue is the SigComp message is complete, EFalse otherwise
         */

        IMPORT_C TBool IsCompleteL(const TDesC8& aMessage) const;

                    
        /**
         * Decompress the message; leaves on failure. 
         *
         * SigComp specific leave codes:
         * EDecompressionFailure - the decompressor failed to decompress the
         * message.
         * EIncompleteMessage - the SigComp message was incomplete
         * The function expects the client to provide complete SigComp message.
         *
         * @pre IsSigCompMsg()==ETrue
         * 
         * @param aMessage a message to decompress. The message must start with
         *                 SigComp specific delimeter and end with SigComp
         *                 specific delimeter
         *
         * @param aBytesConsumed on return will contain the number of bytes
         *                       consumed by the decompression from the
         *                       original message
         * @param aStreamBasedProtocol if set to ETrue, the message was received
         *                       over stream-based transport protocol
         * @returns decompressed message, the ownership is transferred
         */

        IMPORT_C CBufBase* DecompressL(const TDesC8& aMessage,
                                       TUint& aBytesConsumed,
                                       TBool aStreamBasedProtocol = EFalse);

        /**
         * Allows the state of the decompressed message to be saved; 
         * leaves on failure.
         * 
         * @param aSigCompCompartment the compartment under which the
         * state will be saved.
         */

        IMPORT_C void AllowL(CSigCompCompartment& aSigCompCompartment);

        /**
         * Denies the state of the message to be saved.
         */

        IMPORT_C void Deny();


        /**
         * Get decompression memory size parameter.
         *
         * @return decompression memory size
         */

        TMemorySize DecompressionMemorySize() const;


        /**
         * Get cycles per bit parameter.
         *
         * @return cycles per bit
         */

        TCyclesPerBit CyclesPerBit() const;


        /**
         * Get state memory size parameter.
         *
         * @return state memory size
         */

        TMemorySize StateMemorySize() const;


        /**
         * Get state manager instance.
         *
         * @return state manager
         */

        const CStateMgr* StateMgr() const;

        /**
         * Get compressor instance.
         *
         * @return compressor
         */

        const CSigCompCompressor* Compressor() const;

        /**
         * Get state memory size in bytes
         *
         * @return state memory size in bytes
         */

        TUint StateMemoryBytes() const;

#if defined(SIGCOMP_DEBUG)
        /**
         * Get consumed cycles number
         *
         * @return consumed cycles number.
         *
         */
        IMPORT_C TUint CyclesConsumed() const;
#endif

    private:

        CSigComp();

        void ConstructL(TMemorySize aDecompressionMemSize,
                TCyclesPerBit aCyclesPerBit,
                TMemorySize aStateMemorySize,
                const TDesC8& aAlgorithm);

        void ConstructL(TMemorySize aDecompressionMemSize,
                TCyclesPerBit aCyclesPerBit,
                TMemorySize aStateMemorySize,
                const TDesC8& aAlgorithm,
                const TSigCompStateItem& aStateItem,
                TBool aUploadState = EFalse);

        void ConstructL(TMemorySize aDecompressionMemSize,
                        TCyclesPerBit aCyclesPerBit,
                        TMemorySize aStateMemorySize,
                        TBool aUploadState);

    private:
        /** decompression memory size, in bytes */
        TInt iMemSize;

        /** cycles per bit */
        TCyclesPerBit iCyclesPerBit;

        /** state memory size */
        TMemorySize iStateMemorySize;

        /**  should the state be uploaded */
        TBool iUploadState;

        /** state manager instance */
        CStateMgr* iStateMgr;

        /** UDVM instance */
        CUdvm* iUdvm;

        /** compressor instance */
        CSigCompCompressor* iCompressor;

    };

#endif // CSIGCOMP_H