epoc32/include/sdpmediafield.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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