|
1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Attribute node functions |
|
15 // |
|
16 |
|
17 |
|
18 |
|
19 /** |
|
20 @file |
|
21 @publishedAll |
|
22 @released |
|
23 */ |
|
24 #ifndef XMLENGATTR_H |
|
25 #define XMLENGATTR_H |
|
26 |
|
27 #include <xml/dom/xmlengnode.h> |
|
28 |
|
29 /** |
|
30 This class represents a XML attribute in the DOM tree. |
|
31 */ |
|
32 class TXmlEngAttr : public TXmlEngNode |
|
33 { |
|
34 public: |
|
35 /** Default constructor */ |
|
36 inline TXmlEngAttr(); |
|
37 |
|
38 /** |
|
39 Clones attribute node. |
|
40 |
|
41 Note: Resets the namespace of the attribute. To avoid this, use |
|
42 TXmlEngNode::CopyToL(), which finds an appropriate or creates |
|
43 a new namespace declaration on the new parent node (argument should be |
|
44 an TXmlEngElement handle) |
|
45 |
|
46 @see TXmlEngNode::CopyToL() |
|
47 |
|
48 @return A copy of this attribute |
|
49 @leave - One of the system-wide error codes |
|
50 */ |
|
51 IMPORT_C TXmlEngAttr CopyL() const; |
|
52 |
|
53 /** |
|
54 Get the owner element. |
|
55 |
|
56 Same as TXmlEngNode::ParentNode() but returns TXmlEngElement |
|
57 instead of TXmlEngNode. |
|
58 |
|
59 Note: Copies of attributes [TXmlEngAttr::CopyL()] and newly created |
|
60 attribute nodes [RXmlEngDocument::CreateAttributeL()] do not have |
|
61 parent element until they are attached to some element. |
|
62 |
|
63 If there is no owning element, a NULL element is returned. |
|
64 |
|
65 @return TXmlEngElement that contains the attribute |
|
66 */ |
|
67 IMPORT_C const TXmlEngElement OwnerElement() const; |
|
68 |
|
69 /** |
|
70 Get the attribute name. Equal to TXmlEngNode::Name(), but works faster. |
|
71 |
|
72 @return Local name of the attribute |
|
73 @pre Node must not be NULL |
|
74 @see TXmlEngNode::Name() |
|
75 */ |
|
76 IMPORT_C TPtrC8 Name() const; |
|
77 |
|
78 /** |
|
79 Get the attribute's value. If the value consists of more than one TXmlEngTextNode, |
|
80 as children of the attribute, only the beginning of the value is returned. This |
|
81 happens when the value is represented by list of TXmlEngTextNode and |
|
82 TXmlEngEntityReference nodes. |
|
83 |
|
84 @return The attribute's value |
|
85 @see IsSimpleContents(), WholeValueCopyL() |
|
86 */ |
|
87 IMPORT_C TPtrC8 Value() const; |
|
88 |
|
89 /** |
|
90 Get a copy of attribute content. Since the value may be composed from a set of |
|
91 TXmlEngTextNode and TXmlEngEntityReference nodes, the returned result is a newly allocated |
|
92 RBuf, which should be closed by the caller. |
|
93 |
|
94 Example usage of the API: |
|
95 @code |
|
96 RBuf8 value; |
|
97 attr.WholeValueCopyL(value); |
|
98 ... |
|
99 value.Close(); |
|
100 @endcode |
|
101 |
|
102 In most cases using Value() is enough (and it needs no memory allocation). |
|
103 Use IsSimpleTextContents() if there are doubts whether Value() can be used safely. |
|
104 |
|
105 @return Complex value of the attribute, probably consisting of text nodes and entity references |
|
106 @leave KXmlEngErrNullNode Node is NULL |
|
107 @leave - One of the system-wide error codes |
|
108 @see TXmlEngAttr::Value() |
|
109 @see TXmlEngNode::Value() |
|
110 @see TXmlEngNode::IsSimpleTextContents() |
|
111 @see TXmlEngNode::WholeTextContentsCopyL() |
|
112 */ |
|
113 IMPORT_C void WholeValueCopyL(RBuf8& aBuffer) const; |
|
114 |
|
115 /** |
|
116 Sets the value of the attribute. The new value should not contain entity |
|
117 references. Entity references are not expanded, but used as text, thus |
|
118 the string "abc & def" is copied directly as "abc & def" without |
|
119 expansion. |
|
120 |
|
121 @param aNewValue A string value for the attribute |
|
122 @leave KXmlEngErrNullNode Node is NULL |
|
123 @leave - One of the system-wide error codes |
|
124 @see SetEscapedValueL(const TDesC8&) |
|
125 */ |
|
126 IMPORT_C void SetValueL(const TDesC8& aNewValue); |
|
127 |
|
128 /** |
|
129 Sets the value of the attribute from escaped XML character data that may contain |
|
130 entity references. |
|
131 |
|
132 If the value contains entity references, then the resulting |
|
133 content of the attribute is a list of TXmlEngTextNode |
|
134 and TXmlEngEntityReference nodes. |
|
135 Predefined entities are converted into characters they represent. |
|
136 |
|
137 @param aNewValue is a new attribute value |
|
138 @leave KXmlEngErrNullNode Node is NULL |
|
139 @leave - One of the system-wide error codes |
|
140 @see TXmlEngAttr::SetValueL(const TDesC8&) |
|
141 */ |
|
142 IMPORT_C void SetEscapedValueL(const TDesC8& aNewValue); |
|
143 |
|
144 /** |
|
145 Sets new attribute value exactly as presented in the string. |
|
146 Predefined entities are not converted into characters they represent. |
|
147 |
|
148 @param aNewValue is the new attribute value |
|
149 @leave KXmlEngErrNullNode Node is NULL |
|
150 @leave - One of the system-wide error codes |
|
151 @see TXmlEngAttr::SetValueL(const TDesC8&) |
|
152 */ |
|
153 IMPORT_C void SetValueNoEncL(const TDesC8& aNewValue ); |
|
154 |
|
155 protected: |
|
156 /** |
|
157 Constructor |
|
158 @param aInternal attribute pointer |
|
159 */ |
|
160 inline TXmlEngAttr(void* aInternal); |
|
161 }; |
|
162 |
|
163 #include <xml/dom/xmlengattr.inl> |
|
164 |
|
165 #endif /* XMLENGATTR_H */ |
|
166 |