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