--- /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 <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