diff -r 000000000000 -r 307788aac0a8 realtimenetprots/sipfw/SigComp/SigCompEngine/api/Sigcomp.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/realtimenetprots/sipfw/SigComp/SigCompEngine/api/Sigcomp.h Tue Feb 02 01:03:15 2010 +0200 @@ -0,0 +1,445 @@ +/* +* 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 + +// 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