1 sdpmediafield.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 "_sdpdefs.h"

    30 #include <stringpool.h>

    31 

    32 // FORWARD DECLARATIONS

    33 class RReadStream;

    34 class RWriteStream;

    35 class CSdpConnectionField;

    36 class CSdpBandwidthField;

    37 class CSdpAttributeField;

    38 class CSdpKeyField;

    39 class CSdpFmtAttributeField;

    40 class CSdpCodecParseUtil;

    41 

    42 // CLASS DECLARATION

    43 /**

    44  *  @publishedAll

    45  *  @released

    46  *

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

    48  *  specific subfields of the Session Description Protocol.

    49  *

    50  *	The normative reference for correct formatting and values is

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

    52  *  member documentation. The implementation supports this normative

    53  *  reference, but does not enforce it fully. 

    54  *

    55  *  @lib sdpcodec.lib

    56  */

    57 class CSdpMediaField : public CBase

    58 	{

    59 

    60 	public:

    61 

    62 

    63     public: // Constructors and destructor

    64         /**

    65          *	Constructs a new media description field.

    66 		 *	

    67          *	@param aText A correctly formatted media field 

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

    69          *         attribute fields separated by a CRLF.

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

    71          *         attributes following the CRLF terminating the media field.

    72          *	@return a new instance.

    73          */

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

    75 												TBool aRecurse = ETrue);

    76 

    77         /**

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

    79          *  the cleanup stack.

    80 		 *	

    81          *	@param aText A correctly formatted media field 

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

    83          *         attribute fields separated by a CRLF.

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

    85          *         attributes following the CRLF terminating the media field.

    86 		 *  @return a new instance.

    87          */

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

    89 												 TBool aRecurse = ETrue);

    90 

    91         /**

    92          *	Constructs a new media description field.

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

    94 		 *

    95 		 *	@param aMedia A valid media type name.

    96          *	@param aPort Port number.

    97          *	@param aProtocol A valid media protocol name.

    98          *	@param aFormatList A valid format list.

    99          *	@return a new instance.

   100          */

   101 		IMPORT_C static CSdpMediaField* NewL(RStringF aMedia,

   102 											 TUint aPort,

   103 											 RStringF aProtocol,

   104 											 const TDesC8& aFormatList);

   105 

   106 		/**

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

   108          *  the cleanup stack.

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

   110 		 *	

   111 		 *	@param aMedia A valid media type name.

   112          *	@param aPort Port number.

   113          *	@param aProtocol A valid media protocol name.

   114          *	@param aFormatList A valid format list.

   115          *	@return a new instance.

   116          */

   117 		IMPORT_C static CSdpMediaField* NewLC(RStringF aMedia,

   118 											  TUint aPort,

   119 										      RStringF aProtocol,

   120 										      const TDesC8& aFormatList);

   121 

   122 		/**

   123 		 *	Deletes the resources held by the instance.

   124 		 */

   125 		IMPORT_C ~CSdpMediaField();

   126 

   127     public: // New functions

   128 		/**

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

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

   131 		 *  level fields. 

   132 		 * 

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

   134          *         stream includes correctly formatted media field with 

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

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

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

   138 		 */

   139 		IMPORT_C void 

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

   141 

   142 		/**

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

   144 		 *  Optionally also related subfields are cloned.

   145 		 *

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

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

   148 		 *	@return a new instance.

   149 		 */

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

   151 

   152 		/**	

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

   154 		 *  included in the comparison if present.

   155 		 *

   156 		 *	@param aObj The instance to compare to.

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

   158 		 */

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

   160 

   161 		/**

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

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

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

   165 		 *  media field.

   166 		 *

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

   168 		 */

   169 		IMPORT_C TBool IsValid() const;

   170 

   171 		/**

   172 		 *	Gets the media type.

   173 		 *

   174 		 *	@return The media type.

   175 		 */

   176 		IMPORT_C RStringF Media() const;

   177 

   178 		/**

   179 		 *	Sets the media type.

   180 		 *

   181 		 *	@param aMedia The media type.

   182 		 *  @leave KErrSdpCodecMediaField if aMedia is not valid character

   183 		 */

   184 		IMPORT_C void SetMediaL(RStringF aMedia);

   185 

   186 		/**

   187 		 *	Gets the media protocol.

   188 		 *

   189 		 *	@return The media protocol.

   190 		 */

   191 		IMPORT_C RStringF Protocol() const;

   192 

   193 		/**

   194 		 *	Sets the media protocol.

   195 		 *

   196 		 *	@param aProtocol The media protocol.

   197 		 *  @leave KErrSdpCodecMediaField if 

   198 		 *		   aProtocol containing two elements divided by slash are not 

   199          *         valid tokens.

   200 		 */

   201 		IMPORT_C void SetProtocolL(RStringF aProtocol);

   202 

   203 		/**

   204 		 *	Gets the port number.

   205 		 *

   206 		 *	@return The port number.

   207 		 */

   208 		IMPORT_C TUint Port() const;

   209 

   210 		/**

   211 		 *	Sets the port number.

   212 		 *

   213 		 *	@param aPort The port number.

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

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

   216 		 */

   217 		IMPORT_C void SetPortL(TUint aPort);

   218 

   219 		/**

   220 		 *	Gets the port count.

   221 		 *

   222 		 *	@return The port count.

   223 		 */

   224 		IMPORT_C TUint PortCount() const;

   225 

   226 		/**

   227 		 *	Sets the port count.

   228 		 *

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

   230 		 *  @leave KErrSdpCodecMediaField if aCount equals to zero.

   231 		 */

   232 		IMPORT_C void SetPortCountL(TUint aCount);

   233 

   234 		/**

   235 		 *	Gets the format list.

   236 		 *

   237 		 *	@return The format list.

   238 		 */

   239 		IMPORT_C const TDesC8& FormatList() const;

   240 

   241 		/**

   242 		 *	Sets the format list.

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

   244 		 *  by a single whitespace character.

   245 		 *

   246 		 *	@param aValue A valid format list.

   247 		 *  @leave KErrSdpCodecMediaField if aValue contains invalid tokens

   248 		 */

   249 		IMPORT_C void SetFormatListL(const TDesC8& aValue);

   250 

   251 		/**

   252 		 *	Return the media level info field value.

   253 		 *

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

   255 		 */

   256 		IMPORT_C const TDesC8& Info() const;

   257 

   258 		/**

   259 		 *	Sets the media level info field value.

   260 		 *

   261 		 *	@param aValue A valid info field value.

   262 		 *	@leave KErrSdpCodecMediaInfoField if aValue is not KNullDesC8 or 

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

   264 		 */

   265 		IMPORT_C void SetInfoL(const TDesC8& aValue);

   266 

   267 		/**

   268 		 *	Gets the media level encryption key field.

   269 		 *	Note, that the ownership is not transferred and

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

   271 		 *

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

   273 		 */

   274 		IMPORT_C CSdpKeyField* Key();

   275 

   276 		/**

   277 		 *	Gets the media level encryption key field.

   278 		 *

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

   280 		 */

   281 		IMPORT_C const CSdpKeyField* Key() const;

   282 

   283 		/**

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

   285 		 *

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

   287          *         to be removed. Ownership of the referenced object

   288 		 *         is transferred to the media field instance.

   289 		 */

   290 		IMPORT_C void SetKey(CSdpKeyField* aObj);

   291 

   292 		/**

   293 		 *	Gets the set of media format level attributes.

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

   295 		 *

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

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

   298 		 *  removed from the media description by setting the corresponding

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

   300 		 *  of the removed object.

   301 		 *

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

   303 		 */

   304 		IMPORT_C RPointerArray<CSdpFmtAttributeField>& FormatAttributeFields();

   305 

   306 		/**

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

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

   309 		 *

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

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

   312 		 *  removed from the media description by setting the corresponding

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

   314 		 *  of the removed object.

   315 		 *

   316 		 *	@return The set of media level attributes.

   317 		 */

   318 		IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();

   319 

   320 		/**

   321 		 *	Gets the set of media level bandwidth fields.

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

   323 		 *

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

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

   326 		 *  removed from the media description by setting the corresponding

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

   328 		 *  of the removed object.

   329 		 *

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

   331 		 */

   332 		IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();

   333 

   334 		/**

   335 		 *	Gets the set of media level connection fields.

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

   337 		 *

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

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

   340 		 *  removed from the media description by setting the corresponding

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

   342 		 *  of the removed object.

   343 		 *

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

   345 		 */

   346 		IMPORT_C RPointerArray<CSdpConnectionField>& ConnectionFields();

   347 

   348 		/**

   349 		 *	Removes a specific format from the media description.

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

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

   352 		 *  CSdpFmtAttributeField related to the removed format. 

   353 		 *

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

   355 		 */

   356 		IMPORT_C void RemoveFormatL(const TDesC8& aFormat);

   357 

   358 		/**

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

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

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

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

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

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

   365 		 *  attribute set will be empty.

   366 		 *

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

   368 		 *         removing all others.

   369 		 */

   370 		IMPORT_C void KeepFormatL(const TDesC8& aFormat);

   371 

   372 		/**

   373 		 *	Sets this media description into rejected state.

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

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

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

   377 		 *  by the implementation.

   378 		 */

   379 		IMPORT_C void RejectMedia();

   380 

   381     public:

   382 		/**

   383 		 *	Shows if contact is present

   384 		 *

   385 		 *	@return ETrue if contact present, otherwise EFalse

   386 		 */

   387 		TBool IsContactPresent() const;

   388 		

   389 		/**

   390          *  Externalizes the object to stream

   391          *

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

   393          */

   394 		void ExternalizeL(RWriteStream& aStream) const;

   395 		

   396 		/**

   397          *  Creates object from the stream data

   398          *

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

   400          *  @return Initialized object

   401          */

   402 		static CSdpMediaField* InternalizeL(RReadStream& aStream);

   403 

   404 	private:

   405 		CSdpMediaField();

   406 		void ConstructL();

   407 		void ConstructL(TBool aRecurse);

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

   409 						const TDesC8& aFormatList);

   410 

   411 		void ConstructL(const CSdpMediaField& aSdpMediaField);

   412 		void DoInternalizeL(RReadStream& aStream);

   413 		void ParseL (const TDesC8& aText);

   414 		void ParseMediaL();

   415 		void ParseInformationL();

   416 		void ParseConnectionL();

   417 		void ParseBandwithL();

   418 		void ParseEncryptionKeyL();

   419 		void ParseAttributeFieldsL();

   420 		TDesC8& GetTokenFromStreamL(RReadStream& aStream);

   421 

   422 

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

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

   425 

   426     private: // Data

   427 		HBufC8* iInfo;

   428 		CSdpKeyField* iSdpKeyField;

   429 		RArray<TPtrC8> iElementArray;

   430 		RStringPool iPool;

   431 		TBool iRecurse;

   432 		RStringF iMedia;

   433 		RStringF iProtocol;

   434 		TUint iPort;

   435 		TUint iPortCount;

   436 		HBufC8* iFormatList;

   437 		RPointerArray<CSdpBandwidthField>* iBandwidthFields;

   438 		RPointerArray<CSdpAttributeField>* iAttributeFields;

   439 		RPointerArray<CSdpConnectionField>* iConnectionFields;

   440 		RPointerArray<CSdpFmtAttributeField>* iFmtAttrFields;

   441 		HBufC8* iToken;

   442 		CSdpCodecParseUtil* iSdpCodecParseUtil;

   443 	};

   444 

   445 #endif // CSDPMEDIAFIELD_H