1 /*

     2 * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name        : SigComp.h

    16 * Part of     : SigComp

    17 * Interface   : 

    18 * main sigcomp class, sigcomp public API.

    19 * Version     : 1.0

    20 *

    21 */

    22 

    23 

    24 

    25 #ifndef CSIGCOMP_H

    26 #define CSIGCOMP_H

    27 

    28 //  INCLUDES

    29 #include <e32base.h>

    30 

    31 // FORWARD DECLARATIONS

    32 class CSigCompCompartment;

    33 class TSigCompStateItem;

    34 class CUdvm;

    35 class CStateMgr;

    36 class CSigCompCompressor;

    37 class TStateItem;

    38 

    39 // CONSTANTS

    40 const TInt KSigCompVersion = 0x0001;

    41 

    42 // CLASS DECLARATION

    43 /**

    44 * @publishedPartner

    45 * @released

    46 * 

    47 * @class CSigComp sigcomp.h "sigcomp.h"

    48 *

    49 * This class is used for compressing and decompressing text-based protocols

    50 * using static or dynamic compression. Different algorithms can be used in

    51 * order to compress the signalling messages. 

    52 *

    53 * The user of the class must call AllowL() or Deny() immediately after

    54 * verification

    55 * of the decompressed message. If the user fails to call AllowL()/Deny()

    56 * the UDVM memory will be freed next time the user will use SigComp services.

    57 * It is the user's responsibility to map the decompressed

    58 * message under appropriate compartment.

    59 *

    60 * The user is supposed to use only one instance of the class while using

    61 * the compression of the particular text-based protocol e.g. SIP/SDP. The

    62 * compression algorithm and static dictionary to be used are chosen while

    63 * creating the instance of the class The static dictionary will be shared

    64 * between different compartments. All compartments created will use the

    65 * compression algorithm defined during the instantion of the class.

    66 *

    67 * If the precondintions are not met the function will leave with KErrArgument

    68 * system wide error code.

    69 */

    70 class CSigComp : public CBase

    71     {

    72     public: 

    73 

    74         /** Error codes*/

    75         enum TError 

    76             {

    77 

    78             /** Decompression failure occurred*/

    79             EDecompressionFailure = -3000,

    80             /** The SigComp message was incomplete*/

    81             EIncompleteMessage,

    82             /**Compression failure occured*/

    83             ECompressionFailure

    84 

    85             };

    86 

    87 

    88         /** 

    89           * The number of "UDVM cycles" available to decompress each

    90           * bit in a SigComp message.

    91           */

    92         enum TCyclesPerBit

    93             {

    94 

    95             /** 16 cycles */

    96             E16 = 16,        

    97             /** 32 cycles */

    98             E32 = 32,

    99             /** 64 cycles */

   100             E64 = 64,

   101             /** 128 cycles */

   102             E128 = 128

   103 

   104             };

   105 

   106 

   107         /**

   108           * The number of bytes offered

   109           * to a particular compartment for the creation of state;

   110           * also defines the amount of memory available to decompress

   111           * SigComp message.

   112           */

   113         enum TMemorySize

   114             {

   115             /** 0 bytes */

   116             E0 = 0,

   117             /** 2048 bytes */

   118             E2048 = 2048,

   119             /** 4096 bytes */

   120             E4096 = 4096,

   121             /** 8192 bytes */

   122             E8192 = 8192,

   123             /** 16384 bytes */

   124             E16384 = 16384,

   125             /** 32768 bytes */

   126             E32768 = 32768,

   127             /** 65536 bytes */

   128             E65536 = 65536,

   129             /** 131072 bytes */

   130             E131072 = 131072

   131 

   132             };

   133     

   134 

   135 

   136 

   137     public:

   138 

   139         /**

   140          * Destructor

   141          */

   142 

   143         IMPORT_C ~CSigComp();

   144 

   145         /**

   146          * Constructs an object; leaves on failure. If the algorithm is

   147          * not supported, the function leaves with KErrNotFound

   148          * error code.

   149          *

   150          * @pre aDecompressionMemSize != TMemorySize::E0

   151          *

   152          * @param aDecompressionMemSize The amount of memory in bytes

   153          *                available decompress one

   154          *                SigComp message.

   155          * @param aCyclesPerBit The amount of "UDVM cycles" available to

   156          *                      decompress each bit in SigComp message

   157          * @param aStateMemorySize The default amount of memory offered for

   158          *                         each compartment for saving the states.

   159          * @param aAlgorithm       an algorithm to be used for the compression

   160          *                         e.g. DEFLATE

   161          *

   162          * @return new instance

   163          */

   164 

   165         IMPORT_C static CSigComp* NewL(TMemorySize aDecompressionMemSize,

   166                        TCyclesPerBit aCyclesPerBit,

   167                        TMemorySize aStateMemorySize,

   168                        const TDesC8& aAlgorithm);

   169 

   170         /**

   171          * Constructs an object; leaves on failure. If the algorithm is not

   172          * supported, the function leaves with KErrNotFound error code.

   173          * If the state item value is not found, the function leaves with

   174          * KErrNotFound error code.

   175          *

   176          * @pre aDecompressionMemSize != TMemorySize::E0

   177          *

   178          * @param aDecompressionMemSize The amount of memory in bytes available

   179          *                              to decompress one SigComp message.

   180          * @param aCyclesPerBit The amount of "UDVM cycles" available to

   181          *                      decompress each bit in SigComp message

   182          * @param aStateMemorySize The default amount of memory offered for

   183          *                         each compartment for saving the states.

   184          * @param aAlgorithm       an algorithm to be used for the compression

   185          *                         e.g. DEFLATE

   186          * @param aStateItem       the local state to be used with every

   187          *                         compartment e.g. static dictionary

   188          * @param aUploadState     If set to ETrue, the state item will be

   189          *                         uploaded to the remote endpoint in the first

   190          *                         SigComp message sent within the compartment.

   191          *                         

   192          * @return new instance

   193          */

   194 

   195 

   196         IMPORT_C static CSigComp* NewL(TMemorySize aDecompressionMemSize,

   197                        TCyclesPerBit aCyclesPerBit,

   198                        TMemorySize aStateMemorySize,

   199                        const TDesC8& aAlgorithm,

   200                        const TSigCompStateItem& aStateItem,

   201                        TBool aUploadState = EFalse);

   202 

   203 

   204                                        

   205 

   206         /**

   207          * Constructs an object and adds the pointer to the cleanup stack;

   208          * leaves on failure.

   209          * If the algorithm is not

   210          * supported, the function leaves with KErrNotFound error code.

   211          *

   212          * @pre aDecompressionMemSize != TMemorySize::E0

   213          *

   214          * @param aDecompressionMemSize The amount of memory in bytes available

   215          *                              to decompress one SigComp message.

   216          * @param aCyclesPerBit The amount of "UDVM cycles" available to

   217          *                      decompress each bit in SigComp message

   218          * @param aStateMemorySize The default amount of memory offered for

   219          *                         each compartment for saving the states.

   220          * @param aAlgorithm       an algorithm to be used for the compression

   221          *                         e.g. DEFLATE

   222          *

   223          * @return new instance

   224          */

   225 

   226         IMPORT_C static CSigComp* NewLC(TMemorySize aDecompressionMemSize,

   227                         TCyclesPerBit aCyclesPerBit,

   228                         TMemorySize aStateMemorySize,

   229                         const TDesC8& aAlgorithm);

   230 

   231 

   232 

   233         /**

   234          * Constructs an object and adds the pointer to the cleanupstack;

   235          * leaves on failure. 

   236          * If the algorithm is not supported, the function leaves with

   237          * KErrNotFound error code.

   238          * If the state item value is not found, the function leaves

   239          * with KErrNotFound error code.

   240          *

   241          * @pre aDecompressionMemSize != TMemorySize::E0

   242          *

   243          * @param aDecompressionMemSize The amount of memory in bytes available

   244          *                              to decompress one SigComp message.

   245          * @param aCyclesPerBit The amount of "UDVM cycles" available to

   246          *                      decompress each bit in SigComp message

   247          * @param aStateMemorySize The default amount of memory offered for

   248          *                         each compartment for saving the states.

   249          * @param aAlgorithm       an algorithm to be used for the compression

   250          *                         e.g. DEFLATE

   251          * @param aStateItem       the local state to be used with every

   252          *                         compartment e.g. static dictionary

   253          * @param aUploadState     If set to ETrue, the state item will be

   254          *                         uploaded to the remote endpoint in the

   255          *                         first SigComp message sent within the

   256          *                         compartment.

   257          *                         

   258          * @return new instance

   259          */

   260 

   261 

   262         IMPORT_C static CSigComp* NewLC(TMemorySize aDecompressionMemSize,

   263                             TCyclesPerBit aCyclesPerBit,

   264                             TMemorySize aStateMemorySize,

   265                             const TDesC8& aAlgorithm,

   266                             const TSigCompStateItem& aStateItem,

   267                             TBool aUploadState = EFalse);

   268 

   269         /**

   270          * Checks if the first byte contains bit pattern indicating the start

   271          * of the SigComp message. Function examines only the first byte.

   272          *

   273          * @param aMessage a message

   274          * @return ETrue if the first byte indicates the start of the SigComp

   275          *          message, EFalse otherwise

   276          */

   277 

   278         IMPORT_C TBool IsSigCompMsg(const TDesC8& aMessage) const;

   279 

   280 

   281         /**

   282          * Checks if the message contains the delimeter indicating SigComp

   283          * message end. This function must be used only with stream-based

   284          * transports, otherwise it will always return EFalse.

   285          *

   286          * @pre IsSigCompMsg()==ETrue

   287          *

   288          * @param aMessage a message

   289          * @return ETrue is the SigComp message is complete, EFalse otherwise

   290          */

   291 

   292         IMPORT_C TBool IsCompleteL(const TDesC8& aMessage) const;

   293 

   294                     

   295         /**

   296          * Decompress the message; leaves on failure. 

   297          *

   298          * SigComp specific leave codes:

   299          * EDecompressionFailure - the decompressor failed to decompress the

   300          * message.

   301          * EIncompleteMessage - the SigComp message was incomplete

   302          * The function expects the client to provide complete SigComp message.

   303          *

   304          * @pre IsSigCompMsg()==ETrue

   305          * 

   306          * @param aMessage a message to decompress. The message must start with

   307          *                 SigComp specific delimeter and end with SigComp

   308          *                 specific delimeter

   309          *

   310          * @param aBytesConsumed on return will contain the number of bytes

   311          *                       consumed by the decompression from the

   312          *                       original message

   313          * @param aStreamBasedProtocol if set to ETrue, the message was received

   314          *                       over stream-based transport protocol

   315          * @returns decompressed message, the ownership is transferred

   316          */

   317 

   318         IMPORT_C CBufBase* DecompressL(const TDesC8& aMessage,

   319                                        TUint& aBytesConsumed,

   320                                        TBool aStreamBasedProtocol = EFalse);

   321 

   322         /**

   323          * Allows the state of the decompressed message to be saved; 

   324          * leaves on failure.

   325          * 

   326          * @param aSigCompCompartment the compartment under which the

   327          * state will be saved.

   328          */

   329 

   330         IMPORT_C void AllowL(CSigCompCompartment& aSigCompCompartment);

   331 

   332         /**

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

   334          */

   335 

   336         IMPORT_C void Deny();

   337 

   338 

   339         /**

   340          * Get decompression memory size parameter.

   341          *

   342          * @return decompression memory size

   343          */

   344 

   345         TMemorySize DecompressionMemorySize() const;

   346 

   347 

   348         /**

   349          * Get cycles per bit parameter.

   350          *

   351          * @return cycles per bit

   352          */

   353 

   354         TCyclesPerBit CyclesPerBit() const;

   355 

   356 

   357         /**

   358          * Get state memory size parameter.

   359          *

   360          * @return state memory size

   361          */

   362 

   363         TMemorySize StateMemorySize() const;

   364 

   365 

   366         /**

   367          * Get state manager instance.

   368          *

   369          * @return state manager

   370          */

   371 

   372         const CStateMgr* StateMgr() const;

   373 

   374         /**

   375          * Get compressor instance.

   376          *

   377          * @return compressor

   378          */

   379 

   380         const CSigCompCompressor* Compressor() const;

   381 

   382         /**

   383          * Get state memory size in bytes

   384          *

   385          * @return state memory size in bytes

   386          */

   387 

   388         TUint StateMemoryBytes() const;

   389 

   390 #if defined(SIGCOMP_DEBUG)

   391         /**

   392          * Get consumed cycles number

   393          *

   394          * @return consumed cycles number.

   395          *

   396          */

   397         IMPORT_C TUint CyclesConsumed() const;

   398 #endif

   399 

   400     private:

   401 

   402         CSigComp();

   403 

   404         void ConstructL(TMemorySize aDecompressionMemSize,

   405                 TCyclesPerBit aCyclesPerBit,

   406                 TMemorySize aStateMemorySize,

   407                 const TDesC8& aAlgorithm);

   408 

   409         void ConstructL(TMemorySize aDecompressionMemSize,

   410                 TCyclesPerBit aCyclesPerBit,

   411                 TMemorySize aStateMemorySize,

   412                 const TDesC8& aAlgorithm,

   413                 const TSigCompStateItem& aStateItem,

   414                 TBool aUploadState = EFalse);

   415 

   416         void ConstructL(TMemorySize aDecompressionMemSize,

   417                         TCyclesPerBit aCyclesPerBit,

   418                         TMemorySize aStateMemorySize,

   419                         TBool aUploadState);

   420 

   421     private:

   422         /** decompression memory size, in bytes */

   423         TInt iMemSize;

   424 

   425         /** cycles per bit */

   426         TCyclesPerBit iCyclesPerBit;

   427 

   428         /** state memory size */

   429         TMemorySize iStateMemorySize;

   430 

   431         /**  should the state be uploaded */

   432         TBool iUploadState;

   433 

   434         /** state manager instance */

   435         CStateMgr* iStateMgr;

   436 

   437         /** UDVM instance */

   438         CUdvm* iUdvm;

   439 

   440         /** compressor instance */

   441         CSigCompCompressor* iCompressor;

   442 

   443     };

   444 

   445 #endif // CSIGCOMP_H