1 /*

     2 * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name          : SdpMediaField.h

    16 * Part of       : SDP Codec

    17 * Interface     : SDK API, SDP Codec API

    18 * Version       : 1.0

    19 *

    20 */

    21 

    22 

    23 

    24 #ifndef CSDPMEDIAFIELD_H

    25 #define CSDPMEDIAFIELD_H

    26 

    27 //  INCLUDES

    28 #include <e32base.h>

    29 #include <stringpool.h>

    30 

    31 // FORWARD DECLARATIONS

    32 class RReadStream;

    33 class RWriteStream;

    34 class CSdpConnectionField;

    35 class CSdpBandwidthField;

    36 class CSdpAttributeField;

    37 class CSdpKeyField;

    38 class CSdpFmtAttributeField;

    39 class CSdpCodecParseUtil;

    40 

    41 // CLASS DECLARATION

    42 /**

    43  *  @publishedAll

    44  *  @released

    45  *

    46  *	This class encapsulates the media description field and related media

    47  *  specific subfields of the Session Description Protocol.

    48  *

    49  *	The normative reference for correct formatting and values is

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

    51  *  member documentation. The implementation supports this normative

    52  *  reference, but does not enforce it fully. 

    53  *

    54  *  @lib sdpcodec.lib

    55  */

    56 class CSdpMediaField : public CBase

    57 	{

    58 

    59 	public:

    60 

    61 

    62     public: // Constructors and destructor

    63         /**

    64          *	Constructs a new media description field.

    65 		 *	

    66          *	@param aText A correctly formatted media field 

    67          *         terminated by a CRLF followed by zero or more media 

    68          *         attribute fields separated by a CRLF.

    69          *	@param aRecurse If ETrue, attempts to construct also media 

    70          *         attributes following the CRLF terminating the media field.

    71          *	@return a new instance.

    72          */

    73 		IMPORT_C static	CSdpMediaField* DecodeL(const TDesC8& aText,

    74 												TBool aRecurse = ETrue);

    75 

    76         /**

    77          *	Constructs a new media description field and adds the pointer to 

    78          *  the cleanup stack.

    79 		 *	

    80          *	@param aText A correctly formatted media field 

    81          *         terminated by a CRLF followed by zero or more media 

    82          *         attribute fields separated by a CRLF.

    83          *	@param aRecurse If ETrue, attempts to construct also media 

    84          *         attributes following the CRLF terminating the media field.

    85 		 *  @return a new instance.

    86          */

    87 		IMPORT_C static	CSdpMediaField* DecodeLC(const TDesC8& aText,

    88 												 TBool aRecurse = ETrue);

    89 

    90         /**

    91          *	Constructs a new media description field.

    92 		 *  The optional portcount component of the field is initialized to 1.

    93 		 *

    94 		 *	@param aMedia A valid media type name.

    95          *	@param aPort Port number.

    96          *	@param aProtocol A valid media protocol name.

    97          *	@param aFormatList A valid format list.

    98          *	@return a new instance.

    99          */

   100 		IMPORT_C static CSdpMediaField* NewL(RStringF aMedia,

   101 											 TUint aPort,

   102 											 RStringF aProtocol,

   103 											 const TDesC8& aFormatList);

   104 

   105 		/**

   106          *	Constructs a new media description field and adds the pointer to 

   107          *  the cleanup stack.

   108 		 *  The optional portcount component of the field is initialized to 1.

   109 		 *	

   110 		 *	@param aMedia A valid media type name.

   111          *	@param aPort Port number.

   112          *	@param aProtocol A valid media protocol name.

   113          *	@param aFormatList A valid format list.

   114          *	@return a new instance.

   115          */

   116 		IMPORT_C static CSdpMediaField* NewLC(RStringF aMedia,

   117 											  TUint aPort,

   118 										      RStringF aProtocol,

   119 										      const TDesC8& aFormatList);

   120 

   121 		/**

   122 		 *	Deletes the resources held by the instance.

   123 		 */

   124 		IMPORT_C ~CSdpMediaField();

   125 

   126     public: // New functions

   127 		/**

   128 		 *	Outputs the field formatted according to SDP syntax and including

   129 		 *  the terminating CRLF. Optionally output also the related media 

   130 		 *  level fields. 

   131 		 * 

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

   133          *         stream includes correctly formatted media field with 

   134          *         media part fields if aRecurse is defined to ETrue.

   135 		 *	@param aRecurse Flag to specify whether to output media 

   136 		 *         attributes also (ETrue) or only the media field (EFalse).

   137 		 */

   138 		IMPORT_C void 

   139 			EncodeL(RWriteStream& aStream, TBool aRecurse = ETrue) const;

   140 

   141 		/**

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

   143 		 *  Optionally also related subfields are cloned.

   144 		 *

   145 		 *	@param aRecurse Flag to specify whether to clone subfields

   146 		 *         also (ETrue) or only the media field (EFalse).

   147 		 *	@return a new instance.

   148 		 */

   149 		IMPORT_C CSdpMediaField * CloneL(TBool aRecurse = ETrue) const;

   150 

   151 		/**	

   152 		 *	Compares this instance to another for equality. Subfields are

   153 		 *  included in the comparison if present.

   154 		 *

   155 		 *	@param aObj The instance to compare to.

   156 		 *	@return ETrue if equal, EFalse if not.

   157 		 */

   158 		IMPORT_C TBool operator == (const CSdpMediaField& aObj) const;

   159 

   160 		/**

   161 		 *	Checks the consistency between the media field and it's subfields.

   162 		 *  In particular, this function checks that each format specific 

   163 		 *  attribute is related to a format in the format list of the

   164 		 *  media field.

   165 		 *

   166 		 *	@return	ETrue if media description is consistent and EFalse if not.

   167 		 */

   168 		IMPORT_C TBool IsValid() const;

   169 

   170 		/**

   171 		 *	Gets the media type.

   172 		 *

   173 		 *	@return The media type.

   174 		 */

   175 		IMPORT_C RStringF Media() const;

   176 

   177 		/**

   178 		 *	Sets the media type.

   179 		 *

   180 		 *	@param aMedia The media type.

   181 		 *  @leave KErrSdpCodecMediaField if aMedia is not valid character

   182 		 */

   183 		IMPORT_C void SetMediaL(RStringF aMedia);

   184 

   185 		/**

   186 		 *	Gets the media protocol.

   187 		 *

   188 		 *	@return The media protocol.

   189 		 */

   190 		IMPORT_C RStringF Protocol() const;

   191 

   192 		/**

   193 		 *	Sets the media protocol.

   194 		 *

   195 		 *	@param aProtocol The media protocol.

   196 		 *  @leave KErrSdpCodecMediaField if 

   197 		 *		   aProtocol containing two elements divided by slash are not 

   198          *         valid tokens.

   199 		 */

   200 		IMPORT_C void SetProtocolL(RStringF aProtocol);

   201 

   202 		/**

   203 		 *	Gets the port number.

   204 		 *

   205 		 *	@return The port number.

   206 		 */

   207 		IMPORT_C TUint Port() const;

   208 

   209 		/**

   210 		 *	Sets the port number.

   211 		 *

   212 		 *	@param aPort The port number.

   213 		 *  @leave KErrSdpCodecMediaField if port is not valid number as 

   214          *         defined in draft-ietf-mmusic-sdp-new-14

   215 		 */

   216 		IMPORT_C void SetPortL(TUint aPort);

   217 

   218 		/**

   219 		 *	Gets the port count.

   220 		 *

   221 		 *	@return The port count.

   222 		 */

   223 		IMPORT_C TUint PortCount() const;

   224 

   225 		/**

   226 		 *	Sets the port count.

   227 		 *

   228 		 *	@param aCount The port count that must be greater than zero.

   229 		 *  @leave KErrSdpCodecMediaField if aCount equals to zero.

   230 		 */

   231 		IMPORT_C void SetPortCountL(TUint aCount);

   232 

   233 		/**

   234 		 *	Gets the format list.

   235 		 *

   236 		 *	@return The format list.

   237 		 */

   238 		IMPORT_C const TDesC8& FormatList() const;

   239 

   240 		/**

   241 		 *	Sets the format list.

   242 		 *  The format list should contain one or more format tokens separated

   243 		 *  by a single whitespace character.

   244 		 *

   245 		 *	@param aValue A valid format list.

   246 		 *  @leave KErrSdpCodecMediaField if aValue contains invalid tokens

   247 		 */

   248 		IMPORT_C void SetFormatListL(const TDesC8& aValue);

   249 

   250 		/**

   251 		 *	Return the media level info field value.

   252 		 *

   253 		 *	@return The value or an empty descriptor if not present.

   254 		 */

   255 		IMPORT_C const TDesC8& Info() const;

   256 

   257 		/**

   258 		 *	Sets the media level info field value.

   259 		 *

   260 		 *	@param aValue A valid info field value.

   261 		 *	@leave KErrSdpCodecMediaInfoField if aValue is not KNullDesC8 or 

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

   263 		 */

   264 		IMPORT_C void SetInfoL(const TDesC8& aValue);

   265 

   266 		/**

   267 		 *	Gets the media level encryption key field.

   268 		 *	Note, that the ownership is not transferred and

   269 		 *	the instance must not be deleted by the caller.

   270 		 *

   271 		 *	@return Encryption key field or null if not present.

   272 		 */

   273 		IMPORT_C CSdpKeyField* Key();

   274 

   275 		/**

   276 		 *	Gets the media level encryption key field.

   277 		 *

   278 		 *	@return Encryption key field or null if not present.

   279 		 */

   280 		IMPORT_C const CSdpKeyField* Key() const;

   281 

   282 		/**

   283 		 *	Sets or removes the media level encryption key field.

   284 		 *

   285 		 *	@param aObj The new key field or null if field is 

   286          *         to be removed. Ownership of the referenced object

   287 		 *         is transferred to the media field instance.

   288 		 */

   289 		IMPORT_C void SetKey(CSdpKeyField* aObj);

   290 

   291 		/**

   292 		 *	Gets the set of media format level attributes.

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

   294 		 *

   295 		 *	The objects referenced from the array are owned by the media

   296 		 *  field instance and must not be deleted. An object can be

   297 		 *  removed from the media description by setting the corresponding

   298 		 *  element to zero. By doing so, the calling party receives ownership

   299 		 *  of the removed object.

   300 		 *

   301 		 *	@return The set of media format level attributes.

   302 		 */

   303 		IMPORT_C RPointerArray<CSdpFmtAttributeField>& FormatAttributeFields();

   304 

   305 		/**

   306 		 *	Gets the set of media level, format independent attributes.

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

   308 		 *

   309 		 *	The objects referenced from the array are owned by the media

   310 		 *  field instance and must not be deleted. An object can be

   311 		 *  removed from the media description by setting the corresponding

   312 		 *  element to zero. By doing so, the calling party receives ownership

   313 		 *  of the removed object.

   314 		 *

   315 		 *	@return The set of media level attributes.

   316 		 */

   317 		IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();

   318 

   319 		/**

   320 		 *	Gets the set of media level bandwidth fields.

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

   322 		 *

   323 		 *	The objects referenced from the array are owned by the media

   324 		 *  field instance and must not be deleted. An object can be

   325 		 *  removed from the media description by setting the corresponding

   326 		 *  element to zero. By doing so, the calling party receives ownership

   327 		 *  of the removed object.

   328 		 *

   329 		 *	@return The set of media level bandwidth fields.

   330 		 */

   331 		IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();

   332 

   333 		/**

   334 		 *	Gets the set of media level connection fields.

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

   336 		 *

   337 		 *	The objects referenced from the array are owned by the media

   338 		 *  field instance and must not be deleted. An object can be

   339 		 *  removed from the media description by setting the corresponding

   340 		 *  element to zero. By doing so, the calling party receives ownership

   341 		 *  of the removed object.

   342 		 *

   343 		 *	@return The set of media level connection fields.

   344 		 */

   345 		IMPORT_C RPointerArray<CSdpConnectionField>& ConnectionFields();

   346 

   347 		/**

   348 		 *	Removes a specific format from the media description.

   349 		 *  The function will remove the named format from the format list if

   350 		 *  found and then delete all format level attributes of type 

   351 		 *  CSdpFmtAttributeField related to the removed format. 

   352 		 *

   353 		 *	@param aFormat The name of the format to remove.

   354 		 */

   355 		IMPORT_C void RemoveFormatL(const TDesC8& aFormat);

   356 

   357 		/**

   358 		 *	Removes all formats except one from the media description.

   359 		 *  The function will set the format list to only contain the one

   360 		 *  format to keep and then delete all format level attributes that

   361 		 *  are related to the removed formats. If the format is not found

   362 		 *  from the format list, it is added there. If there are no format

   363 		 *  level attributes for the specified format, the format level

   364 		 *  attribute set will be empty.

   365 		 *

   366 		 *	@param aFormat The name of the format to keep after 

   367 		 *         removing all others.

   368 		 */

   369 		IMPORT_C void KeepFormatL(const TDesC8& aFormat);

   370 

   371 		/**

   372 		 *	Sets this media description into rejected state.

   373 		 *  The rejected state is defined by the offer/answer model in

   374 		 *  RFC3264. The function sets the port number to 0 and removes

   375 		 *  all formats except one. The remaining format is determined

   376 		 *  by the implementation.

   377 		 */

   378 		IMPORT_C void RejectMedia();

   379 

   380     public:

   381 		/**

   382 		 *	Shows if contact is present

   383 		 *

   384 		 *	@return ETrue if contact present, otherwise EFalse

   385 		 */

   386 		TBool IsContactPresent() const;

   387 		

   388 		/**

   389          *  Externalizes the object to stream

   390          *

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

   392          */

   393 		void ExternalizeL(RWriteStream& aStream) const;

   394 		

   395 		/**

   396          *  Creates object from the stream data

   397          *

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

   399          *  @return Initialized object

   400          */

   401 		static CSdpMediaField* InternalizeL(RReadStream& aStream);

   402 

   403 	private:

   404 		CSdpMediaField();

   405 		void ConstructL();

   406 		void ConstructL(TBool aRecurse);

   407 		void ConstructL(RStringF aMedia, TUint aPort, RStringF aProtocol, 

   408 						const TDesC8& aFormatList);

   409 

   410 		void ConstructL(const CSdpMediaField& aSdpMediaField);

   411 		void DoInternalizeL(RReadStream& aStream);

   412 		void ParseL (const TDesC8& aText);

   413 		void ParseMediaL();

   414 		void ParseInformationL();

   415 		void ParseConnectionL();

   416 		void ParseBandwithL();

   417 		void ParseEncryptionKeyL();

   418 		void ParseAttributeFieldsL();

   419 		TDesC8& GetTokenFromStreamL(RReadStream& aStream);

   420 

   421 

   422 		CSdpMediaField(const CSdpMediaField&); // Hidden.

   423 		CSdpMediaField& operator = (const CSdpMediaField&); // Hidden

   424 

   425     private: // Data

   426 		HBufC8* iInfo;

   427 		CSdpKeyField* iSdpKeyField;

   428 		RArray<TPtrC8> iElementArray;

   429 		RStringPool iPool;

   430 		TBool iRecurse;

   431 		RStringF iMedia;

   432 		RStringF iProtocol;

   433 		TUint iPort;

   434 		TUint iPortCount;

   435 		HBufC8* iFormatList;

   436 		RPointerArray<CSdpBandwidthField>* iBandwidthFields;

   437 		RPointerArray<CSdpAttributeField>* iAttributeFields;

   438 		RPointerArray<CSdpConnectionField>* iConnectionFields;

   439 		RPointerArray<CSdpFmtAttributeField>* iFmtAttrFields;

   440 		HBufC8* iToken;

   441 		CSdpCodecParseUtil* iSdpCodecParseUtil;

   442 	};

   443 

   444 #endif // CSDPMEDIAFIELD_H