epoc32/include/mw/senelement.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 /*
     2 * Copyright (c) 2002-2005 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:        Central place for debug-type macros
    15 *
    16 */
    17 
    18 
    19 
    20 
    21 
    22 
    23 
    24 
    25 #ifndef SEN_ELEMENT_H
    26 #define SEN_ELEMENT_H
    27 
    28 //  INCLUDES
    29 #include <e32base.h>
    30 #include <s32strm.h>
    31 #include <xml/attribute.h>
    32 #include <stringpool.h>
    33 
    34 #include <MSenElement.h>
    35 
    36 using namespace Xml;
    37 
    38 // CLASS DECLARATION
    39 
    40 /**
    41 *  Abstract class definition of XML element
    42 *  @lib SenXML.dll
    43 *  @since Series60 3.0
    44 */
    45 class CSenElement : public CBase, public MSenElement
    46     {
    47     public: // Functions from base classes
    48 
    49         // From MSenElement 
    50         
    51         /**
    52         * Getter for local name.
    53         * @since Series60 3.0
    54         * @return KNullDesC if not set (argumentless constructor).
    55         */
    56         virtual const TDesC8& LocalName() const = 0;
    57 
    58         /**
    59         * Getter for namespace URI.
    60         * @since Series60 3.0
    61         * @return KNullDesC if not set.
    62         */      
    63         virtual const TDesC8& NamespaceURI() const = 0;
    64 
    65         /**
    66         * Setter for Element's namespace URI.
    67         * @since Series60 3.0
    68         * @param @param aNsUri: Namespace URI
    69         */      
    70         virtual void SetNamespaceL(const TDesC8& aNsUri) = 0;
    71 
    72         /**
    73         * Setter for Element's namespace URI.
    74         * @since Series60 3.0
    75         * @param aNsPrefix: Namespace prefix
    76         * @param aNsUri:        Namespace URI
    77         */      
    78         virtual void SetNamespaceL( const TDesC8& aNsPrefix,
    79                                     const TDesC8& aNsUri) = 0;
    80 
    81         /**
    82         * Method for adding a namespace for the Element.
    83         * @since Series60 3.0
    84         * @param aPrefix:   Namespace prefix
    85         * @param aUri:  Namespace URI
    86         * @return the added Namespace, or the equivalent pre-existing one.
    87         */      
    88         virtual const CSenNamespace* AddNamespaceL( const TDesC8& aPrefix,
    89                                                     const TDesC8& aUri) = 0;
    90 
    91         /**
    92         * Getter for Element's namespace.
    93         * @since Series60 3.0
    94         * @return const pointer to the CSenNamespace object of this Element.
    95         *         Returns NULL, if not set.
    96         */      
    97         virtual const CSenNamespace* Namespace() = 0;
    98 
    99         /**
   100         * @since Series60 3.0
   101         * @param prefix
   102         * @return the namespace that is declared for the given prefix
   103         *         within the scope of this Element. If no such prefix is
   104         *         declared return NULL.
   105         */      
   106         virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix) = 0;
   107 
   108         /**
   109         * Get namespace that is declared for the given prefix and namespace 
   110         * URI within the scope of this element. 
   111         * @since Series60 3.0
   112         * @param aNsPrefix  The prefix used to search
   113         * @param aUri           The namespace URI used to search.
   114         * @return the found namespace that is declared for the given prefix 
   115         *                   and namespace URI within the scope of this Element
   116         *                   or NULL if not found.
   117         */
   118         virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
   119                                                 const TDesC8& aUri) = 0;
   120 
   121         /**
   122         * @since Series60 3.0
   123         * @param aNsPrefix      The prefix used to search
   124         * @param aCheckInParent The flag indicating whether to check parent's
   125         *                       namespaces too if not found in the current 
   126         *                       element. 
   127         *                       ETrue to check, EFalse for not to check.
   128         * @return the found Namespace that is declared for the given prefix 
   129         *                   and namespace URI within the scope of this Element
   130         *                   or NULL if not found
   131         */
   132         virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
   133                                                 const TBool aCheckInParent) = 0;
   134 
   135         /**
   136         * Getter for namespace prefix of this element.
   137         * @since Series60 3.0
   138         * @return namespace prefix or KNullDesC8 if not set.
   139         */
   140         virtual const TDesC8& NsPrefix() const = 0;
   141 
   142         /**
   143         * Setter for namespace prefix of this element.
   144         * @since Series60 3.0
   145         * @param aPrefix:   new namespace prefix for the element.
   146         */
   147         virtual void SetPrefixL(const TDesC8& aPrefix) = 0;
   148 
   149         /**
   150         * Method for checking if the element has any content within.
   151         * @since Series60 3.0
   152         * @return ETrue if has content, EFalse if not.
   153         */
   154         virtual TBool HasContent() const = 0;
   155 
   156         /**
   157         * Getter for the content of the element.
   158         * @since Series60 3.0
   159         * @return the content or KNullDesC8 if empty.
   160         */
   161         virtual TPtrC8 Content() const = 0;
   162 
   163         /**
   164         * Getter for the content of the element, Unicode (UCS2) version
   165         * @since Series60 3.0
   166         * @return content as Unicode. Ownership is transferred to the caller.
   167         */
   168         virtual HBufC* ContentUnicodeL() const = 0;
   169         
   170         /**
   171         * Sets the content to the element. Old content is overwritten.
   172         * @since Series60 3.0
   173         * @param aContent   The content to be set. Can be KNullDesC8.
   174         * @return The content of the element or KNullDesC8 if no content was set.
   175         */
   176         virtual TPtrC8 SetContentL(const TDesC8& aContent) = 0;
   177 
   178         /**
   179         * Gets the write stream for the content for easy appending.
   180         * Writing 8-bit (UTF-8) string to the returned stream will be appended
   181         * to the content.
   182         * @since Series60 3.0
   183         * @return reference to the RWriteStream.
   184         */
   185         virtual RWriteStream& ContentWriteStreamL() = 0;
   186 
   187         /**
   188          * Checks if element matches to another element
   189          * by it's content and child elements. Element
   190          * can contain more data than the given pattern.
   191          * @since Series60 3.0
   192          * @param   aCandidate The pattern to be matched. Must contain 
   193          *          same or less data for match to come true.
   194          * @return  ETrue if content and possible children match exactly 
   195          *          to given pattern. EFalse otherwise.
   196          */
   197         virtual TBool ConsistsOfL(MSenElement& aCandidate) = 0;
   198 
   199         /**
   200         * Get a list of direct children element that have the given
   201         * name and namespace.
   202         * @since Series60 3.0
   203         * @param    aElementArray RPointerArray that will hold matching elements
   204         * @param    namespaceURI
   205         * @param    localName
   206         * @return   KErrNone or some system-wide error code, 
   207         *           if an error has occurred.
   208         */
   209         virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
   210                                 const TDesC8& aNsUri,
   211                                 const TDesC8& aLocalName) = 0;
   212 
   213         /**
   214         * Get a list of direct children element that have the given
   215         * name and same namespace as this parent Element.
   216         * @since Series60 3.0
   217         * @param    aElementArray RPointerArray that will hold matching elements
   218         * @param    localName
   219         * @return   KErrNone or some system-wide error code, 
   220         *           if an error has occurred.
   221         */
   222         virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
   223                                 const TDesC8& aLocalName) = 0;
   224 
   225         /**
   226         * @since Series60 3.0
   227         * @return an array of child elements. This is an empty array if there
   228         * are no children. Any modifications made on the returned array modify
   229         * the element object.
   230         */
   231         virtual RPointerArray<CSenElement>& ElementsL() = 0;
   232         
   233         /**
   234         * Adds a namespace declaration.
   235         * If this element (or its parent if parameter aCheckInParent is ETrue) 
   236         * already has a namespace with the same prefix and URI the given
   237         * namespace is not added.
   238         * @since Series60 3.0
   239         * @param aNewNamespace
   240         * @param aCheckInParent
   241         * @return the added Namespace, or the equivalent pre-existing one.
   242         */
   243         virtual const CSenNamespace* AddNamespaceL(CSenNamespace& aNewNamespace,
   244                                                     TBool aCheckInParent) = 0;
   245 
   246         /**
   247         * Gets the value of the given attribute.
   248         * @since Series60 3.0
   249         * @param aName: Name of the attribute in question.
   250         * @return the value of the attribute, or NULL if not found. 
   251         * Ownership is not transferred to caller.
   252         */
   253         virtual const TDesC8* AttrValue(const TDesC8& aName) = 0;
   254 
   255         /**
   256         * Adds an attribute. If attribute is already existing, 
   257         *                  the value of the attribute will be replaced.
   258         * @since Series60 3.0
   259         * @param aName      Name of the attribute to be added.
   260         * @param aValue Value of the attribute to be added.
   261         */
   262         virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue) = 0;
   263 
   264         /**
   265         * Gets all the attributes of this element in an array.
   266         * @since Series60 3.0
   267         * @return array of attributes. Array will be empty if element has 
   268         *         no attributes.
   269         */
   270         virtual RPointerArray<CSenBaseAttribute>& AttributesL() = 0;
   271 
   272         /**
   273         * Gets all the namespaces of this element in an array.
   274         * @since Series60 3.0
   275         * @return array of namespaces. Array will be empty if element has 
   276         *         no namespaces.
   277         */
   278         virtual RPointerArray<CSenNamespace>& NamespacesL() = 0;
   279 
   280         /**
   281         * Gets the parent element of this element.
   282         * @since Series60 3.0
   283         * @return the parent element or NULL if no parent set. 
   284         *           Ownership is NOT transferred to the caller.
   285         */
   286         virtual CSenElement* Parent() = 0;
   287 
   288         /**
   289         * From MSenElement  Sets the parent element to this element. 
   290         * Notice that the element is not automatically added as a 
   291         * child of the parent. Parent's AddElementL() must be called 
   292         * to achieve that.
   293         *
   294         * @since Series60 3.0
   295         * @param apParent:  The wanted parent. Can be NULL.
   296         * @return   the parent element
   297         */
   298         virtual CSenElement* SetParent(CSenElement* apParent) = 0;
   299 
   300         /**
   301         * Detach the element from its parent.
   302         * If the element, or one of its children, is dependent
   303         * on a namespace declared in the scope of the parent
   304         * copy those namespace declarations to this element.
   305         * @since Series60 3.0
   306         * @return this Element. Ownership is NOT transferred to the caller.
   307         *         or NULL if no parent was set, and nothing was detached.
   308         */
   309         virtual CSenElement* DetachL() = 0;
   310 
   311         /**
   312         * Gets a child element from a specified index.
   313         * @since Series60 3.0
   314         * @param  aIndex:   the index what to get
   315         * @return child element from a current index. NULL if no child in given
   316         *         index is found
   317         */
   318         virtual CSenElement* Child(TInt aIndex) = 0;
   319 
   320         /**
   321         * Gets the root element. If no parent element, returns this element.
   322         * @since Series60 3.0
   323         * @return the root of the tree. Ownership is not transferred.
   324         */
   325         virtual MSenElement& Root() = 0;
   326 
   327         /**
   328         * Gets the child element with the specified local name.
   329         * Assumes that namespace is the same as this parent element.
   330         * @since Series60 3.0
   331         * @param aLocalName is the XML localname of the requested child element
   332         * @return   the child element or NULL if the child with the specified 
   333         *           local name is not found. Ownership is NOT transferred.
   334         */
   335         virtual CSenElement* Element(const TDesC8& aLocalName) = 0;
   336 
   337         /**
   338         * Gets the child element with the specified local name and namespace URI.
   339         * @since Series60 3.0
   340         * @param aNsUri is the XML namespace of the requested child element
   341         * @param aLocalName  is the XML localname of the requested child element
   342         * @return   the child element or NULL if the child with the specified 
   343         *           criterias is not found. Ownership is NOT transferred.
   344         */
   345         virtual CSenElement* Element(const TDesC8& aNsUri,
   346                                      const TDesC8& aLocalName) = 0;
   347 
   348         /**
   349         * Create a new element ready for adding or insertion.
   350         * If the given namespace prefix is not declared yet
   351         * the element will not be created and NULL will be returned.
   352         * @since Series60 3.0
   353         * @param aNsPrefix: The namespace prefix
   354         * @param aLocalName:    The new elements localname
   355         * @return   the new Element just created, or NULL if given prefix was not
   356         *           declared yet. Ownership is transferred to the caller.
   357         * Leave codes:  
   358         *       KErrSenInvalidCharacters if aLocalName contain illegal characters.      
   359         *       KErrSenZeroLengthDescriptor if aLocalName is zero length.
   360         */
   361         virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,
   362                                             const TDesC8& aLocalName) = 0;
   363 
   364         /**
   365         * Insert an Element into the list of children elements
   366         * so that the inserted Element is placed right before the aBeforeElement.
   367         * If aBeforeElement is not found, element will be appended to the last
   368         * position.
   369         * Function leaves if error occurs in inserting.
   370         * @since Series60 3.0
   371         * @param aInsertedElement   the element to be inserted. 
   372         *                           Ownership is transferred.
   373         * @param aBeforeElement     the element which will be right next to the 
   374         *                           element just inserted.
   375         * @return the inserted Element
   376         */
   377         virtual CSenElement& InsertElementL(CSenElement& aInsertedElement,
   378                                             const CSenElement& aBeforeElement) = 0;
   379 
   380         /**
   381         * Adds an Element to the children elements. 
   382         * Sets this element to be the new parent of the given element.
   383         * @since Series60 3.0
   384         * @param aElement:  the element to be added. Ownership is transferred.
   385         * @return the added Element
   386         */
   387         virtual CSenElement& AddElementL(CSenElement& aElement) = 0;
   388 
   389         /**
   390         * Constructs and adds a new element to the children elements. 
   391         * Sets this element to be the new parent of the given element.
   392         * @since Series60 3.0
   393         * @param aNsUri     namespace URI of the new element
   394         * @param aLocalName local name of the new element
   395         * @return the added Element
   396         * Leave codes:  
   397         *       KErrSenInvalidCharacters if aLocalName contains illegal characters.     
   398         *       KErrSenZeroLengthDescriptor if aLocalName is zero length.
   399         */
   400         virtual CSenElement& AddElementL(   const TDesC8& aNsUri,
   401                                             const TDesC8& aLocalName) = 0;
   402         
   403         /**
   404         * Constructs and adds a new element to the children elements. 
   405         * Sets this element to be the new parent of the given element.
   406         * @since Series60 3.0
   407         * @param aNsUri     namespace URI of the new element
   408         * @param aLocalName local name of the new element
   409         * @param aQName     qualified name of the new element
   410         * @return the added Element
   411         * Leave codes:  
   412         *       KErrSenInvalidCharacters if aLocalName or aQName contain illegal 
   413         *       characters.     
   414         *
   415         *       KErrSenZeroLengthDescriptor if aLocalName or aQName is zero 
   416         *       length.
   417         */
   418         virtual CSenElement& AddElementL(const TDesC8& aNsUri,
   419                                          const TDesC8& aLocalName,
   420                                          const TDesC8& aQName) = 0;
   421 
   422         /**
   423         * Constructs and adds a new element to the children elements. 
   424         * Sets this element to be the new parent of the given element.
   425         * Note: Element is created with no specific namespace, default namespace
   426         * of some of the upper level elements are in effect if there is such a 
   427         * namespace.
   428         * @since Series60 3.0
   429         * @param aLocalName local name of the new element
   430         * @return the added Element
   431         * Leave codes:  
   432         *       KErrSenInvalidCharacters if aLocalName contains illegal 
   433         *       characters.     
   434         *
   435         *       KErrSenZeroLengthDescriptor if aLocalName is zero length.
   436         */
   437         virtual CSenElement& AddElementL(const TDesC8& aLocalName) = 0;
   438 
   439         /**
   440         * Remove an element from the childs.
   441         * @since Series60 3.0
   442         * @param aElement:  the element to be removed.
   443         * @return The removed element. May be NULL if nothing was removed
   444         *           (if child element was not found).
   445         *           The caller TAKES OWNERSHIP of the removed element.
   446         */
   447         virtual CSenElement* RemoveElement(CSenElement& aElement) = 0;
   448 
   449         /**
   450         * Remove an element from the childs.
   451         * @since Series60 3.0
   452         * @param    aNsUri:     the namespace URI of the element to be removed.
   453         * @param    aLocalName: the local name of the element to be removed.
   454         * @return The removed element. May be NULL if nothing was removed
   455         *           (if child element was not found).
   456         *           The caller TAKES OWNERSHIP of the removed element.
   457         */
   458         virtual CSenElement* RemoveElement( const TDesC8& aNsUri,
   459                                             const TDesC8& aLocalName) = 0;
   460 
   461         /**
   462         * Remove a child element.
   463         * @since Series60 3.0
   464         * @param    aLocalName: the local name of the element to be removed.
   465         * @return The removed element. May be NULL if nothing was removed
   466         *           (if child element was not found).
   467         *
   468         * The caller takes ownership of the removed element.
   469         */
   470         virtual CSenElement* RemoveElement(const TDesC8& aLocalName) = 0;
   471 
   472         /**
   473         * Replaces a child element with another element.
   474         * Element's local name and namespace URI will be used to check
   475         * whether or not that element matches with any existing child.
   476         * If no matching child element is found this method will add a 
   477         * new child element.
   478         *
   479         * @since Series60 3.0
   480         * @param aElement:  the element to be added. Ownership is transferred.
   481         * @return The old element. May be NULL if nothing was replaced
   482         *           (if element was not found from the childs).
   483         *           The caller TAKES OWNERSHIP of the old element.
   484         */
   485         virtual CSenElement* ReplaceElementL(CSenElement& aElement) = 0;
   486 
   487         /**
   488         * Gets the element as an XML buffer. Buffer will 
   489         * contain all the child elements.
   490         * @since Series60 3.0
   491         * @return element as XML. Caller takes ownership.
   492         */
   493         virtual HBufC8* AsXmlL() = 0;
   494         
   495         /**
   496         * Gets the element as an unicode (UCS2) XML buffer.
   497         * Buffer will contain all the child elements.
   498         * @since Series60 3.0
   499         * @return element as XML. Caller takes ownership.
   500         */
   501         virtual HBufC* AsXmlUnicodeL() = 0;
   502 
   503         /**
   504         * Element writes itself to a write stream using UTF-8 
   505         * character-set encoding.
   506         * @since Series60 3.0
   507         * @param aWriteStream The stream to write to.
   508         */
   509         virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;
   510 
   511         /**
   512         * Element writes its namespaces to a write stream 
   513         * using UTF-8 character-set encoding.
   514         * @since Series60 3.0
   515         * @param aWriteStream The stream to write to.
   516         */
   517         virtual void WriteNamespacesToL(RWriteStream& aWriteStream) = 0;
   518 
   519         /**
   520         * Offers the M-class interface pointer to this XML 
   521         * element.
   522         * @since Series60 3.0
   523         * @return the current object as element. Ownership is NOT transferred.
   524         */
   525         virtual MSenElement* AsElement() = 0;
   526 
   527         /**
   528         * Copies content from given element to this element appending to the 
   529         * existing content if there is any.
   530         * @since Series60 3.0
   531         * @param aSource The source element.
   532         */
   533         virtual void CopyFromL(CSenElement& aSource) = 0;
   534 
   535         /**
   536         * (Re-) Set the name and namespace of this Element. The element will be
   537         * given the localName in the the given namespace. A prefix will be
   538         * computed from the qualified name.
   539         * This method should be used with care and is mainly intended for
   540         * protected use in implementations.
   541         * @since Series60 3.0
   542         * @param aNamespaceURI The new namespace URI.
   543         * @param aLocalName The new local name.
   544         * @param aQName The new qualified name.
   545         */
   546         virtual void Set(const TDesC8& aNamespaceURI, const TDesC8& aLocalName, const TDesC8& aQName) = 0;
   547 
   548         /**
   549         * Adds new attributes to the element.
   550         * @since Series60 3.0
   551         * @param aAttrs:    the array of attributes.
   552         */
   553         virtual void AddAttributesL(const RAttributeArray& apAttrs) = 0;
   554     };
   555 
   556 #endif //SEN_ELEMENT_H
   557 
   558 // End of File
   559