diff -r 000000000000 -r 307788aac0a8 realtimenetprots/sipfw/SDP/api/SdpDocument.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/realtimenetprots/sipfw/SDP/api/SdpDocument.h Tue Feb 02 01:03:15 2010 +0200 @@ -0,0 +1,445 @@ +/* +* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* Name : SdpDocument.h +* Part of : SDP Codec +* Interface : SDK API, SDP Codec API +* Version : 1.0 +* +*/ + + + +#ifndef CSDPDOCUMENT_H +#define CSDPDOCUMENT_H + +// INCLUDES +#include +#include +#include + +// FORWARD DECLARATIONS +class SdpUtil; +class RReadStream; +class RWriteStream; +class CUri8; +class CDesC8Array; +class CSdpOriginField; +class CSdpEmailField; +class CSdpPhoneField; +class CSdpConnectionField; +class CSdpBandwidthField; +class CSdpTimeField; +class CSdpAttributeField; +class CSdpMediaField; +class CSdpKeyField; +class CSdpCodecParseUtil; + +// CLASS DECLARATION +/** + * @publishedAll + * @released + * + * This class encapsulates the Session Description Protocol (SDP) document. + * The SDP document is a collection of SDP fields and related values + * describing a session. + * + * The normative reference for correct formatting and values is + * draft-ietf-mmusic-sdp-new-14 unless specified otherwise in + * member documentation. The implementation supports this normative + * reference, but does not enforce it fully. + * + * @lib sdpcodec.lib + */ +class CSdpDocument : public CBase + { + public: // Constructors and destructor + /** + * Constructs a new SDP document. + * + * @param aText A string containing a correctly formatted SDP document. + * @return a new instance. + */ + IMPORT_C static CSdpDocument* DecodeL(const TDesC8& aText); + + /** + * Constructs a new SDP document and adds the pointer to the cleanup stack. + * + * @param aText A string containing a correctly formatted SDP document. + * @return a new instance. + */ + IMPORT_C static CSdpDocument* DecodeLC(const TDesC8& aText); + + /** + * Constructs a new, empty SDP document. + * The instance will have the following initial values: + * v=0 + * s=- + * t=0 0 + * + * @return a new instance. + */ + IMPORT_C static CSdpDocument* NewL(); + + /** + * Constructs a new, empty SDP document document and adds the pointer to + * the cleanup stack. + * The instance will have the following initial values: + * v=0 + * s=- + * t=0 0 + * + * @return a new instance. + */ + IMPORT_C static CSdpDocument* NewLC(); + + /** + * Deletes the resources held by the instance. + */ + IMPORT_C ~CSdpDocument(); + + public: + /** + * Externalizes the object state in an internal, memory optimized format. + * + * @param aStream The output stream. + */ + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + + /** + * Internalizes the object state from an internal, memory optimized format. + * + * @param aStream The input stream. + * @return A new SDP document internalized from the input stream. + */ + IMPORT_C static CSdpDocument* InternalizeL(RReadStream& aStream); + + /** + * Outputs the SDP document formatted according to SDP syntax. + * It is possible to output the document even though it is + * incomplete in the sense that all mandatory SDP fields are + * not present.When creating an SDP document to be used e.g. + * as part of SIP signalling, caller should first ensure the + * validity of the document using the IsValid() function. + * + * @param aStream Stream used for output. On return the + * stream includes correctly formatted SDP description. + */ + IMPORT_C void EncodeL(RWriteStream& aStream) const; + + /** + * Creates a new instance that is equal to the target. + * + * @return a new instance. + */ + IMPORT_C CSdpDocument* CloneL() const; + + /** + * Checks if the instance represents a valid SDP document. + * + * @return ETrue if SDP document is valid and EFalse if not. + */ + IMPORT_C TBool IsValid() const; + + /** + * Gets the SDP version used in the version field. + * Note, that the current implementation supports only version number 0. + * + * @return The SDP version number. + */ + IMPORT_C TUint SdpVersion() const; + + /** + * Gets a reference to the session origin field. + * Note, that the ownership is not transferred and + * the instance must not be deleted by the caller. + * + * @return The origin field or zero if not present. + */ + IMPORT_C CSdpOriginField* OriginField(); + + /** + * Gets a reference to the session origin field. + * + * @return The origin field or zero if not present. + */ + IMPORT_C const CSdpOriginField* OriginField() const; + + /** + * Sets or removes the session origin field. + * Note, that the ownership of the argument is + * transferred to the SDP document object. + * + * @param aObj New origin field or null to remove the field. + */ + IMPORT_C void SetOriginField(CSdpOriginField* aObj); + + /** + * Gets the session name field value. + * + * @return The session name or empty descriptor if not present. + */ + IMPORT_C const TDesC8& SessionName() const; + + /** + * Sets the session name field value. + * + * @param aValue Valid session name value. + * Note that an empty value is not accepted. + * @leave KErrSdpCodecSessionField if + * aValue is not empty or aValue includes invalid byte strings + * (´\0´, ´\n´, ´\r´). + */ + IMPORT_C void SetSessionNameL(const TDesC8& aValue); + + /** + * Gets the session information field value. + * + * @return Info field value or an empty descriptor if not present. + */ + IMPORT_C const TDesC8& Info() const; + + /** + * Sets or removes the session information field value. + * + * @param New field value or an empty descriptor to remove the field. + * @leave KErrSdpCodecInfoField if aValue is not empty or aValue includes + * invalid byte strings (´\0´, ´\n´, ´\r´). + */ + IMPORT_C void SetInfoL(const TDesC8& aValue); + + /** + * Gets the session URI field value. + * Note, that the ownership is not transferred and + * the instance must not be deleted by the caller. + * + * @return CUri8*: Session URI or zero if the field is not present. + */ + IMPORT_C CUri8* Uri(); + + /** + * Gets the session URI field value. + * + * @return Session URI or zero if the field is not present. + */ + IMPORT_C const CUri8* Uri() const; + + /** + * Sets or removes the session level URI field. + * Note, that the ownership of the argument is + * transferred to the SDP document object. + * + * @param New value of the field or zero to remove the field. + */ + IMPORT_C void SetUri(CUri8* aValue); + + /** + * Gets the set of session level email field values. This array is used to + * add and remove fields into the document. + * Note, that only correctly formatted email field values should be placed + * into the array. Empty values in the array will be ignored. + * + * @return Email fields in array or empty array if no email fields. + */ + IMPORT_C CDesC8Array& EmailFields(); + + /** + * Gets the set of session level phone field values. This array is used to + * add and remove fields into the document. + * Note, that only correctly formatted phone field values should be placed + * into the array. Empty values in the array will be ignored. + * + * @return Phone fields in array or empty array if no phone fields. + */ + IMPORT_C CDesC8Array& PhoneFields(); + + /** + * Gets the session level connection field. + * Note, that the ownership is not transferred and the instance must not be + * deleted by the caller. + * + * @return Connection field or zero if not present. + */ + IMPORT_C CSdpConnectionField* ConnectionField(); + + /** + * Gets the session level connection field. + * + * @return Connection field or zero if not present. + */ + IMPORT_C const CSdpConnectionField* ConnectionField() const; + + /** + * Sets or removes the session level connection field. + * Note, that the ownership of the argument is + * transferred to the SDP document object. + * + * @param New connection field or zero to remove the field. + */ + IMPORT_C void SetConnectionField(CSdpConnectionField* aObj); + + /** + * Gets the possibly empty set of session level bandwidth fields. + * This array is used directly for element insertion and removal. + * The array may contain zero references and these are ignored. + * + * The objects referenced from the array are owned by the document + * instance and must not be deleted. An object can be removed from + * the document by setting the corresponding element to zero. By + * doing so, the calling party receives ownership of the removed object. + * + * @return Set of bandwidth fields. + */ + IMPORT_C RPointerArray& BandwidthFields(); + + /** + * Gets the set of session level time description fields. + * This array is used directly for element insertion and removal. + * There must be at least one time description field in a valid SDP + * document.The array may contain zero references and these are ignored. + * + * The objects referenced from the array are owned by the document + * instance and must not be deleted. An object can be removed from the + * document by setting the corresponding element to zero. By doing so, + * the calling party receives ownership of the removed object. + * + * @return Set of time fields. + */ + IMPORT_C RPointerArray& TimeFields(); + + /** + * Gets the zone adjustments field value. + * + * @return The field value or an empty descriptor if the + * field is not present. + */ + IMPORT_C const TDesC8& ZoneAdjustments() const; + + /** + * Sets the zone adjustments field value. + * + * @param aValue A valid field value or an empty descriptor + * if field is not present. + */ + IMPORT_C void SetZoneAdjustmentsL(const TDesC8& aValue); + + /** + * Gets the session level encryption key field. + * Note, that the ownership is not transferred and + * the instance must not be deleted by the caller. + * + * @return The encryption key or zero if not present. + */ + IMPORT_C CSdpKeyField* Key(); + + /** + * Gets the session level encryption key field. + * + * @return The encryption key or zero if not present. + */ + IMPORT_C const CSdpKeyField* Key() const; + + /** + * Sets or removes the encryption key field. + * Note, that the ownership of the argument is + * transferred to the SDP document object. + * + * @param aObj New value of the field or zero to remove the field. + */ + IMPORT_C void SetKey(CSdpKeyField* aObj); + + /** + * Gets the possibly empty set of session level attribute fields. + * This array is used directly for element insertion and removal. + * The array may contain zero references and these are ignored. + * + * The objects referenced from the array are owned by the document + * instance and must not be deleted. An object can be removed from the + * document by setting the corresponding element to zero. By doing so, + * the calling party receives ownership of the removed object. + * + * @return Set of session level attributes. + */ + IMPORT_C RPointerArray& AttributeFields(); + + /** + * Gets the possibly empty set of media description fields. + * This array is used directly for element insertion and removal. + * Note, that media level attributes and fields are managed + * through the corresponding media field instance and not through + * the document instance. + * The array may contain zero references and these are ignored. + * + * The objects referenced from the array are owned by the document + * instance and must not be deleted. An object can be removed from the + * document by setting the corresponding element to zero. By doing so, + * the calling party receives ownership of the removed object. + * + * @return Set of media description fields. + */ + IMPORT_C RPointerArray& MediaFields(); + + private: + CSdpDocument(); + void ConstructL(); + void ConstructL(const CSdpDocument& aSdpDocument); + void DoInternalizeL(RReadStream& aStream); + + void ParseL (const TDesC8& aText); + void ParseSessionVersionL(); + void ParseSessionOwnerL(); + void ParseSessionNameL(); + void ParseSessionInformationL(); + void ParseUriL(); + void ParseEmailL(); + void ParsePhoneL(); + void ParseConnectionL(); + void ParseBandwidthL(); + void ParseTimeFieldL(); + void ParseZoneAdjustmentL(); + void ParseEncryptionKeyL(); + void ParseAttributeFieldL(); + void ParseMediaLevelL (); + void ExternalizeDesCArrayL(CDesC8ArraySeg& aArray, + RWriteStream& aStream) const; + void EncodeDesCArrayL(CDesC8ArraySeg& aArray,TInt aIndex, + RWriteStream& aStream) const; + + TDesC8& GetTokenFromStreamL(RReadStream& aStream); + + CSdpDocument(const CSdpDocument&); // Hidden. + CSdpDocument& operator = (const CSdpDocument&); // Hidden + + private: // Data + + HBufC8* iInfo; + HBufC8* iSessionName; + HBufC8* iZoneAdjustments; + CSdpKeyField* iSdpKeyField; + CSdpOriginField* iSdpOriginField; + CSdpConnectionField* iSdpConnectionField; + TUint iSdpVersion; + RPointerArray* iTimeFields; + RPointerArray* iBandwidthFields; + RPointerArray* iAttributeFields; + RPointerArray* iMediaFields; + CUri8* iUri; + CDesC8ArraySeg* iEmailFields; + CDesC8ArraySeg* iPhoneFields; + RStringPool iPool; + HBufC8* iToken; + CSdpCodecParseUtil* iSdpCodecParseUtil; + }; + +#endif // CSDPDOCUMENT_H