2 * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * Name : SdpMediaField.h
17 * Interface : SDK API, SDP Codec API
24 #ifndef CSDPMEDIAFIELD_H
25 #define CSDPMEDIAFIELD_H
30 #include <stringpool.h>
32 // FORWARD DECLARATIONS
35 class CSdpConnectionField;
36 class CSdpBandwidthField;
37 class CSdpAttributeField;
39 class CSdpFmtAttributeField;
40 class CSdpCodecParseUtil;
47 * This class encapsulates the media description field and related media
48 * specific subfields of the Session Description Protocol.
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.
57 class CSdpMediaField : public CBase
63 public: // Constructors and destructor
65 * Constructs a new media description field.
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.
74 IMPORT_C static CSdpMediaField* DecodeL(const TDesC8& aText,
75 TBool aRecurse = ETrue);
78 * Constructs a new media description field and adds the pointer to
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.
88 IMPORT_C static CSdpMediaField* DecodeLC(const TDesC8& aText,
89 TBool aRecurse = ETrue);
92 * Constructs a new media description field.
93 * The optional portcount component of the field is initialized to 1.
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.
101 IMPORT_C static CSdpMediaField* NewL(RStringF aMedia,
104 const TDesC8& aFormatList);
107 * Constructs a new media description field and adds the pointer to
109 * The optional portcount component of the field is initialized to 1.
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.
117 IMPORT_C static CSdpMediaField* NewLC(RStringF aMedia,
120 const TDesC8& aFormatList);
123 * Deletes the resources held by the instance.
125 IMPORT_C ~CSdpMediaField();
127 public: // New functions
129 * Outputs the field formatted according to SDP syntax and including
130 * the terminating CRLF. Optionally output also the related media
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).
140 EncodeL(RWriteStream& aStream, TBool aRecurse = ETrue) const;
143 * Creates a new instance that is equal to the target.
144 * Optionally also related subfields are cloned.
146 * @param aRecurse Flag to specify whether to clone subfields
147 * also (ETrue) or only the media field (EFalse).
148 * @return a new instance.
150 IMPORT_C CSdpMediaField * CloneL(TBool aRecurse = ETrue) const;
153 * Compares this instance to another for equality. Subfields are
154 * included in the comparison if present.
156 * @param aObj The instance to compare to.
157 * @return ETrue if equal, EFalse if not.
159 IMPORT_C TBool operator == (const CSdpMediaField& aObj) const;
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
167 * @return ETrue if media description is consistent and EFalse if not.
169 IMPORT_C TBool IsValid() const;
172 * Gets the media type.
174 * @return The media type.
176 IMPORT_C RStringF Media() const;
179 * Sets the media type.
181 * @param aMedia The media type.
182 * @leave KErrSdpCodecMediaField if aMedia is not valid character
184 IMPORT_C void SetMediaL(RStringF aMedia);
187 * Gets the media protocol.
189 * @return The media protocol.
191 IMPORT_C RStringF Protocol() const;
194 * Sets the media protocol.
196 * @param aProtocol The media protocol.
197 * @leave KErrSdpCodecMediaField if
198 * aProtocol containing two elements divided by slash are not
201 IMPORT_C void SetProtocolL(RStringF aProtocol);
204 * Gets the port number.
206 * @return The port number.
208 IMPORT_C TUint Port() const;
211 * Sets the port number.
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
217 IMPORT_C void SetPortL(TUint aPort);
220 * Gets the port count.
222 * @return The port count.
224 IMPORT_C TUint PortCount() const;
227 * Sets the port count.
229 * @param aCount The port count that must be greater than zero.
230 * @leave KErrSdpCodecMediaField if aCount equals to zero.
232 IMPORT_C void SetPortCountL(TUint aCount);
235 * Gets the format list.
237 * @return The format list.
239 IMPORT_C const TDesC8& FormatList() const;
242 * Sets the format list.
243 * The format list should contain one or more format tokens separated
244 * by a single whitespace character.
246 * @param aValue A valid format list.
247 * @leave KErrSdpCodecMediaField if aValue contains invalid tokens
249 IMPORT_C void SetFormatListL(const TDesC8& aValue);
252 * Return the media level info field value.
254 * @return The value or an empty descriptor if not present.
256 IMPORT_C const TDesC8& Info() const;
259 * Sets the media level info field value.
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´).
265 IMPORT_C void SetInfoL(const TDesC8& aValue);
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.
272 * @return Encryption key field or null if not present.
274 IMPORT_C CSdpKeyField* Key();
277 * Gets the media level encryption key field.
279 * @return Encryption key field or null if not present.
281 IMPORT_C const CSdpKeyField* Key() const;
284 * Sets or removes the media level encryption key field.
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.
290 IMPORT_C void SetKey(CSdpKeyField* aObj);
293 * Gets the set of media format level attributes.
294 * This array is used directly for element insertion and removal.
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.
302 * @return The set of media format level attributes.
304 IMPORT_C RPointerArray<CSdpFmtAttributeField>& FormatAttributeFields();
307 * Gets the set of media level, format independent attributes.
308 * This array is used directly for element insertion and removal.
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.
316 * @return The set of media level attributes.
318 IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();
321 * Gets the set of media level bandwidth fields.
322 * This array is used directly for element insertion and removal.
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.
330 * @return The set of media level bandwidth fields.
332 IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();
335 * Gets the set of media level connection fields.
336 * This array is used directly for element insertion and removal.
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.
344 * @return The set of media level connection fields.
346 IMPORT_C RPointerArray<CSdpConnectionField>& ConnectionFields();
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.
354 * @param aFormat The name of the format to remove.
356 IMPORT_C void RemoveFormatL(const TDesC8& aFormat);
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.
367 * @param aFormat The name of the format to keep after
368 * removing all others.
370 IMPORT_C void KeepFormatL(const TDesC8& aFormat);
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.
379 IMPORT_C void RejectMedia();
383 * Shows if contact is present
385 * @return ETrue if contact present, otherwise EFalse
387 TBool IsContactPresent() const;
390 * Externalizes the object to stream
392 * @param aStream Stream where the object's state will be stored
394 void ExternalizeL(RWriteStream& aStream) const;
397 * Creates object from the stream data
399 * @param aStream Stream where the object's state will be read
400 * @return Initialized object
402 static CSdpMediaField* InternalizeL(RReadStream& aStream);
407 void ConstructL(TBool aRecurse);
408 void ConstructL(RStringF aMedia, TUint aPort, RStringF aProtocol,
409 const TDesC8& aFormatList);
411 void ConstructL(const CSdpMediaField& aSdpMediaField);
412 void DoInternalizeL(RReadStream& aStream);
413 void ParseL (const TDesC8& aText);
415 void ParseInformationL();
416 void ParseConnectionL();
417 void ParseBandwithL();
418 void ParseEncryptionKeyL();
419 void ParseAttributeFieldsL();
420 TDesC8& GetTokenFromStreamL(RReadStream& aStream);
423 CSdpMediaField(const CSdpMediaField&); // Hidden.
424 CSdpMediaField& operator = (const CSdpMediaField&); // Hidden
428 CSdpKeyField* iSdpKeyField;
429 RArray<TPtrC8> iElementArray;
437 RPointerArray<CSdpBandwidthField>* iBandwidthFields;
438 RPointerArray<CSdpAttributeField>* iAttributeFields;
439 RPointerArray<CSdpConnectionField>* iConnectionFields;
440 RPointerArray<CSdpFmtAttributeField>* iFmtAttrFields;
442 CSdpCodecParseUtil* iSdpCodecParseUtil;
445 #endif // CSDPMEDIAFIELD_H