1 xmlengattr.h

     1 /*

     2 * Copyright (c) 2004-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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:       Attribute node functions

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 

    24 #ifndef XMLENGINE_ATTR_H_INCLUDED

    25 #define XMLENGINE_ATTR_H_INCLUDED

    26 

    27 #include "xmlengnode.h"

    28 

    29 /**

    30  * Instance of TXmlEngAttr class represents an XML attribute in the DOM tree.

    31  * 

    32  * Is a storage attributes properties. Implements DOM action for it.

    33  * 

    34  * @lib XmlEngineDOM.lib

    35  * @since S60 v3.1

    36  */

    37 class TXmlEngAttr : public TXmlEngNode

    38 {

    39   public:

    40     /**

    41      * Default constructor

    42      *

    43      * @since S60 v3.1

    44      */

    45     inline TXmlEngAttr();

    46 

    47 

    48     /**

    49      * Clones attribute node

    50      *

    51      * @since S60 v3.1

    52      * @return A copy of the attribute with its value

    53      *

    54      * @note Namespace of the attribute is reset; use 

    55      * TXmlEngNode::CopyToL(TXmlEngNode), which finds appropriate or creates

    56      * new namespace declaration on the new parent node (argument should be

    57      * an TXmlEngElement handle)

    58      *

    59      * @see CopyToL(TXmlEngNode)

    60      */

    61     IMPORT_C TXmlEngAttr CopyL() const;

    62 

    63     /**

    64      * Get owner element

    65      *

    66      * @since S60 v3.1

    67      * @return TXmlEngElement that contains the attribute

    68      *

    69      * Same as TXmlEngNode::ParentNode() but returns TXmlEngElement 

    70      * instead of TXmlEngNode.

    71      *

    72      * @note Copies of attributes [TXmlEngAttr::CopyL()] and newly created 

    73      * attribute nodes [RXmlEngDocument::CreateAttributeL(..)] do not have 

    74      * parent element until they are attached to some element.

    75      */

    76     IMPORT_C const TXmlEngElement OwnerElement() const;

    77 

    78     /**

    79      * Check attribute name.

    80      *

    81      * @since S60 v3.1

    82      * @return Local name of the attribute

    83      *

    84      * @note Equal to TXmlEngNode::Name(), but works faster.

    85      *

    86      * Never call this on NULL object!

    87      * @see TXmlEngNode::Name()

    88      */

    89     IMPORT_C TPtrC8 Name() const;

    90 

    91     /**

    92      * Get element value.

    93      *

    94      * @since S60 v3.1

    95      * @return Attribute's contents

    96      *

    97      * @note For values consisting of more then one TXmlEngTextNode node 

    98      * (as attribute's child) returns only the begining of the value; 

    99      * this happens when the value is represented by list of TXmlEngTextNode

   100      * and TXmlEngEntityReference nodes.

   101      * 

   102      * @see IsSimpleContents(), WholeValueCopyL()

   103      */

   104     IMPORT_C TPtrC8 Value() const; 

   105 

   106     /**

   107      * Get copy of attribute content

   108      *

   109      * @since S60 v3.1

   110      * @return Complex value of the attribute,

   111      *     probably consisting of text nodes and entity references

   112      *

   113      * Since the value may be composed from a set of TXmlEngTextNode

   114      * and EntityRefernce nodes, the returned result is newly allocated 

   115      * string, which should be freed by caller.

   116      * 

   117      * <B style="color: red">BE SURE TO FREE THE RESULT STRING!!!</B>

   118      *

   119      * Example usage of the API:

   120      * @code

   121      *    RBuf8 value;

   122 	 *    attr.WholeValueCopyL(value);

   123      *    ...

   124      *    value.Close();

   125      * @endcode

   126      *

   127      * @see TXmlEngAttr::Value(), TXmlEngNode::Value(),

   128      * TXmlEngNode::IsSimpleTextContents(), 

   129      * TXmlEngNode::WholeTextContentsCopyL()

   130      *

   131      * @note In most cases using Value() is enough (and it needs no memory allocation).

   132      *     Use IsSimpleTextContents() if there doubts can Value() be used or not safely.

   133      */

   134     IMPORT_C void WholeValueCopyL(RBuf8& aBuffer) const;

   135 

   136     /**

   137      * Sets new value of the attribute. Provided new value will be escaped 

   138      * as needed.

   139      *

   140 	 * @ since S60 v3.1

   141      * @param aNewValue A string value for the attribute

   142      *

   143      * The new value should not contain entity references. 

   144      * Entity references are not expanded, but used as text, because 

   145      * the ampersand (&) character of reference is escaped.

   146      *

   147      * @see SetEscapedValueL(const TDesC8&)

   148      */

   149     IMPORT_C void SetValueL(const TDesC8& aNewValue);

   150 

   151     /**

   152      * Sets new value from escaped XML character data that may contain 

   153      * entity references.

   154      *

   155      * The value as if it is an escaped contents from XML file.

   156      * If the value contains entity references, then the resulting

   157      * content of the attribute is a list of TXmlEngTextNode 

   158      * and TXmlEngEntityRefeerence nodes.

   159      * Predefined entities are converted into characters they represent.

   160      * 

   161      * @param aNewValue is a new attribute value

   162      * @since S60 v3.1

   163      *

   164      * @see TXmlEngAttr::SetValueL(const TDesC8&)

   165      */

   166     IMPORT_C void SetEscapedValueL(const TDesC8& aNewValue);

   167 

   168 	/**

   169 	 * Sets new attribute value exactly as presented in the string.

   170 	 *

   171 	 * Predefined entities are not converted into characters they represent.

   172 	 *

   173      * @param aNewValue is a new attribute value 

   174      * @since S60 v3.2

   175      *

   176      * @see TXmlEngAttr::SetValueL(const TDesC8&)

   177      */

   178 	IMPORT_C void SetValueNoEncL(const TDesC8& aNewValue );

   179 

   180 protected:

   181     /**

   182      * Constructor

   183      *

   184      * @since S60 v3.1

   185      * @param aInternal attribute pointer

   186      */

   187     inline TXmlEngAttr(void* aInternal);

   188 };

   189 

   190 #include "xmlengattr.inl"

   191 

   192 #endif /* XMLENGINE_ATTR_H_INCLUDED */