/*

* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

* Name          : SdpDocument.h

* Part of       : SDP Codec

* Interface     : SDK API, SDP Codec API

* Version       : 1.0

*

*/

#ifndef CSDPDOCUMENT_H

#define CSDPDOCUMENT_H

//  INCLUDES

#include <e32base.h>

#include <badesca.h>

#include "_sdpdefs.h"

#include <stringpool.h>

// FORWARD DECLARATIONS

class SdpUtil;

class RReadStream;

class RWriteStream;

class CUri8;

class CDesC8Array;

class CSdpOriginField;

class CSdpEmailField;

class CSdpPhoneField;

class CSdpConnectionField;

class CSdpBandwidthField;

class CSdpTimeField;

class CSdpAttributeField;

class CSdpMediaField;

class CSdpKeyField;

class CSdpCodecParseUtil;

// CLASS DECLARATION

/**

 *  @publishedAll

 *  @released

 *

 *    This class encapsulates the Session Description Protocol (SDP) document.

 *  The SDP document is a collection of SDP fields and related values

 *    describing a session.

 *

 *    The normative reference for correct formatting and values is

 *    draft-ietf-mmusic-sdp-new-14 unless specified otherwise in

 *  member documentation. The implementation supports this normative

 *  reference, but does not enforce it fully. 

 *

 *  @lib sdpcodec.lib

 */

class CSdpDocument : public CBase

    {

    public: // Constructors and destructor

        /**

        * Constructs a new SDP document.

        *    

        * @param aText A string containing a correctly formatted SDP document.

        * @return a new instance.

        */

        IMPORT_C static CSdpDocument* DecodeL(const TDesC8& aText);

        /**

        * Constructs a new SDP document and adds the pointer to the cleanup stack.

        *    

        * @param aText A string containing a correctly formatted SDP document.

        * @return a new instance.

        */

        IMPORT_C static CSdpDocument* DecodeLC(const TDesC8& aText);

        /**

        * Constructs a new, empty SDP document.

        * The instance will have the following initial values:

        *      v=0

        *      s=-

        *      t=0 0

        *

        * @return a new instance.

        */

        IMPORT_C static CSdpDocument* NewL();

        /**

        * Constructs a new, empty SDP document document and adds the pointer to 

        * the cleanup stack.

        * The instance will have the following initial values:

        *      v=0

        *      s=-

        *      t=0 0

        *

        * @return a new instance.

        */

        IMPORT_C static CSdpDocument* NewLC();

        /**

        * Deletes the resources held by the instance.

        */

        IMPORT_C ~CSdpDocument();

    public: 

        /**

        * Externalizes the object state in an internal, memory optimized format.

        *

        * @param aStream The output stream.

        */

        IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

        /**

        * Internalizes the object state from an internal, memory optimized format.

        *

        * @param aStream The input stream.

        * @return A new SDP document internalized from the input stream.

        */

        IMPORT_C static CSdpDocument* InternalizeL(RReadStream& aStream);

        /**

        * Outputs the SDP document formatted according to SDP syntax.

        * It is possible to output the document even though it is

        * incomplete in the sense that all mandatory SDP fields are

        * not present.When creating an SDP document to be used e.g.

        * as part of SIP signalling, caller should first ensure the

        * validity of the document using the IsValid() function.

        * 

        * @param aStream Stream used for output. On return the 

        *        stream includes correctly formatted SDP description.

        */

        IMPORT_C void EncodeL(RWriteStream& aStream) const;

        /**

        * Creates a new instance that is equal to the target.

        *

        * @return a new instance.

        */

        IMPORT_C CSdpDocument* CloneL() const;

        /**

        * Checks if the instance represents a valid SDP document.

        *

        * @return ETrue if SDP document is valid and EFalse if not.

        */

        IMPORT_C TBool IsValid() const;

        /**

        * Gets the SDP version used in the version field.

        * Note, that the current implementation supports only version number 0.

        *

        * @return The SDP version number.

        */ 

        IMPORT_C TUint SdpVersion() const;

        /**

        * Gets a reference to the session origin field.

        * Note, that the ownership is not transferred and

        * the instance must not be deleted by the caller.

        *

        * @return The origin field or zero if not present.

        */

        IMPORT_C CSdpOriginField* OriginField();

        /**

        * Gets a reference to the session origin field.

        *

        * @return The origin field or zero if not present.

        */

        IMPORT_C const CSdpOriginField* OriginField() const;

        /**

        * Sets or removes the session origin field.

        * Note, that the ownership of the argument is 

        * transferred to the SDP document object.

        *

        * @param aObj New origin field or null to remove the field.

        */

        IMPORT_C void SetOriginField(CSdpOriginField* aObj);

        /**

        * Gets the session name field value.

        *

        * @return The session name or empty descriptor if not present.

        */

        IMPORT_C const TDesC8& SessionName() const;

        /**

        * Sets the session name field value.

        *

        * @param aValue Valid session name value. 

        *        Note that an empty value is not accepted.

        * @leave KErrSdpCodecSessionField if

        *        aValue is not empty or aValue includes invalid byte strings 

        *        (´\0´, ´\n´, ´\r´).

        */

        IMPORT_C void SetSessionNameL(const TDesC8& aValue);

        /**

        * Gets the session information field value.

        *

        * @return Info field value or an empty descriptor if not present.

        */

        IMPORT_C const TDesC8& Info() const;

        /**

        * Sets or removes the session information field value.

        *

        * @param New field value or an empty descriptor to remove the field.

        * @leave KErrSdpCodecInfoField if aValue is not empty or aValue includes 

        *        invalid byte strings (´\0´, ´\n´, ´\r´).

        */

        IMPORT_C void SetInfoL(const TDesC8& aValue);

        /**

        *    Gets the session URI field value.

        *    Note, that the ownership is not transferred and

        *    the instance must not be deleted by the caller.

        *

        *    @return CUri8*: Session URI or zero if the field is not present.

        */

        IMPORT_C CUri8* Uri();

        /**

        * Gets the session URI field value.

        *

        * @return Session URI or zero if the field is not present.

        */

        IMPORT_C const CUri8* Uri() const;

        /**

        * Sets or removes the session level URI field.

        * Note, that the ownership of the argument is 

        * transferred to the SDP document object.

        *

        * @param New value of the field or zero to remove the field.

        */

        IMPORT_C void SetUri(CUri8* aValue);

        /**

        * Gets the set of session level email field values. This array is used to

        * add and remove fields into the document.

        * Note, that only correctly formatted email field values should be placed

        * into the array. Empty values in the array will be ignored.

        *

        * @return Email fields in array or empty array if no email fields.

        */

        IMPORT_C CDesC8Array& EmailFields();

        /**

        * Gets the set of session level phone field values. This array is used to

        * add and remove fields into the document.

        * Note, that only correctly formatted phone field values should be placed

        * into the array. Empty values in the array will be ignored.

        *  

        * @return Phone fields in array or empty array if no phone fields.

        */

        IMPORT_C CDesC8Array& PhoneFields();

        /**

        * Gets the session level connection field.

        * Note, that the ownership is not transferred and the instance must not be

        * deleted by the caller.

        *

        * @return Connection field or zero if not present.

        */

        IMPORT_C CSdpConnectionField* ConnectionField();

        /**

        * Gets the session level connection field.

        *

        * @return Connection field or zero if not present.

        */

        IMPORT_C const CSdpConnectionField* ConnectionField() const;

        /**

        * Sets or removes the session level connection field.

        * Note, that the ownership of the argument is 

        * transferred to the SDP document object.

        *

        * @param New connection field or zero to remove the field.

        */    

        IMPORT_C void SetConnectionField(CSdpConnectionField* aObj);

        /**

        * Gets the possibly empty set of session level bandwidth fields.

        * This array is used directly for element insertion and removal.

        * The array may contain zero references and these are ignored.

        *

        * The objects referenced from the array are owned by the document

        * instance and must not be deleted. An object can be removed from

        * the document by setting the corresponding element to zero. By

        * doing so, the calling party receives ownership of the removed object.

        *

        * @return Set of bandwidth fields.

        */

        IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();

        /**

        * Gets the set of session level time description fields.

        * This array is used directly for element insertion and removal.

        * There must be at least one time description field in a valid SDP

        * document.The array may contain zero references and these are ignored.

        *

        * The objects referenced from the array are owned by the document 

        * instance and must not be deleted. An object can be removed from the

        * document by setting the corresponding element to zero. By doing so,

        * the calling party receives ownership of the removed object.  

        *

        * @return Set of time fields.

        */

        IMPORT_C RPointerArray<CSdpTimeField>& TimeFields();

        /** 

        * Gets the zone adjustments field value.

        *

        * @return The field value or an empty descriptor if the

        *         field is not present.

        */

        IMPORT_C const TDesC8& ZoneAdjustments() const;

        /** 

        * Sets the zone adjustments field value.

        *

        * @param aValue A valid field value or an empty descriptor

        *        if field is not present.

        */

        IMPORT_C void SetZoneAdjustmentsL(const TDesC8& aValue);

        /**

        * Gets the session level encryption key field.

        * Note, that the ownership is not transferred and

        * the instance must not be deleted by the caller.

        *

        * @return The encryption key or zero if not present.

        */

        IMPORT_C CSdpKeyField* Key();

        /**

        * Gets the session level encryption key field.

        *

        * @return The encryption key or zero if not present.

        */

        IMPORT_C const CSdpKeyField* Key() const;

        /**

        * Sets or removes the encryption key field.

        * Note, that the ownership of the argument is 

        * transferred to the SDP document object.

        *

        * @param aObj New value of the field or zero to remove the field.

        */

        IMPORT_C void SetKey(CSdpKeyField* aObj);

        /**

        * Gets the possibly empty set of session level attribute fields.

        * This array is used directly for element insertion and removal.

        * The array may contain zero references and these are ignored.

        *

        * The objects referenced from the array are owned by the document

        * instance and must not be deleted. An object can be removed from the

        * document by setting the corresponding element to zero. By doing so,

        * the calling party receives ownership of the removed object.

        *

        * @return Set of session level attributes.

        */

        IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();

        /**

        * Gets the possibly empty set of media description fields.

        * This array is used directly for element insertion and removal.

        * Note, that media level attributes and fields are managed 

        * through the corresponding media field instance and not through

        * the document instance.

        * The array may contain zero references and these are ignored.

        *

        * The objects referenced from the array are owned by the document

        * instance and must not be deleted. An object can be removed from the

        * document by setting the corresponding element to zero. By doing so,

        * the calling party receives ownership of the removed object.

        *

        * @return Set of media description fields.

        */

        IMPORT_C RPointerArray<CSdpMediaField>& MediaFields();

    private:

        CSdpDocument();

        void ConstructL();

        void ConstructL(const CSdpDocument& aSdpDocument);

        void DoInternalizeL(RReadStream& aStream);

        void ParseL (const TDesC8& aText);

        void ParseSessionVersionL();

        void ParseSessionOwnerL();

        void ParseSessionNameL();

        void ParseSessionInformationL();

        void ParseUriL();

        void ParseEmailL();

        void ParsePhoneL();

        void ParseConnectionL();

        void ParseBandwidthL();

        void ParseTimeFieldL();

        void ParseZoneAdjustmentL();

        void ParseEncryptionKeyL();

        void ParseAttributeFieldL();

        void ParseMediaLevelL ();

        void ExternalizeDesCArrayL(CDesC8ArraySeg& aArray,

                               RWriteStream& aStream) const;

        void EncodeDesCArrayL(CDesC8ArraySeg& aArray,TInt aIndex,

                                            RWriteStream& aStream) const;

        TDesC8& GetTokenFromStreamL(RReadStream& aStream);

        CSdpDocument(const CSdpDocument&); // Hidden.

        CSdpDocument& operator = (const CSdpDocument&); // Hidden

    private: // Data

        HBufC8* iInfo;

        HBufC8* iSessionName;

        HBufC8* iZoneAdjustments;

        CSdpKeyField* iSdpKeyField;

        CSdpOriginField* iSdpOriginField;

        CSdpConnectionField* iSdpConnectionField;

        TUint iSdpVersion;

        RPointerArray<CSdpTimeField>* iTimeFields;

        RPointerArray<CSdpBandwidthField>* iBandwidthFields;

        RPointerArray<CSdpAttributeField>* iAttributeFields;

        RPointerArray<CSdpMediaField>* iMediaFields;

        CUri8* iUri;

        CDesC8ArraySeg* iEmailFields;

        CDesC8ArraySeg* iPhoneFields;

        RStringPool iPool;

        HBufC8* iToken;

        CSdpCodecParseUtil* iSdpCodecParseUtil;

    };

#endif // CSDPDOCUMENT_H