1 /*

     2 * Copyright (c) 2005-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        : sipmessage.h

    16 * Part of     : SIP Codec

    17 * Interface   : SIP Codec API

    18 * Version     : SIP/4.0 

    19 *

    20 */

    21 

    22 

    23 

    24 

    25 /**

    26  @internalComponent

    27 */

    28 

    29 #ifndef CSIPMESSAGE_H

    30 #define CSIPMESSAGE_H

    31 

    32 //  INCLUDES

    33 #include <e32base.h>

    34 #include "sipheaderbase.h"

    35 #include "_sipcodecdefs.h"

    36 

    37 // FORWARD DECLARATIONS

    38 class CSIPFromHeader;

    39 class CSIPToHeader;

    40 class CSIPCallIDHeader;

    41 class CSIPCSeqHeader;

    42 

    43 // CLASS DECLARATION

    44 /**

    45 * A base class for SIP messages that provides functions 

    46 * for setting and getting headers and SIP version of a SIP message. 

    47 *

    48 * @lib sipcodec.lib

    49 */

    50 class CSIPMessage : public CBase

    51     {

    52     public: // Constructors and destructor

    53 

    54         /**

    55         * Destructor.

    56         */

    57         IMPORT_C virtual ~CSIPMessage();

    58 

    59     public: // New functions

    60 

    61         /**

    62         * Checks if the actual class of this object is CSIPRequest and 

    63         * can be safely casted to CSIPRequest

    64         * @return ETrue if the object is of class CSIPRequest

    65         */

    66         IMPORT_C virtual TBool IsRequest() const = 0;

    67 

    68         /**

    69         * Adds a header to the SIP message. Note that the first header inserted

    70         * within a group of headers with the same name (for example "Route") is

    71         * also guaranteed to appear first in the encoded message.

    72         * 

    73         * @pre aSIPHeader != 0

    74         * @pre !(aSIPHeader->MoreThanOneAllowed()&&HasHeader

    75         *                                            (aSIPHeader->Name())

    76         * @param aSIPHeader a SIP header to be added, ownership is transferred.

    77         */

    78         IMPORT_C void AddHeaderL(CSIPHeaderBase* aSIPHeader);

    79 

    80         /**

    81         * Adds a deep copy of a given header to the SIP message. 

    82         * Note that the first header inserted

    83         * within a group of headers with the same name (for example "Route") is

    84         * also guaranteed to appear first in the encoded message.

    85         * 

    86         * @pre !(aSIPHeader.MoreThanOneAllowed()&&HasHeader(aSIPHeader->Name())

    87         * @param aSIPHeader a SIP header to be added

    88         */

    89         IMPORT_C void AddHeaderL(const CSIPHeaderBase& aSIPHeader);

    90 

    91         /**

    92         * Replaces a header to the SIP message based on pointer comparison.

    93         * The updated header has to have the same type.

    94         * This means that a Contact-header cannot replace a To-header.

    95         * Note that the new header will be placed last in the list of headers.

    96         *

    97         * @pre aOldSIPHeader != 0

    98         * @pre aNewSIPHeader != 0

    99         * @pre aOldSIPHeader->Name() == aNewSIPHeader->Name()

   100         * @param aOldSIPHeader the header to be replaced.

   101         *       Deleted if the function returns without leaving.

   102         * @param aNewSIPHeader the header that replaces the old header.

   103         *        The ownership is transferred.

   104         */

   105         IMPORT_C void ReplaceHeaderL(

   106             CSIPHeaderBase* aOldSIPHeader,

   107             CSIPHeaderBase* aNewSIPHeader);

   108 

   109         /**

   110         * Replaces all the headers with a common name.

   111         * All the headers must be of same type.

   112         *

   113         * @pre aNewHeaders.Count() > 0

   114         * @param aNewHeaders the headers that will replace the old headers.

   115         *        The ownership of the headers is transferred and 

   116         *        the array is resetted on return.

   117         */

   118         IMPORT_C void ReplaceHeadersL(

   119             RPointerArray<CSIPHeaderBase>& aNewHeaders);

   120 

   121         /**

   122         * Checks if a one or more headers with aName are present

   123         * @param aName the full or compact name of the header

   124         * @return ETrue if present, otherwise EFalse

   125         */

   126         IMPORT_C TBool HasHeader(RStringF aName) const;

   127 

   128         /**

   129         * Get a count of headers with a given name in this SIP message.

   130         * @param aName the full or compact name of the header

   131         * @return number of headers with the given name.

   132         */

   133         IMPORT_C TInt HeaderCount(RStringF aName);

   134 

   135         /**

   136         * Gets an iterator to a list of headers with aName 

   137         * @pre HasHeader(aName) == ETrue

   138         * @param aName the full or compact name of the headers to get

   139         * @return an iterator to a list of headers with aName.

   140         *         The headers can be modified through the iterator, but are 

   141         *         supposed to be removed using RemoveHeader.

   142         */

   143         IMPORT_C TSglQueIter<CSIPHeaderBase> Headers(RStringF aName);

   144 

   145         /**

   146         * Gets a header with aName and an index in list of header with aName

   147         * Note that using HeaderCount(...) and this function to loop through

   148         * the headers with a given name is MUCH less efficient than using

   149         * iterators through Headers(...).

   150         *

   151         * @pre aIndex < HeaderCount(aName) 

   152         * @param aName the full or compact name of the header to get

   153         * @param aIndex the index in the header list

   154         * @return 0 if the header with the given name or index was not found,

   155         *          otherwise the header. The ownership is NOT transferred.

   156         */

   157         IMPORT_C CSIPHeaderBase* Header(RStringF aName, TInt aIndex);

   158 

   159         /**

   160         * Removes a header from the SIP message based on pointer comparison

   161         * @param aSIPHeader the header to be removed, ownership is NOT 

   162         *        transferred, the caller is supposed to do the deletion

   163         * @return KErrNone if succesfully removed, KErrNotFound if the

   164         *         header was not found.

   165         */

   166         IMPORT_C TInt RemoveHeader(const CSIPHeaderBase* aSIPHeader);

   167 

   168         /**

   169         * Removes and deletes all the headers with name aName

   170         * @pre HasHeader(aName)==ETrue

   171         * @param aName the full or compact name of the headers to delete. 

   172         * @return KErrNone if succesfully removed and deleted,

   173         *         KErrNotFound if headers with aName header were not found.

   174         */

   175         IMPORT_C TInt DeleteHeaders(RStringF aName);

   176 

   177         /**

   178         * Creates copies of the pointers to all the headers in the SIP message.

   179         * Note that the caller must not delete any of the headers returned.

   180         * @return an array of all the headers in the SIP message.

   181         */

   182         IMPORT_C const RPointerArray<CSIPHeaderBase>& AllHeadersL();

   183 

   184         /**

   185         * Gets the From-header in the message.

   186         * @return The From-header or zero if the header is not present.

   187         *         The ownership is NOT transferred.

   188         */

   189         IMPORT_C CSIPFromHeader* From();

   190 

   191         /**

   192         * Gets the To-header in the message.

   193         * @return The To-header or zero if the header is not present.

   194         *          The ownership is NOT transferred.

   195         */

   196         IMPORT_C CSIPToHeader* To();

   197 

   198         /**

   199         * Gets the Call-ID-header in the message.

   200         * @return The Call-ID-header or zero if the header is not present.

   201         *         The ownership is NOT transferred.

   202         */

   203         IMPORT_C CSIPCallIDHeader* CallID();

   204 

   205         /**

   206         * Gets the CSeq-header in the message.

   207         * @return The CSeq-header or zero if the header is not present.

   208         *         The ownership is NOT transferred.

   209         */

   210         IMPORT_C CSIPCSeqHeader* CSeq();

   211 

   212         /**

   213         * Gets the SIP version

   214         * @return the SIP version as text

   215         */

   216         IMPORT_C RStringF SIPVersion() const;

   217 

   218         /**

   219         * Set the content

   220         * @param aContent, the ownership is transferred

   221         */

   222         IMPORT_C void SetContent(HBufC8* aContent);

   223 

   224         /**

   225         * Gets the content.

   226         * @return the content, the ownership is NOT transferred.

   227         */

   228         IMPORT_C const TDesC8& Content() const;

   229 

   230         /**

   231         * Gets the ownership to the content

   232         * @return the content, the ownership is transferred.

   233         */

   234         IMPORT_C HBufC8* TakeContentOwnershipL();

   235 

   236         /**

   237         * Checks if "Content-Length"-header was present 

   238         * when the message was decoded.

   239         * @return ETrue if set, otherwise EFalse

   240         */

   241         IMPORT_C TBool HasAnnouncedContentLength() const;

   242 

   243         /**

   244         * Gets the value of "Content-Length"-header 

   245         * that was present when the message was decoded.

   246         * This might be different than the actual length of the message content.

   247         * @pre HasAnnouncedContentLength() == ETrue

   248         * @return the value of "Content-Length"-header

   249         */

   250         IMPORT_C TUint AnnouncedContentLength() const;

   251 

   252         /**

   253         * Using this function the user can get the length of the

   254         * encoded header part without actually encoding the whole header part.

   255         * Note that this function only saves memory, but not necessarily 

   256         * processing time compared to the actual encoding.

   257         * @return the length of the header part when encoded

   258         */

   259         IMPORT_C TInt EncodedHeaderPartLengthL();

   260 

   261         /**

   262         * Encodes the header part of the SIP message object 

   263         * into its textual representation..

   264         * @return a textual representation of the object,

   265         *         the ownership is transferred

   266         */

   267         IMPORT_C CBufBase* ToTextHeaderPartL();

   268 

   269         /**

   270         * Encodes the header part of the SIP message object 

   271         * into its textual representation and pushes it to the CleanupStack.

   272         * @return a textual representation of the object,

   273         *         the ownership is transferred

   274         */

   275         IMPORT_C CBufBase* ToTextHeaderPartLC();

   276 

   277         /**

   278         * Encodes the SIP message object into its textual representation.

   279         * @return a textual representation of the object,

   280         *         the ownership is transferred

   281         */

   282         IMPORT_C CBufBase* ToTextL();

   283 

   284         /**

   285         * Encodes the SIP message object into its textual representation

   286         * and pushes it to the CleanupStack.

   287         * @return a textual representation of the object,

   288         *         the ownership is transferred

   289         */

   290         IMPORT_C CBufBase* ToTextLC();

   291 

   292         /**

   293         * Externalizes all the headers that support serialization

   294         * to a write stream.

   295         * @param aWriteStream a stream where the objects will be externalized

   296         */

   297         IMPORT_C void ExternalizeHeadersL(RWriteStream& aWriteStream);

   298 

   299         /**

   300         * Adds headers to the CSIPMessage from a read stream. 

   301         * @param aReadStream a stream containing the values of the

   302         *        externalized SIP header objects 

   303         */

   304         IMPORT_C void InternalizeHeadersL(RReadStream& aReadStream);

   305 

   306     public: // New functions, for internal use

   307 

   308         void SetSIPVersionL(const TDesC8& aSIPVersion);

   309 

   310     protected: // Constructors

   311     

   312         void ConstructL();

   313         CSIPMessage();

   314         

   315     protected: // New functions

   316         

   317         virtual HBufC8* ToTextFirstLineLC() const = 0; 

   318 

   319     private: // New functions

   320 

   321         RStringF ReadFromStreamL (RReadStream& aReadStream) const;

   322         

   323         TBool IsContentLengthHeader(const CSIPHeaderBase& aHeader) const;

   324         

   325         TInt FindHeaderListIndex(RStringF aName) const;

   326         

   327         TInt FindHeaderListIndex(const CSIPHeaderBase& aHeader) const;

   328     

   329         void InsertL(TSglQue<CSIPHeaderBase>& aHeaderList);

   330         

   331         static TInt HeaderOrder(

   332             const TSglQue<CSIPHeaderBase>& aFirstList, 

   333             const TSglQue<CSIPHeaderBase>& aSecondList);

   334             

   335         void GetEncodedFirstLineSizeL(TInt& aSize) const;

   336     

   337         void GetEncodedContentLengthHeaderSizeL(TInt& aSize) const;

   338     

   339         HBufC8* ToTextContentLengthLC() const;

   340 

   341     private: // Data

   342 

   343         RStringF iSIPVersion;

   344         RArray<TSglQue<CSIPHeaderBase> > iSIPHeaderListArray;

   345         HBufC8* iContent;

   346         TInt iAnnouncedContentLength;

   347         TBool iAnnouncedContentLengthSet;

   348         RPointerArray<CSIPHeaderBase> iTmpAllHeaders;

   349 

   350     private: // For testing purposes

   351 

   352         UNIT_TEST(CSIPMessageTest)

   353     };

   354 

   355 

   356 #endif // CSIPMESSAGE_H

   357 

   358 // End of File