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 metadata

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef simplemeta_H

    22 #define simplemeta_H

    23 

    24 #include <e32std.h>

    25 #include "simplecommon.h"

    26 #include "msimplemeta.h"

    27 #include "simplebasedocument.h"

    28 

    29 // FORWARD DECLARATION

    30 class CSimpleNamespace;

    31 

    32 

    33 /**

    34  *  CSimpleMeta

    35  *

    36  *  SIMPLE Engine core.

    37  *

    38  *  @lib simplexmlutils

    39  *  @since S60 v3.1

    40  */

    41 

    42 class CSimpleMeta : public CSimpleBaseDocument, public MSimpleMeta

    43     {

    44 

    45 public:

    46 

    47 

    48     /**

    49      * Two-phased constructor.

    50      * @since S60 v3.1

    51      * @param aXml XML document

    52      * @return CSimpleMeta

    53      */

    54     static CSimpleMeta* NewL( const TDesC8& aXml );

    55 

    56     /**

    57      * Destructor.

    58      */

    59     virtual ~CSimpleMeta();

    60 

    61     /**

    62      * Validates root element name

    63      * Leaves if not valid

    64      * @param aName element name

    65      */

    66     void ValidateXmlL( const TDesC8& aName );

    67 

    68 // from base class MSimpleMeta

    69 

    70 

    71     /**

    72      * From MSimpleMeta

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

    74      *

    75      * @since S60 v3.1

    76      * @return default namespace URI

    77      */

    78     TPtrC8 DefaultNamespace();

    79 

    80     /**

    81      * From MSimpleMeta

    82      * Add new newspace

    83      *

    84      * @since S60 v3.1

    85      * @param aPrefix:  Namespace prefix

    86      * @param aUri: Namespace URI

    87      */

    88     void AddNamespaceL( const TDesC8& aPrefix,

    89                         const TDesC8& aUri);

    90 

    91     /**

    92      * From MSimpleMeta

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

    94      *

    95      * @since S60 v3.1

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

    97      *         no namespaces.

    98      */

    99     RPointerArray<MSimpleNamespace>& NamespacesL();

   100 

   101     /**

   102      * Externalize the document into write stream.

   103      *

   104      * @since S60 v3.1

   105      * @param aStream write stream

   106      */

   107     void ExternalizeL( RWriteStream& aStream );

   108 

   109 // from base class MSimpleEntity

   110 

   111     /**

   112      * Destroy this element entity and all its descendant elements

   113      *

   114      * @since S60 v3.1

   115      */

   116     void Close();

   117 

   118     /**

   119      * Getter for Element's local name.

   120      * LocalName and Namespace are given in factory method.

   121      * @return KNullDesC if not set

   122      */

   123     const TDesC8& LocalName();

   124 

   125     /**

   126      * Getter for Element's default namespace.

   127      *

   128      * @since S60 v3.1

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

   130      *        NULL if not set. Ownership is transferred.

   131      */

   132     MSimpleNamespace* DefNamespaceL();

   133 

   134     /**

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

   136      *

   137      * @since S60 v3.1

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

   139      */

   140     TBool HasContent();

   141 

   142     /**

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

   144      *

   145      * @since S60 v3.1

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

   147      */

   148     HBufC* ContentUnicodeL();

   149 

   150     /**

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

   152      *

   153      * @since S60 v3.1

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

   155      */

   156     void SetContentUnicodeL(const TDesC& aContent);

   157 

   158 

   159     /**

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

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

   162      *                          or empty array if no matching found.

   163      *                          Any modifications made on the returned items

   164      *                          modify the real childs too.

   165      * @return KErrNone     ok

   166      *         KErrNotFound No child elements exist.

   167      */

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

   169 

   170     /**

   171      * Gets the value of the given attribute.

   172      *

   173      * @since Series60 3.1

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

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

   176      *        TRANSFERRED.

   177      */

   178     HBufC* AttrValueLC( const TDesC8& aName );

   179 

   180     /**

   181      * Gets the value of the given attribute.

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

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

   184      *         NOT TRANSFERRED.

   185      */

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

   187 

   188     /**

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

   190      * the value of the attribute will be replaced.

   191      *

   192      * @since Series60 3.1

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

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

   195      */

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

   197 

   198     /**

   199      * From MSimpleElement

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

   201      *

   202      * @since Series60 3.1

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

   204      *                       or empty array if no matching found.

   205      * @return KErrNone ok

   206      *         KErrNotFound No child elements exist.

   207      */

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

   209 

   210     /**

   211      * Gets the parent element of this element.

   212      *

   213      * @since Series60 3.1

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

   215      *        Ownership IS TRANSFERRED to the caller.

   216      */

   217     MSimpleElement* SimpleParentL();

   218 

   219     /**

   220      * Detach the element from its parent.

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

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

   223      * copy those namespace declarations to this element.

   224      * Leaves with KErrNotFound if parent was not set and

   225      * nothing to detach.

   226      *

   227      * @since Series60 3.1

   228      */

   229     void DetachSimpleL();

   230 

   231     /**

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

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

   234      *

   235      * @since Series60 3.1

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

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

   238      * @return the added Element

   239      * Leave codes:

   240      *      KErrSenInvalidCharacters if aLocalName contains illegal characters.

   241      *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

   242      */

   243     MSimpleElement* AddSimpleElementL(

   244         const TDesC8& aNsUri,

   245         const TDesC8& aLocalName);

   246 

   247     /**

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

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

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

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

   252      * namespace.

   253      *

   254      * @since Series60 3.1

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

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

   257      *  Leave codes:

   258      *      KErrSenInvalidCharacters if aLocalName contains illegal characters.

   259      *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

   260      */

   261     MSimpleElement* AddSimpleElementL(

   262         const TDesC8& aLocalName );

   263 

   264     /**

   265      * Remove an element from the childs.

   266      *

   267      * @since Series60 3.1

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

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

   270      */

   271     void RemoveSimpleElement(

   272         const TDesC8& aNsUri,

   273         const TDesC8& aLocalName);

   274 

   275 private:

   276 

   277     /**

   278      * Two-phase constructor

   279      */

   280     void ConstructL(

   281         const TDesC8& aNsUri,

   282         const TDesC8& aLocalName );

   283 

   284     /**

   285      * Two-phase constructor

   286      */

   287     void ConstructL(

   288         const TDesC8& aXml );

   289 

   290     /**

   291      * constructor

   292      */

   293     CSimpleMeta();

   294 

   295     };

   296 

   297 #endif      // simplemeta_H

   298 

   299 // End of File