/*

* 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          : SdpFmtAttributeField.h

* Part of       : SDP Codec

* Interface     : SDK API, SDP Codec API

* Version       : 1.0

*

*/

#ifndef CSDPFMTATTRIBUTEFIELD_H

#define CSDPFMTATTRIBUTEFIELD_H

//  INCLUDES

#include <e32base.h>

#include <stringpool.h>

// FORWARD DECLARATIONS

class RReadStream;

class RWriteStream;

class CSdpAttributeField;

class TSdpRtpmapValue;

// CLASS DECLARATION

/**

 *  @publishedAll

 *  @released

 *

 *	This class encapsulates the attribute field of the Session Description

 *  Protocol for media format/payload type level attributes. Media and session

 *  level attributes are supported by the CSdpAttributeField class. 

 *

 *	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 CSdpFmtAttributeField : public CBase

	{

    public: // Constructors and destructor

        /**

         *	Constructs a new media format level attribute field.

		 * 

		 *	@param aText A string containing a correctly 

         *         formatted field value terminated by a CRLF.

         *  @return a new instance.

         */

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

        /**

         *	Constructs a new media format level attribute field  and adds the 

         *  pointer to the cleanup stack.

		 *			 

         *	@param aText A string containing a correctly 

         *         formatted field value terminated by a CRLF.

         *	@return a new instance.

         */

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

        /**

         *	Constructs a new media level format attribute field.

		 *

         *	@param aAttribute The attribute name. It can be a pre-defined

         *         name in the SDP string pool or defined by the client.

         *	@param aFormat A valid format/payload identifier 

         *         used in the format list of the media description.

         *	@param aValue A valid attribute value or an empty 

         *         descriptor to omit the value part.

         *	@return a new instance.

		 */

		IMPORT_C static CSdpFmtAttributeField* NewL(

            RStringF aAttribute, const TDesC8& aFormat, const TDesC8& aValue );

        /**

         *	Constructs a new media format level attribute field and adds the 

         *  pointer to the cleanup stack.

		 *

         *	@param aAttribute The attribute name. It can be a pre-defined 

         *         name in the SDP string pool or defined by the client.

         *	@param aFormat A valid format/payload identifier 

         *         used in the format list of the media description.

         *	@param aValue A valid attribute value or an empty 

         *         descriptor to omit the value part.

         *	@return a new instance.

		 */

		IMPORT_C static CSdpFmtAttributeField* NewLC(

            RStringF aAttribute, const TDesC8& aFormat, const TDesC8& aValue );

		/**

		 *	Deletes the resources held by the instance.

		 */

		IMPORT_C ~CSdpFmtAttributeField();

    public: // New functions

		/**

		 *	Outputs the field formatted according to SDP syntax and including

		 *  the terminating CRLF.

		 * 

		 *	@param aStream Stream used for output. On return 

         *         the stream includes correctly formatted attribute field.

		 */

		IMPORT_C void EncodeL( RWriteStream& aStream ) const;

		/**

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

		 *

		 *	@return a new instance.

		 */

		IMPORT_C CSdpFmtAttributeField * CloneL() const;

		/**	

		 *	Compares this instance to another for equality. 

		 *

		 *	@param aObj The instance to compare to.

		 *	@return ETrue if equal, EFalse if not.

		 */

		IMPORT_C TBool operator== ( const CSdpFmtAttributeField& aObj ) const;

		/**

		 *	Gets the attribute.

		 *	

		 *	@return	The attribute name. The name can be pre-defined 

         *          name in the SDP string table or defined by the client.

         */

		IMPORT_C RStringF Attribute() const;

		/**

		 *	Gets the format.

		 *	

		 *	@return	The format.

		 */

		IMPORT_C const TDesC8& Format() const;

		/**

		 *	Gets the attribute value.

		 *	

		 *	@return The value  or an empty descriptor if there is no value part.

		 */

		IMPORT_C const TDesC8& Value() const;

		/**

		 *	Sets the attribute, format/payload type and attribute value.

		 *

         *	@param aAttribute A valid attribute name. It can be a 

         *         pre-defined name in the SDP string pool or defined by 

         *         the client.

         *	@param aFormat A valid format/payload identifier 

         *         used in the formatlist of the media description.

         *	@param aValue A valid attribute value or an empty 

         *         descriptor to omit the value part.

         *  @leave KErrSdpCodecMediaAttributeField if aAttribute is not rtpmap

         *         or fmtp attribute.

		 */

		IMPORT_C void SetL(

            RStringF aAttribute, const TDesC8& aFormat, const TDesC8& aValue );

    public: // Internal to codec

        /**

         *  Externalizes the object to stream

         *

         *  @param aStream Stream where the object's state will be stored

         */

		void ExternalizeL( RWriteStream& aStream ) const;

        /**

         *  Creates object from the stream data

         *

         *  @param aStream Stream where the object's state will be read        

         *  @return Initialized object

         */

		static CSdpFmtAttributeField* InternalizeL( RReadStream& aStream );

        /**

         *  Returns attribute field

         *

         *  @return Attribute field

         */

        const CSdpAttributeField* AttributeField() const;

    private: // New methods

        /**

         *  Creates object from the stream data.

         *	Does the "2nd phase construction" of internalization.

         *

         *  @param aStream Stream where the object's state will be read

         */

        void DoInternalizeL( RReadStream& aStream );

        /**

         *  Formats value parameters

         *

         *  @param aField Attribute field object

         */

        void FormatValueParamsL( CSdpAttributeField* aField );

    private: // Construction and destruction

        /**

         *  Constructor

         */

        CSdpFmtAttributeField();

        /**

         *  Second phase construction

         *         

         *  @param aText A string containing a correctly formatted field value

		 *         terminated by a CRLF.

         */

        void ConstructL( const TDesC8& aText );

        /**

         *  Second phase construction

         *

         *	@param aAttribute The attribute from the pre-defined SDP string 

		 *         table or defined by the user

         *	@param aFormat A valid format/payload identifier used in the format

		 *         list of the media description.

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

		 *         to omit the value part.         

		 */

		void ConstructL(

            RStringF aAttribute, const TDesC8& aFormat, const TDesC8& aValue );    

        /**

         *  Decode format parameter from string

         *

         *	@param aText A text includeing format parameter.

		 */

        void DecodeFormatL(const TDesC8& aText);

		void __DbgTestInvariant() const;

    private:

        RStringPool iPool;

        CSdpAttributeField* iAttributeField;       

		/** Pointer to the format part*/

		TPtrC8 iFormat;

        /** Pointer to the format parameters*/

		TPtrC8 iValuePart;

	};

#endif // CSDPFMTATTRIBUTEFIELD_H