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 base

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef simplebasedocument_H

    22 #define simplebasedocument_H

    23 

    24 #include <e32std.h>

    25 #include "simplecommon.h"

    26 #include "msimpledocument.h"

    27 

    28 // FORWARD DECLARATION

    29 class CSimpleNamespace;

    30 class CSimpleElement;

    31 

    32 

    33 /**

    34  *  CSimpleBaseDocument

    35  *

    36  *  SIMPLE Engine document base class.

    37  *

    38  *  @lib simplexmlutils

    39  *  @since S60 v3.2

    40  */

    41 

    42 class CSimpleBaseDocument : public CBase

    43     {

    44 

    45 public:

    46 

    47     /**

    48      * Destructor.

    49      */

    50     virtual ~CSimpleBaseDocument();

    51 

    52     /**

    53      * Validates root element name

    54      * Leaves if not valid

    55      * @param aName element name

    56      */

    57     virtual void ValidateXmlL( const TDesC8& aName ) = 0;

    58 

    59 

    60 // from base class MSimpleDocument

    61 

    62 

    63     /**

    64      * From MSimpleDocument

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

    66      *

    67      * @since S60 3.2

    68      * @return default namespace URI

    69      */

    70     TPtrC8 DefaultNamespace();

    71 

    72     /**

    73      * From MSimpleDocument

    74      * Add new newspace

    75      *

    76      * @since S60 3.2

    77      * @param aPrefix:  Namespace prefix

    78      * @param aUri: Namespace URI

    79      */

    80     void AddNamespaceL( const TDesC8& aPrefix,

    81               const TDesC8& aUri);

    82 

    83     /**

    84      * From MSimpleDocument

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

    86      *

    87      * @since S60 3.2

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

    89      *       no namespaces.

    90      */

    91     RPointerArray<MSimpleNamespace>& NamespacesL();

    92 

    93     /**

    94      * Externalize the document into write stream.

    95      *

    96      * @since S60 3.2

    97      * @param aStream write stream

    98     */

    99     void ExternalizeL( RWriteStream& aStream );

   100 

   101 // from base class MSimpleEntity

   102 

   103     /**

   104      * Destroy this element entity and all its descendant elements

   105      *

   106      * @since S60 3.2

   107      */

   108     void Close();

   109 

   110     /**

   111      * Getter for Element's local name.

   112      * LocalName and Namespace are given in factory method.

   113      * @return KNullDesC if not set

   114      */

   115     const TDesC8& LocalName();

   116 

   117     /**

   118      * Getter for Element's default namespace.

   119      *

   120      * @since S60 3.2

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

   122      *      NULL if not set. Ownership is transferred.

   123      */

   124     MSimpleNamespace* DefNamespaceL();

   125 

   126     /**

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

   128      *

   129      * @since S60 3.2

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

   131      */

   132     TBool HasContent();

   133 

   134     /**

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

   136      *

   137      * @since S60 3.2

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

   139      */

   140     HBufC* ContentUnicodeL();

   141 

   142     /**

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

   144      *

   145      * @since S60 3.2

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

   147      */

   148     void SetContentUnicodeL(const TDesC& aContent);

   149 

   150 

   151     /**

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

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

   154      *              or empty array if no matching found.

   155      *              Any modifications made on the returned items

   156      *              modify the real childs too.

   157      * @return KErrNone   ok

   158      *       KErrNotFound No child elements exist.

   159      */

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

   161 

   162     /**

   163      * Gets the value of the given attribute.

   164      *

   165      * @since S60 3.2

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

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

   168      *      TRANSFERRED.

   169      */

   170     HBufC* AttrValueLC( const TDesC8& aName );

   171 

   172     /**

   173      * Gets the value of the given attribute.

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

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

   176      *       NOT TRANSFERRED.

   177      */

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

   179 

   180     /**

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

   182      * the value of the attribute will be replaced.

   183      *

   184      * @since S60 3.2

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

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

   187      */

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

   189 

   190     /**

   191      * From MSimpleElement

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

   193      *

   194      * @since S60 3.2

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

   196      *             or empty array if no matching found.

   197      * @return KErrNone ok

   198      *       KErrNotFound No child elements exist.

   199      */

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

   201 

   202     /**

   203      * Gets the parent element of this element.

   204      *

   205      * @since S60 3.2

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

   207      *      Ownership NOT transferred to the caller.

   208      */

   209     MSimpleElement* SimpleParentL();

   210 

   211     /**

   212      * Detach the element from its parent.

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

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

   215      * copy those namespace declarations to this element.

   216      * Leaves with KErrNotFound if parent was not set and

   217      * nothing to detach.

   218      *

   219      * @since S60 3.2

   220      */

   221     void DetachSimpleL();

   222 

   223     /**

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

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

   226      *

   227      * @since S60 3.2

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

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

   230      * @return the added Element

   231      * Leave codes:

   232      *    KErrSenInvalidCharacters if aLocalName contains illegal characters.

   233      *    KErrSenZeroLengthDescriptor if aLocalName is zero length.

   234      */

   235     MSimpleElement* AddSimpleElementL(

   236         const TDesC8& aNsUri,

   237         const TDesC8& aLocalName);

   238 

   239     /**

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

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

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

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

   244      * namespace.

   245      *

   246      * @since S60 3.2

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

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

   249      *  Leave codes:

   250      *    KErrSenInvalidCharacters if aLocalName contains illegal characters.

   251      *    KErrSenZeroLengthDescriptor if aLocalName is zero length.

   252      */

   253     MSimpleElement* AddSimpleElementL(

   254         const TDesC8& aLocalName );

   255 

   256     /**

   257      * Remove an element from the childs.

   258      *

   259      * @since S60 3.2

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

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

   262      */

   263     void RemoveSimpleElement(

   264         const TDesC8& aNsUri,

   265         const TDesC8& aLocalName);       

   266 

   267 protected:

   268 

   269     /**

   270      * Two-phase constructor, for derived classes

   271      */

   272     void BaseConstructL(

   273         const TDesC8& aNsUri,

   274         const TDesC8& aLocalName );

   275 

   276     /**

   277      * Contructor for deriveed classes

   278      * @since S60 3.2     

   279      * @param aXml XML document.

   280      */

   281     void BaseConstructL(

   282         const TDesC8& aXml );

   283 

   284     CSimpleElement* Root();

   285     

   286         

   287     /**

   288      * constructor

   289      */

   290     CSimpleBaseDocument();     

   291     

   292 private:

   293 

   294      /**      

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

   296       *

   297       * @since S60 3.2

   298       * @return default namespace URI

   299       */

   300     TPtrC8 DoDefaultNamespaceL();

   301 

   302 

   303 

   304 private:    // data

   305 

   306     /**

   307      * Root element.

   308      * Own.

   309      */

   310     CSimpleElement*     iRoot;

   311 

   312     /**

   313      * Extra namespaces

   314      */

   315     RPointerArray<CSimpleNamespace> iNsps;

   316 

   317     /**

   318      * Extra namespaces, M-classes

   319      */

   320     RPointerArray<MSimpleNamespace> iMNsps;

   321 

   322     };

   323 

   324 #endif 

   325 

   326 // End of File