1 sdpdocument.h

     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          : 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 "_sdpdefs.h"

    31 #include <stringpool.h>

    32 

    33 // FORWARD DECLARATIONS

    34 class SdpUtil;

    35 class RReadStream;

    36 class RWriteStream;

    37 class CUri8;

    38 class CDesC8Array;

    39 class CSdpOriginField;

    40 class CSdpEmailField;

    41 class CSdpPhoneField;

    42 class CSdpConnectionField;

    43 class CSdpBandwidthField;

    44 class CSdpTimeField;

    45 class CSdpAttributeField;

    46 class CSdpMediaField;

    47 class CSdpKeyField;

    48 class CSdpCodecParseUtil;

    49 

    50 // CLASS DECLARATION

    51 /**

    52  *  @publishedAll

    53  *  @released

    54  *

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

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

    57  *    describing a session.

    58  *

    59  *    The normative reference for correct formatting and values is

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

    61  *  member documentation. The implementation supports this normative

    62  *  reference, but does not enforce it fully. 

    63  *

    64  *  @lib sdpcodec.lib

    65  */

    66 class CSdpDocument : public CBase

    67     {

    68     public: // Constructors and destructor

    69         /**

    70         * Constructs a new SDP document.

    71         *    

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

    73         * @return a new instance.

    74         */

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

    76 

    77         /**

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

    79         *    

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

    81         * @return a new instance.

    82         */

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

    84             

    85         /**

    86         * Constructs a new, empty SDP document.

    87         * The instance will have the following initial values:

    88         *      v=0

    89         *      s=-

    90         *      t=0 0

    91         *

    92         * @return a new instance.

    93         */

    94         IMPORT_C static CSdpDocument* NewL();

    95 

    96         /**

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

    98         * the cleanup stack.

    99         * The instance will have the following initial values:

   100         *      v=0

   101         *      s=-

   102         *      t=0 0

   103         *

   104         * @return a new instance.

   105         */

   106         IMPORT_C static CSdpDocument* NewLC();

   107 

   108         /**

   109         * Deletes the resources held by the instance.

   110         */

   111         IMPORT_C ~CSdpDocument();

   112 

   113     public: 

   114         /**

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

   116         *

   117         * @param aStream The output stream.

   118         */

   119         IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   120 

   121         /**

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

   123         *

   124         * @param aStream The input stream.

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

   126         */

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

   128 

   129         /**

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

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

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

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

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

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

   136         * 

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

   138         *        stream includes correctly formatted SDP description.

   139         */

   140         IMPORT_C void EncodeL(RWriteStream& aStream) const;

   141 

   142         /**

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

   144         *

   145         * @return a new instance.

   146         */

   147         IMPORT_C CSdpDocument* CloneL() const;

   148 

   149         /**

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

   151         *

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

   153         */

   154         IMPORT_C TBool IsValid() const;

   155 

   156         /**

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

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

   159         *

   160         * @return The SDP version number.

   161         */ 

   162         IMPORT_C TUint SdpVersion() const;

   163 

   164         /**

   165         * Gets a reference to the session origin field.

   166         * Note, that the ownership is not transferred and

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

   168         *

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

   170         */

   171         IMPORT_C CSdpOriginField* OriginField();

   172 

   173         /**

   174         * Gets a reference to the session origin field.

   175         *

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

   177         */

   178         IMPORT_C const CSdpOriginField* OriginField() const;

   179 

   180         /**

   181         * Sets or removes the session origin field.

   182         * Note, that the ownership of the argument is 

   183         * transferred to the SDP document object.

   184         *

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

   186         */

   187         IMPORT_C void SetOriginField(CSdpOriginField* aObj);

   188 

   189         /**

   190         * Gets the session name field value.

   191         *

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

   193         */

   194         IMPORT_C const TDesC8& SessionName() const;

   195 

   196         /**

   197         * Sets the session name field value.

   198         *

   199         * @param aValue Valid session name value. 

   200         *        Note that an empty value is not accepted.

   201         * @leave KErrSdpCodecSessionField if

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

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

   204         */

   205         IMPORT_C void SetSessionNameL(const TDesC8& aValue);

   206 

   207         /**

   208         * Gets the session information field value.

   209         *

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

   211         */

   212         IMPORT_C const TDesC8& Info() const;

   213 

   214         /**

   215         * Sets or removes the session information field value.

   216         *

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

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

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

   220         */

   221         IMPORT_C void SetInfoL(const TDesC8& aValue);

   222 

   223         /**

   224         *    Gets the session URI field value.

   225         *    Note, that the ownership is not transferred and

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

   227         *

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

   229         */

   230         IMPORT_C CUri8* Uri();

   231 

   232         /**

   233         * Gets the session URI field value.

   234         *

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

   236         */

   237         IMPORT_C const CUri8* Uri() const;

   238 

   239         /**

   240         * Sets or removes the session level URI field.

   241         * Note, that the ownership of the argument is 

   242         * transferred to the SDP document object.

   243         *

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

   245         */

   246         IMPORT_C void SetUri(CUri8* aValue);

   247 

   248         /**

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

   250         * add and remove fields into the document.

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

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

   253         *

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

   255         */

   256         IMPORT_C CDesC8Array& EmailFields();

   257 

   258         /**

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

   260         * add and remove fields into the document.

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

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

   263         *  

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

   265         */

   266         IMPORT_C CDesC8Array& PhoneFields();

   267 

   268         /**

   269         * Gets the session level connection field.

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

   271         * deleted by the caller.

   272         *

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

   274         */

   275         IMPORT_C CSdpConnectionField* ConnectionField();

   276 

   277         /**

   278         * Gets the session level connection field.

   279         *

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

   281         */

   282         IMPORT_C const CSdpConnectionField* ConnectionField() const;

   283 

   284         /**

   285         * Sets or removes the session level connection field.

   286         * Note, that the ownership of the argument is 

   287         * transferred to the SDP document object.

   288         *

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

   290         */    

   291         IMPORT_C void SetConnectionField(CSdpConnectionField* aObj);

   292 

   293         /**

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

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

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

   297         *

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

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

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

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

   302         *

   303         * @return Set of bandwidth fields.

   304         */

   305         IMPORT_C RPointerArray<CSdpBandwidthField>& BandwidthFields();

   306 

   307         /**

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

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

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

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

   312         *

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

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

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

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

   317         *

   318         * @return Set of time fields.

   319         */

   320         IMPORT_C RPointerArray<CSdpTimeField>& TimeFields();

   321 

   322         /** 

   323         * Gets the zone adjustments field value.

   324         *

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

   326         *         field is not present.

   327         */

   328         IMPORT_C const TDesC8& ZoneAdjustments() const;

   329 

   330         /** 

   331         * Sets the zone adjustments field value.

   332         *

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

   334         *        if field is not present.

   335         */

   336         IMPORT_C void SetZoneAdjustmentsL(const TDesC8& aValue);

   337 

   338         /**

   339         * Gets the session level encryption key field.

   340         * Note, that the ownership is not transferred and

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

   342         *

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

   344         */

   345         IMPORT_C CSdpKeyField* Key();

   346 

   347         /**

   348         * Gets the session level encryption key field.

   349         *

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

   351         */

   352         IMPORT_C const CSdpKeyField* Key() const;

   353 

   354         /**

   355         * Sets or removes the encryption key field.

   356         * Note, that the ownership of the argument is 

   357         * transferred to the SDP document object.

   358         *

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

   360         */

   361         IMPORT_C void SetKey(CSdpKeyField* aObj);

   362 

   363         /**

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

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

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

   367         *

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

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

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

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

   372         *

   373         * @return Set of session level attributes.

   374         */

   375         IMPORT_C RPointerArray<CSdpAttributeField>& AttributeFields();

   376 

   377         /**

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

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

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

   381         * through the corresponding media field instance and not through

   382         * the document instance.

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

   384         *

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

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

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

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

   389         *

   390         * @return Set of media description fields.

   391         */

   392         IMPORT_C RPointerArray<CSdpMediaField>& MediaFields();

   393 

   394     private:

   395         CSdpDocument();

   396         void ConstructL();

   397         void ConstructL(const CSdpDocument& aSdpDocument);

   398         void DoInternalizeL(RReadStream& aStream);

   399 

   400         void ParseL (const TDesC8& aText);

   401         void ParseSessionVersionL();

   402         void ParseSessionOwnerL();

   403         void ParseSessionNameL();

   404         void ParseSessionInformationL();

   405         void ParseUriL();

   406         void ParseEmailL();

   407         void ParsePhoneL();

   408         void ParseConnectionL();

   409         void ParseBandwidthL();

   410         void ParseTimeFieldL();

   411         void ParseZoneAdjustmentL();

   412         void ParseEncryptionKeyL();

   413         void ParseAttributeFieldL();

   414         void ParseMediaLevelL ();

   415         void ExternalizeDesCArrayL(CDesC8ArraySeg& aArray,

   416                                RWriteStream& aStream) const;

   417         void EncodeDesCArrayL(CDesC8ArraySeg& aArray,TInt aIndex,

   418                                             RWriteStream& aStream) const;

   419 

   420         TDesC8& GetTokenFromStreamL(RReadStream& aStream);

   421 

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

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

   424 

   425     private: // Data

   426             

   427         HBufC8* iInfo;

   428         HBufC8* iSessionName;

   429         HBufC8* iZoneAdjustments;

   430         CSdpKeyField* iSdpKeyField;

   431         CSdpOriginField* iSdpOriginField;

   432         CSdpConnectionField* iSdpConnectionField;

   433         TUint iSdpVersion;

   434         RPointerArray<CSdpTimeField>* iTimeFields;

   435         RPointerArray<CSdpBandwidthField>* iBandwidthFields;

   436         RPointerArray<CSdpAttributeField>* iAttributeFields;

   437         RPointerArray<CSdpMediaField>* iMediaFields;

   438         CUri8* iUri;

   439         CDesC8ArraySeg* iEmailFields;

   440         CDesC8ArraySeg* iPhoneFields;

   441         RStringPool iPool;

   442         HBufC8* iToken;

   443         CSdpCodecParseUtil* iSdpCodecParseUtil;

   444     };

   445 

   446 #endif // CSDPDOCUMENT_H