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 filter

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef simplefilter_H

    22 #define simplefilter_H

    23 

    24 #include <e32std.h>

    25 #include "simplecommon.h"

    26 #include "msimplefilterdocument.h"

    27 #include "simplebasedocument.h"

    28 

    29 // FORWARD DECLARATION

    30 class CSimpleNamespace;

    31 

    32 

    33 /**

    34  *  CSimpleFilter

    35  *

    36  *  SIMPLE Engine core.

    37  *

    38  *  @lib simplexmlutils

    39  *  @since S60 3.2

    40  */

    41 

    42 class CSimpleFilter : public CSimpleBaseDocument, public MSimpleFilterDocument

    43     {

    44 

    45 public:

    46 

    47     /**

    48      * Two-phased constructor.

    49      * @since S60 3.2

    50      * @return CSimpleFilter

    51      */

    52     static CSimpleFilter* NewL( );

    53 

    54     /**

    55      * Two-phased constructor.

    56      * @since S60 3.2

    57      * @param aXml XML document

    58      * @return CSimpleFilter

    59      */

    60     static CSimpleFilter* NewL( const TDesC8& aXml );

    61 

    62     /**

    63      * Destructor.

    64      */

    65     virtual ~CSimpleFilter();

    66     

    67     /**

    68      * Validates root element name

    69      * Leaves if not valid

    70      * @param aName element name

    71      */

    72     void ValidateXmlL( const TDesC8& aName );

    73 

    74 // from base class MSimpleFilterDocument

    75 

    76 

    77     /**

    78      * From MSimpleFilterDocument

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

    80      *

    81      * @since S60 3.2

    82      * @return default namespace URI

    83      */

    84     TPtrC8 DefaultNamespace();

    85 

    86     /**

    87      * From MSimpleFilterDocument

    88      * Add new newspace

    89      *

    90      * @since S60 3.2

    91      * @param aPrefix:  Namespace prefix

    92      * @param aUri: Namespace URI

    93      */

    94     void AddNamespaceL( const TDesC8& aPrefix,

    95                         const TDesC8& aUri);

    96 

    97     /**

    98      * From MSimpleFilterDocument

    99      * Gets namespaces of this element in an array.

   100      *

   101      * @since S60 3.2

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

   103      *         no namespaces.

   104      */

   105     RPointerArray<MSimpleNamespace>& NamespacesL();

   106 

   107     /**

   108      * Externalize the document into write stream.

   109      *

   110      * @since S60 3.2

   111      * @param aStream write stream

   112      */

   113     void ExternalizeL( RWriteStream& aStream );

   114 

   115 // from base class MSimpleEntity

   116 

   117     /**

   118      * Destroy this element entity and all its descendant elements

   119      *

   120      * @since S60 3.2

   121      */

   122     void Close();

   123 

   124     /**

   125      * Getter for Element's local name.

   126      * LocalName and Namespace are given in factory method.

   127      * @return KNullDesC if not set

   128      */

   129     const TDesC8& LocalName();

   130 

   131     /**

   132      * Getter for Element's default namespace.

   133      *

   134      * @since S60 3.2

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

   136      *        NULL if not set. Ownership is transferred.

   137      */

   138     MSimpleNamespace* DefNamespaceL();

   139 

   140     /**

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

   142      *

   143      * @since S60 3.2

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

   145      */

   146     TBool HasContent();

   147 

   148     /**

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

   150      *

   151      * @since S60 3.2

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

   153      */

   154     HBufC* ContentUnicodeL();

   155 

   156     /**

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

   158      *

   159      * @since S60 3.2

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

   161      */

   162     void SetContentUnicodeL(const TDesC& aContent);

   163 

   164     /**

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

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

   167      *                          or empty array if no matching found.

   168      *                          Any modifications made on the returned items

   169      *                          modify the real childs too.

   170      * @return KErrNone     ok

   171      *         KErrNotFound No child elements exist.

   172      */

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

   174 

   175     /**

   176      * Gets the value of the given attribute.

   177      *

   178      * @since S60 3.2

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

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

   181      *        TRANSFERRED.

   182      */

   183     HBufC* AttrValueLC( const TDesC8& aName );

   184 

   185     /**

   186      * Gets the value of the given attribute.

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

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

   189      *         NOT TRANSFERRED.

   190      */

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

   192 

   193     /**

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

   195      * the value of the attribute will be replaced.

   196      *

   197      * @since S60 3.2

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

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

   200      */

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

   202 

   203     /**

   204      * From MSimpleElement

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

   206      *

   207      * @since S60 3.2

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

   209      *                       or empty array if no matching found.

   210      * @return KErrNone ok

   211      *         KErrNotFound No child elements exist.

   212      */

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

   214 

   215     /**

   216      * Gets the parent element of this element.

   217      *

   218      * @since S60 3.2

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

   220      *        Ownership IS TRANSFERRED to the caller.

   221      */

   222     MSimpleElement* SimpleParentL();

   223 

   224     /**

   225      * Detach the element from its parent.

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

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

   228      * copy those namespace declarations to this element.

   229      * Leaves with KErrNotFound if parent was not set and

   230      * nothing to detach.

   231      *

   232      * @since S60 3.2

   233      */

   234     void DetachSimpleL();

   235 

   236     /**

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

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

   239      *

   240      * @since S60 3.2

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

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

   243      * @return the added Element

   244      * Leave codes:

   245      *      KErrSenInvalidCharacters if aLocalName contains illegal characters.

   246      *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

   247      */

   248     MSimpleElement* AddSimpleElementL(

   249         const TDesC8& aNsUri,

   250         const TDesC8& aLocalName);

   251 

   252     /**

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

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

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

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

   257      * namespace.

   258      *

   259      * @since S60 3.2

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

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

   262      *  Leave codes:

   263      *      KErrSenInvalidCharacters if aLocalName contains illegal characters.

   264      *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

   265      */

   266     MSimpleElement* AddSimpleElementL(

   267         const TDesC8& aLocalName );

   268 

   269     /**

   270      * Remove an element from the childs.

   271      *

   272      * @since S60 3.2

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

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

   275      */

   276     void RemoveSimpleElement(

   277         const TDesC8& aNsUri,

   278         const TDesC8& aLocalName);

   279 

   280 

   281 protected:

   282 

   283 

   284 private:

   285 

   286     /**

   287      * Two-phase constructor

   288      */

   289     void ConstructL(

   290         const TDesC8& aNsUri,

   291         const TDesC8& aLocalName );

   292 

   293     /**

   294      * Two-phase constructor

   295      */

   296     void ConstructL(

   297         const TDesC8& aXml );

   298 

   299     /**

   300      * constructor

   301      */

   302     CSimpleFilter();

   303 

   304 

   305 private:    // data

   306 

   307     };

   308 

   309 #endif      // simplefilter_H

   310 

   311 // End of File