1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/sdpdocument.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,446 @@
1.4 +/*
1.5 +* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* 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
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +* Name : SdpDocument.h
1.19 +* Part of : SDP Codec
1.20 +* Interface : SDK API, SDP Codec API
1.21 +* Version : 1.0
1.22 +*
1.23 +*/
1.24 +
1.25 +
1.26 +
1.27 +#ifndef CSDPDOCUMENT_H
1.28 +#define CSDPDOCUMENT_H
1.29 +
1.30 +// INCLUDES
1.31 +#include <e32base.h>
1.32 +#include <badesca.h>
1.33 +#include "_sdpdefs.h"
1.34 +#include <stringpool.h>
1.35 +
1.36 +// FORWARD DECLARATIONS
1.37 +class SdpUtil;
1.38 +class RReadStream;
1.39 +class RWriteStream;
1.40 +class CUri8;
1.41 +class CDesC8Array;
1.42 +class CSdpOriginField;
1.43 +class CSdpEmailField;
1.44 +class CSdpPhoneField;
1.45 +class CSdpConnectionField;
1.46 +class CSdpBandwidthField;
1.47 +class CSdpTimeField;
1.48 +class CSdpAttributeField;
1.49 +class CSdpMediaField;
1.50 +class CSdpKeyField;
1.51 +class CSdpCodecParseUtil;
1.52 +
1.53 +// CLASS DECLARATION
1.54 +/**
1.55 + * @publishedAll
1.56 + * @released
1.57 + *
1.58 + * This class encapsulates the Session Description Protocol (SDP) document.
1.59 + * The SDP document is a collection of SDP fields and related values
1.60 + * describing a session.
1.61 + *
1.62 + * The normative reference for correct formatting and values is
1.63 + * draft-ietf-mmusic-sdp-new-14 unless specified otherwise in
1.64 + * member documentation. The implementation supports this normative
1.65 + * reference, but does not enforce it fully.
1.66 + *
1.67 + * @lib sdpcodec.lib
1.68 + */
1.69 +class CSdpDocument : public CBase
1.70 + {
1.71 + public: // Constructors and destructor
1.72 + /**
1.73 + * Constructs a new SDP document.
1.74 + *
1.75 + * @param aText A string containing a correctly formatted SDP document.
1.76 + * @return a new instance.
1.77 + */
1.78 + IMPORT_C static CSdpDocument* DecodeL(const TDesC8& aText);
1.79 +
1.80 + /**
1.81 + * Constructs a new SDP document and adds the pointer to the cleanup stack.
1.82 + *
1.83 + * @param aText A string containing a correctly formatted SDP document.
1.84 + * @return a new instance.
1.85 + */
1.86 + IMPORT_C static CSdpDocument* DecodeLC(const TDesC8& aText);
1.87 +
1.88 + /**
1.89 + * Constructs a new, empty SDP document.
1.90 + * The instance will have the following initial values:
1.91 + * v=0
1.92 + * s=-
1.93 + * t=0 0
1.94 + *
1.95 + * @return a new instance.
1.96 + */
1.97 + IMPORT_C static CSdpDocument* NewL();
1.98 +
1.99 + /**
1.100 + * Constructs a new, empty SDP document document and adds the pointer to
1.101 + * the cleanup stack.
1.102 + * The instance will have the following initial values:
1.103 + * v=0
1.104 + * s=-
1.105 + * t=0 0
1.106 + *
1.107 + * @return a new instance.
1.108 + */
1.109 + IMPORT_C static CSdpDocument* NewLC();
1.110 +
1.111 + /**
1.112 + * Deletes the resources held by the instance.
1.113 + */
1.114 + IMPORT_C ~CSdpDocument();
1.115 +
1.116 + public:
1.117 + /**
1.118 + * Externalizes the object state in an internal, memory optimized format.
1.119 + *
1.120 + * @param aStream The output stream.
1.121 + */
1.122 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.123 +
1.124 + /**
1.125 + * Internalizes the object state from an internal, memory optimized format.
1.126 + *
1.127 + * @param aStream The input stream.
1.128 + * @return A new SDP document internalized from the input stream.
1.129 + */
1.130 + IMPORT_C static CSdpDocument* InternalizeL(RReadStream& aStream);
1.131 +
1.132 + /**
1.133 + * Outputs the SDP document formatted according to SDP syntax.
1.134 + * It is possible to output the document even though it is
1.135 + * incomplete in the sense that all mandatory SDP fields are
1.136 + * not present.When creating an SDP document to be used e.g.
1.137 + * as part of SIP signalling, caller should first ensure the
1.138 + * validity of the document using the IsValid() function.
1.139 + *
1.140 + * @param aStream Stream used for output. On return the
1.141 + * stream includes correctly formatted SDP description.
1.142 + */
1.143 + IMPORT_C void EncodeL(RWriteStream& aStream) const;
1.144 +
1.145 + /**
1.146 + * Creates a new instance that is equal to the target.
1.147 + *
1.148 + * @return a new instance.
1.149 + */
1.150 + IMPORT_C CSdpDocument* CloneL() const;
1.151 +
1.152 + /**
1.153 + * Checks if the instance represents a valid SDP document.
1.154 + *
1.155 + * @return ETrue if SDP document is valid and EFalse if not.
1.156 + */
1.157 + IMPORT_C TBool IsValid() const;
1.158 +
1.159 + /**
1.160 + * Gets the SDP version used in the version field.
1.161 + * Note, that the current implementation supports only version number 0.
1.162 + *
1.163 + * @return The SDP version number.
1.164 + */
1.165 + IMPORT_C TUint SdpVersion() const;
1.166 +
1.167 + /**
1.168 + * Gets a reference to the session origin field.
1.169 + * Note, that the ownership is not transferred and
1.170 + * the instance must not be deleted by the caller.
1.171 + *
1.172 + * @return The origin field or zero if not present.
1.173 + */
1.174 + IMPORT_C CSdpOriginField* OriginField();
1.175 +
1.176 + /**
1.177 + * Gets a reference to the session origin field.
1.178 + *
1.179 + * @return The origin field or zero if not present.
1.180 + */
1.181 + IMPORT_C const CSdpOriginField* OriginField() const;
1.182 +
1.183 + /**
1.184 + * Sets or removes the session origin field.
1.185 + * Note, that the ownership of the argument is
1.186 + * transferred to the SDP document object.
1.187 + *
1.188 + * @param aObj New origin field or null to remove the field.
1.189 + */
1.190 + IMPORT_C void SetOriginField(CSdpOriginField* aObj);
1.191 +
1.192 + /**
1.193 + * Gets the session name field value.
1.194 + *
1.195 + * @return The session name or empty descriptor if not present.
1.196 + */
1.197 + IMPORT_C const TDesC8& SessionName() const;
1.198 +
1.199 + /**
1.200 + * Sets the session name field value.
1.201 + *
1.202 + * @param aValue Valid session name value.
1.203 + * Note that an empty value is not accepted.
1.204 + * @leave KErrSdpCodecSessionField if
1.205 + * aValue is not empty or aValue includes invalid byte strings
1.206 + * (´\0´, ´\n´, ´\r´).
1.207 + */
1.208 + IMPORT_C void SetSessionNameL(const TDesC8& aValue);
1.209 +
1.210 + /**
1.211 + * Gets the session information field value.
1.212 + *
1.213 + * @return Info field value or an empty descriptor if not present.
1.214 + */
1.215 + IMPORT_C const TDesC8& Info() const;
1.216 +
1.217 + /**
1.218 + * Sets or removes the session information field value.
1.219 + *
1.220 + * @param New field value or an empty descriptor to remove the field.
1.221 + * @leave KErrSdpCodecInfoField if aValue is not empty or aValue includes
1.222 + * invalid byte strings (´\0´, ´\n´, ´\r´).
1.223 + */
1.224 + IMPORT_C void SetInfoL(const TDesC8& aValue);
1.225 +
1.226 + /**
1.227 + * Gets the session URI field value.
1.228 + * Note, that the ownership is not transferred and
1.229 + * the instance must not be deleted by the caller.
1.230 + *
1.231 + * @return CUri8*: Session URI or zero if the field is not present.
1.232 + */
1.233 + IMPORT_C CUri8* Uri();
1.234 +
1.235 + /**
1.236 + * Gets the session URI field value.
1.237 + *
1.238 + * @return Session URI or zero if the field is not present.
1.239 + */
1.240 + IMPORT_C const CUri8* Uri() const;
1.241 +
1.242 + /**
1.243 + * Sets or removes the session level URI field.
1.244 + * Note, that the ownership of the argument is
1.245 + * transferred to the SDP document object.
1.246 + *
1.247 + * @param New value of the field or zero to remove the field.
1.248 + */
1.249 + IMPORT_C void SetUri(CUri8* aValue);
1.250 +
1.251 + /**
1.252 + * Gets the set of session level email field values. This array is used to
1.253 + * add and remove fields into the document.
1.254 + * Note, that only correctly formatted email field values should be placed
1.255 + * into the array. Empty values in the array will be ignored.
1.256 + *
1.257 + * @return Email fields in array or empty array if no email fields.
1.258 + */
1.259 + IMPORT_C CDesC8Array& EmailFields();
1.260 +
1.261 + /**
1.262 + * Gets the set of session level phone field values. This array is used to
1.263 + * add and remove fields into the document.
1.264 + * Note, that only correctly formatted phone field values should be placed
1.265 + * into the array. Empty values in the array will be ignored.
1.266 + *
1.267 + * @return Phone fields in array or empty array if no phone fields.
1.268 + */
1.269 + IMPORT_C CDesC8Array& PhoneFields();
1.270 +
1.271 + /**
1.272 + * Gets the session level connection field.
1.273 + * Note, that the ownership is not transferred and the instance must not be
1.274 + * deleted by the caller.
1.275 + *
1.276 + * @return Connection field or zero if not present.
1.277 + */
1.278 + IMPORT_C CSdpConnectionField* ConnectionField();
1.279 +
1.280 + /**
1.281 + * Gets the session level connection field.
1.282 + *
1.283 + * @return Connection field or zero if not present.
1.284 + */
1.285 + IMPORT_C const CSdpConnectionField* ConnectionField() const;
1.286 +
1.287 + /**
1.288 + * Sets or removes the session level connection field.
1.289 + * Note, that the ownership of the argument is
1.290 + * transferred to the SDP document object.
1.291 + *
1.292 + * @param New connection field or zero to remove the field.
1.293 + */
1.294 + IMPORT_C void SetConnectionField(CSdpConnectionField* aObj);
1.295 +
1.296 + /**
1.297 + * Gets the possibly empty set of session level bandwidth fields.
1.298 + * This array is used directly for element insertion and removal.
1.299 + * The array may contain zero references and these are ignored.
1.300 + *
1.301 + * The objects referenced from the array are owned by the document
1.302 + * instance and must not be deleted. An object can be removed from
1.303 + * the document by setting the corresponding element to zero. By
1.304 + * doing so, the calling party receives ownership of the removed object.
1.305 + *
1.306 + * @return Set of bandwidth fields.
1.307 + */
1.308 + IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();
1.309 +
1.310 + /**
1.311 + * Gets the set of session level time description fields.
1.312 + * This array is used directly for element insertion and removal.
1.313 + * There must be at least one time description field in a valid SDP
1.314 + * document.The array may contain zero references and these are ignored.
1.315 + *
1.316 + * The objects referenced from the array are owned by the document
1.317 + * instance and must not be deleted. An object can be removed from the
1.318 + * document by setting the corresponding element to zero. By doing so,
1.319 + * the calling party receives ownership of the removed object.
1.320 + *
1.321 + * @return Set of time fields.
1.322 + */
1.323 + IMPORT_C RPointerArray<CSdpTimeField>& TimeFields();
1.324 +
1.325 + /**
1.326 + * Gets the zone adjustments field value.
1.327 + *
1.328 + * @return The field value or an empty descriptor if the
1.329 + * field is not present.
1.330 + */
1.331 + IMPORT_C const TDesC8& ZoneAdjustments() const;
1.332 +
1.333 + /**
1.334 + * Sets the zone adjustments field value.
1.335 + *
1.336 + * @param aValue A valid field value or an empty descriptor
1.337 + * if field is not present.
1.338 + */
1.339 + IMPORT_C void SetZoneAdjustmentsL(const TDesC8& aValue);
1.340 +
1.341 + /**
1.342 + * Gets the session level encryption key field.
1.343 + * Note, that the ownership is not transferred and
1.344 + * the instance must not be deleted by the caller.
1.345 + *
1.346 + * @return The encryption key or zero if not present.
1.347 + */
1.348 + IMPORT_C CSdpKeyField* Key();
1.349 +
1.350 + /**
1.351 + * Gets the session level encryption key field.
1.352 + *
1.353 + * @return The encryption key or zero if not present.
1.354 + */
1.355 + IMPORT_C const CSdpKeyField* Key() const;
1.356 +
1.357 + /**
1.358 + * Sets or removes the encryption key field.
1.359 + * Note, that the ownership of the argument is
1.360 + * transferred to the SDP document object.
1.361 + *
1.362 + * @param aObj New value of the field or zero to remove the field.
1.363 + */
1.364 + IMPORT_C void SetKey(CSdpKeyField* aObj);
1.365 +
1.366 + /**
1.367 + * Gets the possibly empty set of session level attribute fields.
1.368 + * This array is used directly for element insertion and removal.
1.369 + * The array may contain zero references and these are ignored.
1.370 + *
1.371 + * The objects referenced from the array are owned by the document
1.372 + * instance and must not be deleted. An object can be removed from the
1.373 + * document by setting the corresponding element to zero. By doing so,
1.374 + * the calling party receives ownership of the removed object.
1.375 + *
1.376 + * @return Set of session level attributes.
1.377 + */
1.378 + IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();
1.379 +
1.380 + /**
1.381 + * Gets the possibly empty set of media description fields.
1.382 + * This array is used directly for element insertion and removal.
1.383 + * Note, that media level attributes and fields are managed
1.384 + * through the corresponding media field instance and not through
1.385 + * the document instance.
1.386 + * The array may contain zero references and these are ignored.
1.387 + *
1.388 + * The objects referenced from the array are owned by the document
1.389 + * instance and must not be deleted. An object can be removed from the
1.390 + * document by setting the corresponding element to zero. By doing so,
1.391 + * the calling party receives ownership of the removed object.
1.392 + *
1.393 + * @return Set of media description fields.
1.394 + */
1.395 + IMPORT_C RPointerArray<CSdpMediaField>& MediaFields();
1.396 +
1.397 + private:
1.398 + CSdpDocument();
1.399 + void ConstructL();
1.400 + void ConstructL(const CSdpDocument& aSdpDocument);
1.401 + void DoInternalizeL(RReadStream& aStream);
1.402 +
1.403 + void ParseL (const TDesC8& aText);
1.404 + void ParseSessionVersionL();
1.405 + void ParseSessionOwnerL();
1.406 + void ParseSessionNameL();
1.407 + void ParseSessionInformationL();
1.408 + void ParseUriL();
1.409 + void ParseEmailL();
1.410 + void ParsePhoneL();
1.411 + void ParseConnectionL();
1.412 + void ParseBandwidthL();
1.413 + void ParseTimeFieldL();
1.414 + void ParseZoneAdjustmentL();
1.415 + void ParseEncryptionKeyL();
1.416 + void ParseAttributeFieldL();
1.417 + void ParseMediaLevelL ();
1.418 + void ExternalizeDesCArrayL(CDesC8ArraySeg& aArray,
1.419 + RWriteStream& aStream) const;
1.420 + void EncodeDesCArrayL(CDesC8ArraySeg& aArray,TInt aIndex,
1.421 + RWriteStream& aStream) const;
1.422 +
1.423 + TDesC8& GetTokenFromStreamL(RReadStream& aStream);
1.424 +
1.425 + CSdpDocument(const CSdpDocument&); // Hidden.
1.426 + CSdpDocument& operator = (const CSdpDocument&); // Hidden
1.427 +
1.428 + private: // Data
1.429 +
1.430 + HBufC8* iInfo;
1.431 + HBufC8* iSessionName;
1.432 + HBufC8* iZoneAdjustments;
1.433 + CSdpKeyField* iSdpKeyField;
1.434 + CSdpOriginField* iSdpOriginField;
1.435 + CSdpConnectionField* iSdpConnectionField;
1.436 + TUint iSdpVersion;
1.437 + RPointerArray<CSdpTimeField>* iTimeFields;
1.438 + RPointerArray<CSdpBandwidthField>* iBandwidthFields;
1.439 + RPointerArray<CSdpAttributeField>* iAttributeFields;
1.440 + RPointerArray<CSdpMediaField>* iMediaFields;
1.441 + CUri8* iUri;
1.442 + CDesC8ArraySeg* iEmailFields;
1.443 + CDesC8ArraySeg* iPhoneFields;
1.444 + RStringPool iPool;
1.445 + HBufC8* iToken;
1.446 + CSdpCodecParseUtil* iSdpCodecParseUtil;
1.447 + };
1.448 +
1.449 +#endif // CSDPDOCUMENT_H