1 /*

     2 * Copyright (c) 2006 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:   SIMPLE document

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef simpledocument_H

    22 #define simpledocument_H

    23 

    24 #include <e32std.h>

    25 #include "simplecommon.h"

    26 #include "msimpledocument.h"

    27 #include "simplebasedocument.h"

    28 

    29 // FORWARD DECLARATION

    30 class CSimpleNamespace;

    31 class CSimpleContent;

    32 class CBodyPart;

    33 class MSimpleContent;

    34 // class RPointerArray;

    35 

    36 

    37 

    38                    

    39 

    40 

    41 /**

    42  *  CSimpleDocument

    43  *

    44  *  SIMPLE Engine core.

    45  *

    46  *  @lib simplexmlutils

    47  *  @since S60 3.2

    48  */

    49 

    50 class CSimpleDocument : public CSimpleBaseDocument, public MSimpleDocument

    51     {

    52     

    53 public:

    54 

    55    

    56 public:

    57 

    58     /**

    59      * Two-phased constructor.

    60      * @since S60 3.2

    61      * @return CSimpleDocument

    62      */

    63     static CSimpleDocument* NewL( );

    64 

    65     /**

    66      * Two-phased constructor.

    67      * @since S60 3.2

    68      * @param aXml XML document

    69      * @return CSimpleDocument

    70      */

    71     static CSimpleDocument* NewL( const TDesC8& aXml );

    72     

    73     /**

    74      * Two-phased constructor.

    75      * @since S60 3.2

    76      * @param aData MIME multipart data     

    77      * @param aBoundary MIME multipart boundary     

    78      * @param aStart MIME multipart start content-id  

    79      * @return CSimpleDocument

    80      */

    81     static CSimpleDocument* NewInMultiPartL( 

    82         const TDesC8& aData, const TDesC8& aBoundary, const TDesC8& aStart );    

    83 

    84     /**

    85      * Destructor.

    86      */

    87     virtual ~CSimpleDocument();

    88     

    89     /**

    90      * Validates root element name

    91      * Leaves if not valid

    92      * @param aName element name

    93      */

    94     void ValidateXmlL( const TDesC8& aName );

    95 

    96 // from base class MSimpleDocument

    97 

    98 

    99     /**

   100      * From MSimpleDocument

   101      * Entity's URI getter. URI is specified in a factory method

   102      *

   103      * @since S60 3.2

   104      * @return URI

   105      */

   106     const TDesC8* EntityURI();

   107 

   108     /**

   109      * From MSimpleDocument

   110      * Entity's URI setter.

   111      *

   112      * @since S60 3.2

   113      * @return URI

   114      */

   115     void SetEntityURIL( const TDesC8& aValue );

   116 

   117     /**

   118      * From MSimpleDocument

   119      * Document's default namespace accessor. It is PIDF namespace.

   120      *

   121      * @since S60 3.2

   122      * @return default namespace URI

   123      */

   124     TPtrC8 DefaultNamespace();

   125 

   126     /**

   127      * From MSimpleDocument

   128      * Add new newspace

   129      *

   130      * @since S60 3.2

   131      * @param aPrefix:  Namespace prefix

   132      * @param aUri: Namespace URI

   133      */

   134     void AddNamespaceL( const TDesC8& aPrefix,

   135                         const TDesC8& aUri);

   136 

   137     /**

   138      * From MSimpleDocument

   139      * Gets all namespaces of this element in an array.

   140      *

   141      * @since S60 3.2

   142      * @return array of namespaces. Array will be empty if element has

   143      *         no namespaces.

   144      *         Any modifications made on the returned items

   145      *         DOES NOT modify the real childs.

   146      *         Do NOT call ResetAndDestroy() for the array,

   147      *         you may call Reset() only. The array is valid only till

   148      *         the next call of this method in this entity.      

   149      */

   150     RPointerArray<MSimpleNamespace>& NamespacesL();

   151     

   152     /**

   153      * Copies content from given element to this element appending to the 

   154 	 * existing content if there is any.

   155      * @since S60 3.2

   156      * @param aSource The source element.

   157      */

   158 	void CopyFromL( MSimpleDocument& aSource );

   159 

   160     /**

   161      * Externalize the document into write stream.

   162      *

   163      * @since S60 3.2

   164      * @param aStream write stream

   165      */

   166     void ExternalizeL( RWriteStream& aStream );

   167     

   168     /**

   169      * Get direct contents

   170      * @param aContents array of contents [out]. 

   171      *        This is walid till the AddDirectContentL method. 

   172      */     

   173     void GetDirectContentsL( RPointerArray<MSimpleContent>& aContents );

   174     

   175     /**

   176      * Add content

   177      * @param aContent content, the data content is copied into document.

   178      * @param aCopyContent ETrue if buffer of each content is copied or 

   179      *        ownership is transferred just without copy.     

   180      */

   181     void AddDirectContentL( MSimpleContent& aContent, TBool aCopyContent );

   182     

   183     

   184 // from base class MSimpleEntity

   185 

   186     /**

   187      * Destroy this element entity and all its descendant elements

   188      *

   189      * @since S60 3.2

   190      */

   191     void Close();

   192 

   193     /**

   194      * Getter for Element's local name.

   195      * LocalName and Namespace are given in factory method.

   196      * @return KNullDesC if not set

   197      */

   198     const TDesC8& LocalName();

   199 

   200     /**

   201      * Getter for Element's default namespace.

   202      *

   203      * @since S60 3.2

   204      * @return const pointer to the CSenNamespace object of this Element.

   205      *        NULL if not set. Ownership is transferred.

   206      */

   207     MSimpleNamespace* DefNamespaceL();

   208 

   209     /**

   210      * Method for checking if the element has any content within.

   211      *

   212      * @since S60 3.2

   213      * @return ETrue if has content, EFalse if not.

   214      */

   215     TBool HasContent();

   216 

   217     /**

   218      * Getter for the content of the element, unicode version.

   219      *

   220      * @since S60 3.2

   221      * @return content as unicode. Ownership IS TRANSFERRED to the caller.

   222      */

   223     HBufC* ContentUnicodeL();

   224 

   225     /**

   226      * Sets the content to the element. Old content is overwritten.

   227      *

   228      * @since S60 3.2

   229      * @param aContent: The content to be set. Can be KNullDesC

   230      */

   231     void SetContentUnicodeL(const TDesC& aContent);

   232 

   233 

   234     /**

   235      * Getting the child elements of this element matching the given criteria.

   236      * @param aElementArray:    Array to be filled with the matching elements,

   237      *                          or empty array if no matching found.

   238      *                          Any modifications made on the returned items

   239      *                          modify the real childs too.

   240      * @return KErrNone     ok

   241      *         KErrNotFound No child elements exist.

   242      */

   243     TInt SimpleElementsL( RPointerArray<MSimpleElement>& aElementArray );

   244 

   245     /**

   246      * Gets the value of the given attribute.

   247      *

   248      * @since S60 3.2

   249      * @param aName:    Name of the attribute in question.

   250      * @return the value of the attribute, or NULL if not found. Ownership is

   251      *        TRANSFERRED.

   252      */

   253     HBufC* AttrValueLC( const TDesC8& aName );

   254 

   255     /**

   256      * Gets the value of the given attribute.

   257      * @param aName:    Name of the attribute in question.

   258      * @return the value of the attribute, or NULL if not found. Ownership is

   259      *         NOT TRANSFERRED.

   260      */

   261     const TDesC8* AttrValue(const TDesC8& aName);

   262 

   263     /**

   264      * Adds an attribute. If attribute is already existing,

   265      * the value of the attribute will be replaced.

   266      *

   267      * @since S60 3.2

   268      * @param aName     Name of the attribute to be added.

   269      * @param aValue    Value of the attribute to be added.

   270      */

   271     void AddAttrL(const TDesC8& aName, const TDesC& aValue);

   272 

   273     /**

   274      * From MSimpleElement

   275      * Gets all the attributes of this element in an array.

   276      *

   277      * @since S60 3.2

   278      * @param aArray: Array to be filled with the attributes,

   279      *                       or empty array if no matching found.

   280      * @return KErrNone ok

   281      *         KErrNotFound No child elements exist.

   282      */

   283     TInt SimpleAttributesL( RPointerArray<MSimpleAttribute>& aArray );

   284 

   285     /**

   286      * Gets the parent element of this element.

   287      *

   288      * @since S60 3.2

   289      * @return the parent element or NULL if no parent set.

   290      *        Ownership IS TRANSFERRED to the caller.

   291      */

   292     MSimpleElement* SimpleParentL();

   293 

   294     /**

   295      * Detach the element from its parent.

   296      * If the element, or one of its children, is dependent

   297      * on a namespace declared in the scope of the parent

   298      * copy those namespace declarations to this element.

   299      * Leaves with KErrNotFound if parent was not set and

   300      * nothing to detach.

   301      *

   302      * @since S60 3.2

   303      */

   304     void DetachSimpleL();

   305 

   306     /**

   307      * Constructs and adds a new element to the children elements.

   308      * Sets this element to be the new parent of the given element.

   309      *

   310      * @since S60 3.2

   311      * @param aNsUri:       namespace URI of the new element

   312      * @param aLocalName:   local name of the new element

   313      * @return the added Element

   314      * Leave codes:

   315      *      KErrSenInvalidCharacters if aLocalName contains illegal characters.

   316      *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

   317      */

   318     MSimpleElement* AddSimpleElementL(

   319         const TDesC8& aNsUri,

   320         const TDesC8& aLocalName);

   321 

   322     /**

   323      * Constructs and adds a new element to the children elements.

   324      * Sets this element to be the new parent of the given element.

   325      * Note: Element is created with no specific namespace, default namespace

   326      * of some of the upper level elements are in effect if there is such a

   327      * namespace.

   328      *

   329      * @since S60 3.2

   330      * @param aLocalName:   local name of the new element

   331      * @return the added Element. OWNERSHIP IS TRANSFERRED.

   332      *  Leave codes:

   333      *      KErrSenInvalidCharacters if aLocalName contains illegal characters.

   334      *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

   335      */

   336     MSimpleElement* AddSimpleElementL(

   337         const TDesC8& aLocalName );

   338 

   339     /**

   340      * Remove an element from the childs.

   341      *

   342      * @since S60 3.2

   343      * @param   aNsUri:     the namespace URI of the element to be removed.

   344      * @param   aLocalName: the local name of the element to be removed.

   345      */

   346     void RemoveSimpleElement(

   347         const TDesC8& aNsUri,

   348         const TDesC8& aLocalName);

   349 

   350 

   351 protected:

   352 

   353 

   354 private:

   355 

   356     /**

   357      * Two-phase constructor

   358      */

   359     void ConstructL(

   360         const TDesC8& aNsUri,

   361         const TDesC8& aLocalName );

   362         

   363     /**

   364      * Two-phase constructor

   365      */

   366     void ConstructMultiPartL(

   367         const TDesC8& aData, const TDesC8& aBoundary, const TDesC8& aStart );        

   368 

   369     /**

   370      * Two-phase constructor

   371      */

   372     void ConstructL(

   373         const TDesC8& aXml );              

   374 

   375     /**

   376      * constructor

   377      */

   378     CSimpleDocument();

   379     

   380 	/**

   381 	 * ClenupStack operation

   382 	 * aPtrArray RPointerArray<CBodyPart>

   383 	 */

   384 	static void ResetAndDestroy( TAny* aPtrArray );	 

   385 	

   386     /**

   387      * DoConstructL

   388      * Handles XML parsing of MIME multiparts

   389      * @param aParts MIME multipart parts

   390      * @param aStart MIME multipart start content-id     

   391      */

   392     void DoConstructL( RPointerArray<CBodyPart>& aParts, const TDesC8& aStart );

   393     

   394     HBufC8* DoComposeMultiPartL( RPointerArray<CBodyPart>& aBodyArray,

   395                                 const TDesC8& aBoundary);  

   396                                 

   397     void DoExternalizeMultiPartL( 

   398         RPointerArray<CBodyPart>& aBodies, 

   399         RPointerArray<HBufC8>& aBuffers,

   400         RWriteStream& aStream );                              	   

   401 

   402 

   403 private:    // data

   404 

   405     /**

   406      * Direct contents in MIME multipart 

   407      */

   408     RPointerArray<CSimpleContent> iContents;

   409 

   410     };

   411 

   412 

   413 #endif      // simpledocument_H

   414 

   415 // End of File