/*

 * 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