/*

 * 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          : 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 <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