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: Namespace node functions |
14 // |
15 * |
|
16 */ |
|
17 |
15 |
18 |
16 |
19 |
17 |
|
18 /** |
|
19 @file |
|
20 @publishedAll |
|
21 @released |
|
22 */ |
|
23 #ifndef XMLENGNAMESPACE_H |
|
24 #define XMLENGNAMESPACE_H |
20 |
25 |
21 |
26 #include <xml/dom/xmlengnode.h> |
22 |
|
23 |
|
24 #ifndef XMLENGINE_NAMESPACE_H_INCLUDED |
|
25 #define XMLENGINE_NAMESPACE_H_INCLUDED |
|
26 |
|
27 #include "xmlengnode.h" |
|
28 |
27 |
29 /** |
28 /** |
30 * Represents existing namespace declaration in DOM tree <b>OR</b> namespace node returned |
29 This class represents an existing namespace declaration in the DOM tree or a |
31 * in RXmlEngNodeSet as a result of some XPath expression. |
30 namespace node returned in RXmlEngNodeSet as a result of some XPath expression. |
32 * |
31 |
33 * All elements and attributes may have a namespace instance associated. |
32 All elements and attributes may have a namespace instance associated with them. |
34 * Once put in element, a namespace declaration (instance of TXmlEngNamespace) may be |
33 Once added to an element, a namespace declaration (instance of |
35 * referred to by all attributes and descentants of the element (unless |
34 TXmlEngNamespace) may be referred to by all attributes and descendants of the |
36 * prefix that this namespace-to-prefix binding uses is overriden somewhere below in the document tree) |
35 element (unless the prefix that this namespace-to-prefix binding uses is |
37 * |
36 overriden somewhere below in the document tree). |
38 * <b>General rules of namespace handling:</b> |
37 |
39 * |
38 General rules for namespace handling: |
40 * - <b>NULL</b> prefix in namespace node means NO PREFIX. ""(empty string '\\0') can be used for specifying |
39 |
41 * absense of prefix when setting it, however <b>NULL</b> will be stored and returned. |
40 - A NULL prefix in the namespace node means NO PREFIX. An empty string "" can |
42 * |
41 be used to specify the absence of a prefix when setting it, however, NULL will |
43 * - <b>NULL</b> value of namespace URI is legal only with <b>NULL</b> prefix and only met in |
42 be stored and returned. |
44 * undeclaration of namespace (<i>xmlns=""</i>). <b>""</b> (empty string) can be used too, however it |
43 |
45 * will be returned as <b>NULL</b>. |
44 - A NULL value for a namespace URI is legal only with a NULL prefix and is only |
46 * |
45 used in the undeclaration of a namespace (@c xmlns="" ). An empty string "" |
47 * - <b>NULL</b> or <b>""</b> namespace <b>URI</b> with non-<b>NULL</b> prefix is illegal acording to the XML specification. |
46 can be used too, however, it will be returned as NULL. |
48 * |
47 |
49 * - Namespace of a element is <b>default</b> if it is associated with some namespace declaration with <b>NULL</b> prefix. |
48 - A NULL or empty string namespace URI with a non-NULL prefix is illegal |
50 * |
49 acording to the XML specification. |
51 * - Elements are never associated with namespace undeclarations (<b>xmlns=""</b>), instead, such elements have no |
50 |
52 * namespace declaration referred to. |
51 - The namespace of an element is a default namespace if it has a NULL prefix. |
53 * |
52 |
54 * - Attributes do not have <i>default</i> namespace. Even if it is effective at element scope, |
53 - Elements with namespace undeclarations (@c xmlns="" ), have no namespace and |
55 * default namespace declaration is not applied to element's attributes (according to the XML specification) |
54 are treated as local names. |
56 * |
55 |
57 * - Namespace of a node (element or attribute) is <b>undefined</b> if no namespace declaration is |
56 - Attributes do not have a default namespace. Even if a namespace is applied at |
58 * associated with it. |
57 element scope, the default namespace declaration is not applied to the |
59 * |
58 element's attributes (according to the XML specification). |
60 * - Node with <i>undefined</i> namespace is serialized as having no prefix. In general, |
59 |
61 * DOM API handles the complexity of namespace declaration handling and creates neccessary |
60 - The namespace of a node (element or attribute) is undefined if no namespace |
62 * namespace declarations and undeclares default namespace. However, some node-creation methods (e.g. TXmlEngElement::AddNewElementL()) |
61 declaration is associated with it. |
63 * do not ensure that created node with undefined namespace (thus, without a prefix) will |
62 |
64 * actually treated after serialization as having some <i>default</i> namespace |
63 - A node with an undefined namespace is serialized as having no prefix. In |
65 * |
64 general, the DOM API handles the complexity of namespace declaration handling, |
66 * @note |
65 creating neccessary namespace declarations and undeclaring default namespaces. |
67 * Namespace nodes that are result of XPath expression have following restrictions: |
66 However, some node-creation methods (e.g. TXmlEngElement::AddNewElementL()) do |
68 * - they cannot be used as namespace definitions, because they are not part of |
67 not ensure that a node created with an undefined namespace (i.e. without a |
69 * the DOM tree, but copies of existing namespace definitions. |
68 prefix) will be treated after serialization as having the default namespace. |
70 * - namespace prefix is not available because it is not mandated by DOM Level 3 XPath module API, |
69 |
71 * so in returned copies of DOM tree, namespaces prefix strings are not preserved |
70 Note: |
72 * and Prefix() returns NULL. |
71 Namespace nodes that are the result of XPath expressions have following restrictions: |
73 * |
72 |
74 * @lib XmlEngineDOM.lib |
73 - They cannot be used as namespace definitions, because they are not part of |
75 * @since S60 v3.1 |
74 the DOM tree, but rather copies of existing namespace definitions. |
76 */ |
75 |
|
76 - The namespace prefix is not available because it is not mandated by the DOM |
|
77 Level 3 XPath API. So, in returned copies of the DOM tree, namespace prefix |
|
78 strings are not preserved and Prefix() returns NULL. |
|
79 */ |
77 class TXmlEngNamespace: public TXmlEngNode |
80 class TXmlEngNamespace: public TXmlEngNode |
78 { |
81 { |
|
82 friend class TXmlEngElement; |
|
83 friend class TXmlEngNode; |
|
84 |
79 public: |
85 public: |
80 /** |
86 /** Default constructor */ |
81 * Default constructor |
|
82 * |
|
83 * @since S60 v3.1 |
|
84 */ |
|
85 inline TXmlEngNamespace(); |
87 inline TXmlEngNamespace(); |
86 |
88 |
87 /** |
89 /** |
88 /** |
90 Gets the namespace URI |
89 * Get namespace URI |
91 @return Namespace URI string or an empty string if the namespace is either |
90 * |
92 NULL or undeclared (@c xmlns="" ) |
91 * @since S60 v3.1 |
93 */ |
92 * @return Namespace URI string |
|
93 * @note "" is never returned - it is replaced with NULL |
|
94 * |
|
95 * For TXmlEngNamespace(NULL) or namespace undeclaration (xmlns=""), which are |
|
96 * treatet as <i>undefined namespace</i> returns NULL, |
|
97 * otherwise result is not a NULL string and not a "" (empty string). |
|
98 */ |
|
99 IMPORT_C TPtrC8 Uri() const; |
94 IMPORT_C TPtrC8 Uri() const; |
100 |
95 |
101 /** |
96 /** |
102 * Get namespace prefix. |
97 Gets the namespace prefix. |
103 * |
98 @return The prefix bound in the namespace declaration or an empty string |
104 * @since S60 v3.1 |
99 when there is a default namespace or if no binding exists |
105 * @return prefix that is bound in the namespace declaration |
100 */ |
106 * or NULL string for default namespace or if no binding exist |
|
107 */ |
|
108 IMPORT_C TPtrC8 Prefix() const; |
101 IMPORT_C TPtrC8 Prefix() const; |
109 |
102 |
110 /** |
103 /** |
111 * Check if namespace is default. |
104 Check if the namespace is default. |
112 * |
105 @return ETrue if the namespace is default (no prefix), EFalse if the |
113 * @since S60 v3.1 |
106 namespace is not default (bound to prefix) or the namespace is NULL |
114 * @return Whether it is a definition of default namespace |
107 */ |
115 * TRUE -- is a default namespace (no prefix) |
|
116 * FALSE -- not a default namespace (bound to prefix) or empty TXmlEngNamespace(NULL) instance |
|
117 */ |
|
118 IMPORT_C TBool IsDefault() const; |
108 IMPORT_C TBool IsDefault() const; |
119 |
109 |
120 /** |
110 /** |
121 * Check if namespace is undefined |
111 Check if the namespace is undefined. A node's namespace is undefined if no |
122 * |
112 namespace declaration is associated with it. This is the same as |
123 * @since S60 v3.1 |
113 TXmlEngNode::IsNull(). |
124 * @return Whether the namespace is undefined |
114 @return ETrue if the namespace is undefined, EFalse otherwise |
125 * |
115 */ |
126 * A node's namespace is undefined if no namespace declaration associated with it. |
|
127 * @note Same as TXmlEngNode::IsNull() |
|
128 */ |
|
129 IMPORT_C TBool IsUndefined() const; |
116 IMPORT_C TBool IsUndefined() const; |
130 |
117 |
131 protected: |
118 protected: |
132 /** |
119 /** |
133 * Workaround to avoid misuse of TXmlEngNode::NamespaceUri() method, which should not be |
120 This method is inherited from TXmlEngNode. To prevent its use, no function body |
134 * applied to TXmlEngNamespace node. Since the name of the inherited method from TXmlEngNode |
121 has been supplied. The method Uri() should be used instead. |
135 * is too similar to TXmlEngNamespace::Uri(), NamespaceUri() is disabled for direct |
122 |
136 * use. |
123 @see Uri(). |
137 * If NamespaceUri() is called on the TXmlEngNamespace object that is downcasted to TXmlEngNode, then |
124 */ |
138 * NamespaceUri()'s result equals to result of Uri() method. |
|
139 * |
|
140 * @since S60 v3.1 |
|
141 * @return NULL |
|
142 */ |
|
143 inline TPtrC8 NamespaceUri(); |
125 inline TPtrC8 NamespaceUri(); |
144 |
126 |
145 protected: |
127 protected: |
146 /** |
128 /** |
147 * Constructor |
129 Constructor |
148 * |
130 @param aPtr Namespace pointer |
149 * @since S60 v3.1 |
131 */ |
150 * @param aPtr Namespace pointer |
|
151 */ |
|
152 inline TXmlEngNamespace(void* aPtr); |
132 inline TXmlEngNamespace(void* aPtr); |
153 |
|
154 friend class TXmlEngElement; |
|
155 friend class TXmlEngNode; |
|
156 }; |
133 }; |
157 |
134 |
158 #include "xmlengnamespace.inl" |
135 #include <xml/dom/xmlengnamespace.inl> |
159 |
136 |
160 #endif /* XMLENGINE_NAMESPACE_H_INCLUDED */ |
137 #endif /* XMLENGNAMESPACE_H */ |
161 |
138 |