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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name          : SdpDocument.h

    16 * Part of       : SDP Codec

    17 * Interface     : SDK API, SDP Codec API

    18 * Version       : 1.0

    19 *

    20 */

    21 

    22 

    23 

    24 #ifndef CSDPDOCUMENT_H

    25 #define CSDPDOCUMENT_H

    26 

    27 //  INCLUDES

    28 #include <e32base.h>

    29 #include <badesca.h>

    30 #include <stringpool.h>

    31 

    32 // FORWARD DECLARATIONS

    33 class SdpUtil;

    34 class RReadStream;

    35 class RWriteStream;

    36 class CUri8;

    37 class CDesC8Array;

    38 class CSdpOriginField;

    39 class CSdpEmailField;

    40 class CSdpPhoneField;

    41 class CSdpConnectionField;

    42 class CSdpBandwidthField;

    43 class CSdpTimeField;

    44 class CSdpAttributeField;

    45 class CSdpMediaField;

    46 class CSdpKeyField;

    47 class CSdpCodecParseUtil;

    48 

    49 // CLASS DECLARATION

    50 /**

    51  *  @publishedAll

    52  *  @released

    53  *

    54  *    This class encapsulates the Session Description Protocol (SDP) document.

    55  *  The SDP document is a collection of SDP fields and related values

    56  *    describing a session.

    57  *

    58  *    The normative reference for correct formatting and values is

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

    60  *  member documentation. The implementation supports this normative

    61  *  reference, but does not enforce it fully. 

    62  *

    63  *  @lib sdpcodec.lib

    64  */

    65 class CSdpDocument : public CBase

    66     {

    67     public: // Constructors and destructor

    68         /**

    69         * Constructs a new SDP document.

    70         *    

    71         * @param aText A string containing a correctly formatted SDP document.

    72         * @return a new instance.

    73         */

    74         IMPORT_C static CSdpDocument* DecodeL(const TDesC8& aText);

    75 

    76         /**

    77         * Constructs a new SDP document and adds the pointer to the cleanup stack.

    78         *    

    79         * @param aText A string containing a correctly formatted SDP document.

    80         * @return a new instance.

    81         */

    82         IMPORT_C static CSdpDocument* DecodeLC(const TDesC8& aText);

    83             

    84         /**

    85         * Constructs a new, empty SDP document.

    86         * The instance will have the following initial values:

    87         *      v=0

    88         *      s=-

    89         *      t=0 0

    90         *

    91         * @return a new instance.

    92         */

    93         IMPORT_C static CSdpDocument* NewL();

    94 

    95         /**

    96         * Constructs a new, empty SDP document document and adds the pointer to 

    97         * the cleanup stack.

    98         * The instance will have the following initial values:

    99         *      v=0

   100         *      s=-

   101         *      t=0 0

   102         *

   103         * @return a new instance.

   104         */

   105         IMPORT_C static CSdpDocument* NewLC();

   106 

   107         /**

   108         * Deletes the resources held by the instance.

   109         */

   110         IMPORT_C ~CSdpDocument();

   111 

   112     public: 

   113         /**

   114         * Externalizes the object state in an internal, memory optimized format.

   115         *

   116         * @param aStream The output stream.

   117         */

   118         IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   119 

   120         /**

   121         * Internalizes the object state from an internal, memory optimized format.

   122         *

   123         * @param aStream The input stream.

   124         * @return A new SDP document internalized from the input stream.

   125         */

   126         IMPORT_C static CSdpDocument* InternalizeL(RReadStream& aStream);

   127 

   128         /**

   129         * Outputs the SDP document formatted according to SDP syntax.

   130         * It is possible to output the document even though it is

   131         * incomplete in the sense that all mandatory SDP fields are

   132         * not present.When creating an SDP document to be used e.g.

   133         * as part of SIP signalling, caller should first ensure the

   134         * validity of the document using the IsValid() function.

   135         * 

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

   137         *        stream includes correctly formatted SDP description.

   138         */

   139         IMPORT_C void EncodeL(RWriteStream& aStream) const;

   140 

   141         /**

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

   143         *

   144         * @return a new instance.

   145         */

   146         IMPORT_C CSdpDocument* CloneL() const;

   147 

   148         /**

   149         * Checks if the instance represents a valid SDP document.

   150         *

   151         * @return ETrue if SDP document is valid and EFalse if not.

   152         */

   153         IMPORT_C TBool IsValid() const;

   154 

   155         /**

   156         * Gets the SDP version used in the version field.

   157         * Note, that the current implementation supports only version number 0.

   158         *

   159         * @return The SDP version number.

   160         */ 

   161         IMPORT_C TUint SdpVersion() const;

   162 

   163         /**

   164         * Gets a reference to the session origin field.

   165         * Note, that the ownership is not transferred and

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

   167         *

   168         * @return The origin field or zero if not present.

   169         */

   170         IMPORT_C CSdpOriginField* OriginField();

   171 

   172         /**

   173         * Gets a reference to the session origin field.

   174         *

   175         * @return The origin field or zero if not present.

   176         */

   177         IMPORT_C const CSdpOriginField* OriginField() const;

   178 

   179         /**

   180         * Sets or removes the session origin field.

   181         * Note, that the ownership of the argument is 

   182         * transferred to the SDP document object.

   183         *

   184         * @param aObj New origin field or null to remove the field.

   185         */

   186         IMPORT_C void SetOriginField(CSdpOriginField* aObj);

   187 

   188         /**

   189         * Gets the session name field value.

   190         *

   191         * @return The session name or empty descriptor if not present.

   192         */

   193         IMPORT_C const TDesC8& SessionName() const;

   194 

   195         /**

   196         * Sets the session name field value.

   197         *

   198         * @param aValue Valid session name value. 

   199         *        Note that an empty value is not accepted.

   200         * @leave KErrSdpCodecSessionField if

   201         *        aValue is not empty or aValue includes invalid byte strings 

   202         *        (´\0´, ´\n´, ´\r´).

   203         */

   204         IMPORT_C void SetSessionNameL(const TDesC8& aValue);

   205 

   206         /**

   207         * Gets the session information field value.

   208         *

   209         * @return Info field value or an empty descriptor if not present.

   210         */

   211         IMPORT_C const TDesC8& Info() const;

   212 

   213         /**

   214         * Sets or removes the session information field value.

   215         *

   216         * @param New field value or an empty descriptor to remove the field.

   217         * @leave KErrSdpCodecInfoField if aValue is not empty or aValue includes 

   218         *        invalid byte strings (´\0´, ´\n´, ´\r´).

   219         */

   220         IMPORT_C void SetInfoL(const TDesC8& aValue);

   221 

   222         /**

   223         *    Gets the session URI field value.

   224         *    Note, that the ownership is not transferred and

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

   226         *

   227         *    @return CUri8*: Session URI or zero if the field is not present.

   228         */

   229         IMPORT_C CUri8* Uri();

   230 

   231         /**

   232         * Gets the session URI field value.

   233         *

   234         * @return Session URI or zero if the field is not present.

   235         */

   236         IMPORT_C const CUri8* Uri() const;

   237 

   238         /**

   239         * Sets or removes the session level URI field.

   240         * Note, that the ownership of the argument is 

   241         * transferred to the SDP document object.

   242         *

   243         * @param New value of the field or zero to remove the field.

   244         */

   245         IMPORT_C void SetUri(CUri8* aValue);

   246 

   247         /**

   248         * Gets the set of session level email field values. This array is used to

   249         * add and remove fields into the document.

   250         * Note, that only correctly formatted email field values should be placed

   251         * into the array. Empty values in the array will be ignored.

   252         *

   253         * @return Email fields in array or empty array if no email fields.

   254         */

   255         IMPORT_C CDesC8Array& EmailFields();

   256 

   257         /**

   258         * Gets the set of session level phone field values. This array is used to

   259         * add and remove fields into the document.

   260         * Note, that only correctly formatted phone field values should be placed

   261         * into the array. Empty values in the array will be ignored.

   262         *  

   263         * @return Phone fields in array or empty array if no phone fields.

   264         */

   265         IMPORT_C CDesC8Array& PhoneFields();

   266 

   267         /**

   268         * Gets the session level connection field.

   269         * Note, that the ownership is not transferred and the instance must not be

   270         * deleted by the caller.

   271         *

   272         * @return Connection field or zero if not present.

   273         */

   274         IMPORT_C CSdpConnectionField* ConnectionField();

   275 

   276         /**

   277         * Gets the session level connection field.

   278         *

   279         * @return Connection field or zero if not present.

   280         */

   281         IMPORT_C const CSdpConnectionField* ConnectionField() const;

   282 

   283         /**

   284         * Sets or removes the session level connection field.

   285         * Note, that the ownership of the argument is 

   286         * transferred to the SDP document object.

   287         *

   288         * @param New connection field or zero to remove the field.

   289         */    

   290         IMPORT_C void SetConnectionField(CSdpConnectionField* aObj);

   291 

   292         /**

   293         * Gets the possibly empty set of session level bandwidth fields.

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

   295         * The array may contain zero references and these are ignored.

   296         *

   297         * The objects referenced from the array are owned by the document

   298         * instance and must not be deleted. An object can be removed from

   299         * the document by setting the corresponding element to zero. By

   300         * doing so, the calling party receives ownership of the removed object.

   301         *

   302         * @return Set of bandwidth fields.

   303         */

   304         IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();

   305 

   306         /**

   307         * Gets the set of session level time description fields.

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

   309         * There must be at least one time description field in a valid SDP

   310         * document.The array may contain zero references and these are ignored.

   311         *

   312         * The objects referenced from the array are owned by the document 

   313         * instance and must not be deleted. An object can be removed from the

   314         * document by setting the corresponding element to zero. By doing so,

   315         * the calling party receives ownership of the removed object.  

   316         *

   317         * @return Set of time fields.

   318         */

   319         IMPORT_C RPointerArray<CSdpTimeField>& TimeFields();

   320 

   321         /** 

   322         * Gets the zone adjustments field value.

   323         *

   324         * @return The field value or an empty descriptor if the

   325         *         field is not present.

   326         */

   327         IMPORT_C const TDesC8& ZoneAdjustments() const;

   328 

   329         /** 

   330         * Sets the zone adjustments field value.

   331         *

   332         * @param aValue A valid field value or an empty descriptor

   333         *        if field is not present.

   334         */

   335         IMPORT_C void SetZoneAdjustmentsL(const TDesC8& aValue);

   336 

   337         /**

   338         * Gets the session level encryption key field.

   339         * Note, that the ownership is not transferred and

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

   341         *

   342         * @return The encryption key or zero if not present.

   343         */

   344         IMPORT_C CSdpKeyField* Key();

   345 

   346         /**

   347         * Gets the session level encryption key field.

   348         *

   349         * @return The encryption key or zero if not present.

   350         */

   351         IMPORT_C const CSdpKeyField* Key() const;

   352 

   353         /**

   354         * Sets or removes the encryption key field.

   355         * Note, that the ownership of the argument is 

   356         * transferred to the SDP document object.

   357         *

   358         * @param aObj New value of the field or zero to remove the field.

   359         */

   360         IMPORT_C void SetKey(CSdpKeyField* aObj);

   361 

   362         /**

   363         * Gets the possibly empty set of session level attribute fields.

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

   365         * The array may contain zero references and these are ignored.

   366         *

   367         * The objects referenced from the array are owned by the document

   368         * instance and must not be deleted. An object can be removed from the

   369         * document by setting the corresponding element to zero. By doing so,

   370         * the calling party receives ownership of the removed object.

   371         *

   372         * @return Set of session level attributes.

   373         */

   374         IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();

   375 

   376         /**

   377         * Gets the possibly empty set of media description fields.

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

   379         * Note, that media level attributes and fields are managed 

   380         * through the corresponding media field instance and not through

   381         * the document instance.

   382         * The array may contain zero references and these are ignored.

   383         *

   384         * The objects referenced from the array are owned by the document

   385         * instance and must not be deleted. An object can be removed from the

   386         * document by setting the corresponding element to zero. By doing so,

   387         * the calling party receives ownership of the removed object.

   388         *

   389         * @return Set of media description fields.

   390         */

   391         IMPORT_C RPointerArray<CSdpMediaField>& MediaFields();

   392 

   393     private:

   394         CSdpDocument();

   395         void ConstructL();

   396         void ConstructL(const CSdpDocument& aSdpDocument);

   397         void DoInternalizeL(RReadStream& aStream);

   398 

   399         void ParseL (const TDesC8& aText);

   400         void ParseSessionVersionL();

   401         void ParseSessionOwnerL();

   402         void ParseSessionNameL();

   403         void ParseSessionInformationL();

   404         void ParseUriL();

   405         void ParseEmailL();

   406         void ParsePhoneL();

   407         void ParseConnectionL();

   408         void ParseBandwidthL();

   409         void ParseTimeFieldL();

   410         void ParseZoneAdjustmentL();

   411         void ParseEncryptionKeyL();

   412         void ParseAttributeFieldL();

   413         void ParseMediaLevelL ();

   414         void ExternalizeDesCArrayL(CDesC8ArraySeg& aArray,

   415                                RWriteStream& aStream) const;

   416         void EncodeDesCArrayL(CDesC8ArraySeg& aArray,TInt aIndex,

   417                                             RWriteStream& aStream) const;

   418 

   419         TDesC8& GetTokenFromStreamL(RReadStream& aStream);

   420 

   421         CSdpDocument(const CSdpDocument&); // Hidden.

   422         CSdpDocument& operator = (const CSdpDocument&); // Hidden

   423 

   424     private: // Data

   425             

   426         HBufC8* iInfo;

   427         HBufC8* iSessionName;

   428         HBufC8* iZoneAdjustments;

   429         CSdpKeyField* iSdpKeyField;

   430         CSdpOriginField* iSdpOriginField;

   431         CSdpConnectionField* iSdpConnectionField;

   432         TUint iSdpVersion;

   433         RPointerArray<CSdpTimeField>* iTimeFields;

   434         RPointerArray<CSdpBandwidthField>* iBandwidthFields;

   435         RPointerArray<CSdpAttributeField>* iAttributeFields;

   436         RPointerArray<CSdpMediaField>* iMediaFields;

   437         CUri8* iUri;

   438         CDesC8ArraySeg* iEmailFields;

   439         CDesC8ArraySeg* iPhoneFields;

   440         RStringPool iPool;

   441         HBufC8* iToken;

   442         CSdpCodecParseUtil* iSdpCodecParseUtil;

   443     };

   444 

   445 #endif // CSDPDOCUMENT_H