/*

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

 * Part of       : SDP Codec

 * Interface     : SDK API, SDP Codec API

 * Version       : 1.0

 *

 */

 #ifndef CSDPCONNECTIONFIELD_H

 #define CSDPCONNECTIONFIELD_H

 //  INCLUDES

 #include <e32base.h>

 #include <in_sock.h>

 #include <stringpool.h>

 // CONSTANTS

 const TUint KDefaultNumOfAddress = 1;

 // FORWARD DECLARATIONS

 class RReadStream;

 class RWriteStream;

 // CLASS DECLARATION

 /**

  *  @publishedAll

  *  @released

  *

  *	This class encapsulates the connection information field of 

  *  the Session Description Protocol.

  *

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

 	{

     public: // Constructors and destructor

         /**

          *	Constructs a new connection field.

 		 * 

          *	@param aText A string containing a correctly 

          *         formatted field value terminated by a CRLF.

          *	@return a new instance.

          */

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

         /**

          *	Constructs a new connection 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 CSdpConnectionField* DecodeLC( const TDesC8& aText );

         /**

          *	Constructs a new connection field.

 		 *	Also sets the network type to "IN" and address type to "IP4" or

 		 *  "IP6" depending on the address family of aAddress.

 		 *	

 		 *	@param aAddress IP address from either KAfInet 

          *         or KAfInet6 family

          *  @param aTTL Time-To-Live for IP4 multicasts, set it as

          *         KErrNotFound if IPv6 multicast or IPv4 unicast

          *  @param aNumOfAddress Number of addresses in multicast,

          *         if unicast, must be 1

          *	@return a new instance.

          */

 		IMPORT_C static CSdpConnectionField* NewL(            

             const TInetAddr& aAddress,

             TInt aTTL = KErrNotFound, 

             TUint aNumOfAddress = KDefaultNumOfAddress );

         /**

          *	Constructs a new connection field.

 		 *	

          *	@param aNetType A valid network type name from the pre-

          *              defined SDP string table or defined by the user.

 		 *  @paramaAddressType A valid address type name from the 

          *              pre-defined SDP string table or defined by the user.

 		 *	@param  const TDesC8& aAddress: A valid address of the address type.

          *              Can contain TTL & number of addresses parameter as well.

          *	@return a new instance.

          */

 		IMPORT_C static CSdpConnectionField* NewL(

 			RStringF aNetType, 

 			RStringF aAddressType, 

 			const TDesC8& aAddress );

 		/**

          *	Constructs a new connection field and adds the pointer to the 

          *  cleanup stack. Also sets the network type to "IN" and address type

 		 *	to "IP4" or "IP6" depending on the address family of aAddress.

 		 *

 		 *	@param aAddress IP address from either KAfInet 

          *              or KAfInet6 family

          *  @param aTTL Time-To-Live for IP4 multicasts, set it as

          *              KErrNotFound if IPv6 multicast or IPv4 unicast

          *  @param aNumOfAddress Number of addresses in multicast,

          *              if unicast, must be 1

          *	@return a new instance.

          */

 		IMPORT_C static CSdpConnectionField* NewLC(       

             const TInetAddr& aAddress, 

             TInt aTTL = KErrNotFound,

             TUint aNumOfAddress = KDefaultNumOfAddress );

         /**

          *	Construct a new connection field  and adds the pointer to the

          *  cleanup stack.

 		 *	

          *	@param aNetType A valid network type name from the pre-

          *         defined SDP string table or defined by the user

 		 *  @paramaAddressType A valid address type name from the 

          *              pre-defined SDP string table or defined by the user

 		 *	@param  const TDesC8& aAddress: A valid address of the address type.

          *              Can contain TTL & number of addresses parameter as well.

          *	@return a new instance.

          */

 		IMPORT_C static CSdpConnectionField* NewLC(

             RStringF aNetType, RStringF aAddressType, const TDesC8& aAddress );

 		/**

 		 *	Deletes the resources held by the instance.

 		 */

 		IMPORT_C ~CSdpConnectionField();

     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 connection field.

 		 */

 		IMPORT_C void EncodeL( RWriteStream& aStream ) const;

 		/**

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

 		 *

 		 *	@return a new instance.

 		 */

 		IMPORT_C CSdpConnectionField* CloneL() const;

 		/**	

 		 *	Compares this instance to another for equality.

 		 *

 		 *	@param const CSdpConnectionField& aObj: The instance to compare to.

 		 *	@return ETrue if equal, EFalse if not.

 		 */

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

 		/**

 		 *	Gets the network type that is from the pre-defined SDP string table

          *  or given by the user.

 		 *

 		 *	@return The network type.

 		 */

 		IMPORT_C RStringF NetType() const;

 		/**

 		 *	Gets the address type that is from the pre-defined SDP string table 

          *  or given by the user.

 		 *

 		 *	@return The address type.

 		 */

 		IMPORT_C RStringF AddressType() const;

 		/**

 		 *	Gets the address.

 		 *

 		 *	@return Address as an IP address or null if it is

          *          not an IP address. This may be e.g. when the address

 		 *          has been specified as a FQDN. In this case, the address

          *          can be accessed using the other getters.

 		 */

 		IMPORT_C const TInetAddr* InetAddress() const;

 		/**

 		 *	Gets the address.

 		 *

 		 *  @return Address as a string.

 		 */

 		IMPORT_C const TDesC8& Address() const;

 		/**

 		 *	Sets the address, network and address type. Also sets the network 

 		 *	type to "IN" and address type to "IP4" or "IP6" depending on the 

 		 *  address family of aAddress.

 		 *

 		 *	@param aValue The new address.

          *  @param aTTL Time-To-Live for IP4 multicasts, set it as

          *         KErrNotFound if IPv6 multicast or IPv4 unicast

          *  @param aNumOfAddress Number of addresses in multicast,

          *         if unicast, must be 1.

          *  @leave KErrSdpCodecConnectionField ifaddress to be set is wrongly 

          *         formatted.

          */

 		IMPORT_C void SetInetAddressL( const TInetAddr& aValue, 

                                    TInt aTTL = KErrNotFound,

                                    TUint aNumOfAddress = KDefaultNumOfAddress);

 		/**

 		 *	Sets the address, network and address type.

 		 *

          *	@param aNetType A valid network type name from the pre-

          *         defined SDP string table or defined by the user

 		 *  @param aAddressType A valid address type name from the 

          *         pre-defined SDP string table or defined by the user

 		 *	@param aAddress A valid address of the address type.

 		 */

 		IMPORT_C void SetAddressL( RStringF aNetType, 

 								   RStringF aAddressType, 

 								   const TDesC8& aAddress );

         /**

          *  Gets TTL attribute.

          *

          *  @return TTL or KErrNotFound, if one is not available for the address

          */

         IMPORT_C TInt TTLValue() const;

         /**

          *  Sets TTL attribute (only valid for IP4 multicasts).

          *  Leaves if trying to set TTL to address that doesn't support it.

          *

          *  @param aTTL Time-To-Live for IP4 multicasts

          *	@leave KErrSdpCodecConnectionField if aTTL is invalid.

          */

         IMPORT_C void SetTTLL( TInt aTTL );

         /**

          *  Gets the number of addresses (can be more than 1 for multicasts).

          *  Multicast addresses are contiguously allocated above the base 

          *  address.

          *

          *  @return Number of addresses

          */

         IMPORT_C TInt NumOfAddress() const;

         /**

          *  Sets the number of addreses allocated for multicast. 

          *  

          *	@param aNumOfAddress Number of addresses in multicast

          *  @leave KErrSdpCodecConnectionField if the address is unicast.

          */

         IMPORT_C void SetNumOfAddressL( TUint aNumOfAddress );

     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 CSdpConnectionField* InternalizeL( RReadStream& aStream );

     private:    // Internal

         /**

          *  Constructor

          */

         CSdpConnectionField();

         /**

          *  2nd phase constructor

          *

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

 		 *         terminated by a CRLF.         

          */         

         void ConstructL( const TDesC8& aText );

         /**

          *  2nd phase constructor

          *

          *	@param aAddress IP address from either KAfInet or KAfInet6 family

          *  @param aTTL Time-To-Live for IP4 multicasts

          *  @param aNumOfAddress Nubmer of addresses in multicast

          */

         void ConstructL( const TInetAddr& aAddress,

                          TInt aTTL, TUint aNumOfAddress );

         /**

          *  2nd phase constructor

          *

          *	@param aNetType A valid network type name from the pre-defined

 		 *         SDP string table or defined by the user

 		 *  @param aAddressType A valid address type name from the pre-defined

 		 *         SDP string table or defined by the user

 		 *	@param aAddress A valid address of the address type

          */

         void ConstructL( RStringF aNetType, RStringF aAddressType, 

 	                     const TDesC8& aAddress );

         /**

          *  Checks if the address is valid against given arguments

          *

          *  @param aAddressTypeIP4 The given type of address (EFalse = IP6)

          *  @param aAddress Address with possibly TTL & number of addresses

          *  @return error code (KErrNone if valid)

          */

         TInt IsValidAddress( TBool aAddressTypeIP4,

                              const TDesC8& aAddress ) const;

         /**

          *  Checks if the address is valid against given arguments

          *         

          *  @param aAddress Address in TInetAddr format

          *  @param aTTL TTL attribute

          *  @param aNumOfAddress Number off addresses

          *  @return error code (KErrNone if valid)

          */

         TInt IsValidAddress( const TInetAddr& aAddress, 

                              TInt aTTL, TUint aNumOfAddress ) const;

         /**

          *  Parses address field

          *

          *  @param aAddressTypeIP4 The given type of address (EFalse = IP6)

          *  @param aAddress Address with possibly TTL & number of addresses

          *  @param aTTL TTL value is stored here (or KErrNotFound)

          *  @param aNumberOfAddresses Range of addreses

          *  @return The address

          */

         HBufC8* ParseAddressFieldL( TBool aAddressTypeIP4,

                                     const TDesC8& aAddress,

                                     TInt& aTTL,

                                     TUint& aNumberOfAddresses ) const;

         /**

          *  Parses IP4 address

          *

          *  @param aPos Position of the (first) separation mark         

          *  @param aTTL TTL value is stored here (or KErrNotFound)

          *  @param aAddr Addres in TInetAddr format

          *  @param aAddress The whole address field

          *  @param aNumberOfAddresses Range of addreses

          *  @return The address

          */

         HBufC8* ParseIP4AddressL( TInt aPos, 

                                   TInetAddr& aAddr,

                                   const TDesC8& aAddress,

                                   TInt& aTTL,

                                   TUint& aNumberOfAddresses ) const;

         /**

          *  Parses IP6 address

          *

          *  @param aPos Position of the (first) separation mark         

          *  @param aTTL TTL value is stored here (or KErrNotFound)

          *  @param aAddr Addres in TInetAddr format

          *  @param aAddress The whole address field

          *  @param aNumberOfAddresses Range of addreses

          *  @return The address

          */

         HBufC8* ParseIP6AddressL( TInt aPos, 

                                   TInetAddr& aAddr,

                                   const TDesC8& aAddress,

                                   TInt& aTTL,

                                   TUint& aNumberOfAddresses ) const;

         /**

          *  Copies given network type to iNetType and verifies aNetType to

          *  be valid

          *

          *  @param aNetType Given network type                

          */

         void CopyNetTypeL( const TDesC8& aNetType );

         /**

          *  Copies given address type to iAddressType and verifies aAddrType

          *  to be valid

          * 

          *  @param aAddrType Given address type     

          */

         void CopyAddressTypeL( const TDesC8& aAddrType );

         /**

          *  Copies address to iAddress, and initalizes TTL & number of addresses,

          *  leaves on error

          *  

          *  @param aAddress Address string, which can also contain TTL

          *                  and number of addresses attributes

          */

         void CopyAddressL( const TDesC8& aAddress, RStringPool aPool );

     private:    // Data

         // <network type>

         RStringF iNetType;

         // <address type>        

         RStringF iAddressType;

         // mutable TInetAddr for InetAddress()

         mutable TInetAddr iInetAddress;

         // Address in text format

         HBufC8* iAddress;

         // TTL for IP4 multicast addresses

         TInt iTTL;

         // Number of addresses

         TUint iNumOfAddress;

         // String pool

         RStringPool iPool;

 		void __DbgTestInvariant() const;

 	};

 #endif // CSDPCONNECTIONFIELD_H