1.1 --- a/epoc32/include/xml/dom/xmlengnamespace.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/xml/dom/xmlengnamespace.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,161 +1,138 @@
1.4 -/*
1.5 -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 -* All rights reserved.
1.7 -* This component and the accompanying materials are made available
1.8 -* 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
1.9 -* which accompanies this distribution, and is available
1.10 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 -*
1.12 -* Initial Contributors:
1.13 -* Nokia Corporation - initial contribution.
1.14 -*
1.15 -* Contributors:
1.16 -*
1.17 -* Description: Namespace node functions
1.18 -*
1.19 -*/
1.20 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.21 +// All rights reserved.
1.22 +// This component and the accompanying materials are made available
1.23 +// under the terms of "Eclipse Public License v1.0"
1.24 +// which accompanies this distribution, and is available
1.25 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.26 +//
1.27 +// Initial Contributors:
1.28 +// Nokia Corporation - initial contribution.
1.29 +//
1.30 +// Contributors:
1.31 +//
1.32 +// Description:
1.33 +//
1.34
1.35
1.36
1.37 -
1.38 -
1.39 -
1.40 -
1.41 -#ifndef XMLENGINE_NAMESPACE_H_INCLUDED
1.42 -#define XMLENGINE_NAMESPACE_H_INCLUDED
1.43 -
1.44 -#include "xmlengnode.h"
1.45 -
1.46 /**
1.47 - * Represents existing namespace declaration in DOM tree <b>OR</b> namespace node returned
1.48 - * in RXmlEngNodeSet as a result of some XPath expression.
1.49 - *
1.50 - * All elements and attributes may have a namespace instance associated.
1.51 - * Once put in element, a namespace declaration (instance of TXmlEngNamespace) may be
1.52 - * referred to by all attributes and descentants of the element (unless
1.53 - * prefix that this namespace-to-prefix binding uses is overriden somewhere below in the document tree)
1.54 - *
1.55 - * <b>General rules of namespace handling:</b>
1.56 - *
1.57 - * - <b>NULL</b> prefix in namespace node means NO PREFIX. ""(empty string '\\0') can be used for specifying
1.58 - * absense of prefix when setting it, however <b>NULL</b> will be stored and returned.
1.59 - *
1.60 - * - <b>NULL</b> value of namespace URI is legal only with <b>NULL</b> prefix and only met in
1.61 - * undeclaration of namespace (<i>xmlns=""</i>). <b>""</b> (empty string) can be used too, however it
1.62 - * will be returned as <b>NULL</b>.
1.63 - *
1.64 - * - <b>NULL</b> or <b>""</b> namespace <b>URI</b> with non-<b>NULL</b> prefix is illegal acording to the XML specification.
1.65 - *
1.66 - * - Namespace of a element is <b>default</b> if it is associated with some namespace declaration with <b>NULL</b> prefix.
1.67 - *
1.68 - * - Elements are never associated with namespace undeclarations (<b>xmlns=""</b>), instead, such elements have no
1.69 - * namespace declaration referred to.
1.70 - *
1.71 - * - Attributes do not have <i>default</i> namespace. Even if it is effective at element scope,
1.72 - * default namespace declaration is not applied to element's attributes (according to the XML specification)
1.73 - *
1.74 - * - Namespace of a node (element or attribute) is <b>undefined</b> if no namespace declaration is
1.75 - * associated with it.
1.76 - *
1.77 - * - Node with <i>undefined</i> namespace is serialized as having no prefix. In general,
1.78 - * DOM API handles the complexity of namespace declaration handling and creates neccessary
1.79 - * namespace declarations and undeclares default namespace. However, some node-creation methods (e.g. TXmlEngElement::AddNewElementL())
1.80 - * do not ensure that created node with undefined namespace (thus, without a prefix) will
1.81 - * actually treated after serialization as having some <i>default</i> namespace
1.82 - *
1.83 - * @note
1.84 - * Namespace nodes that are result of XPath expression have following restrictions:
1.85 - * - they cannot be used as namespace definitions, because they are not part of
1.86 - * the DOM tree, but copies of existing namespace definitions.
1.87 - * - namespace prefix is not available because it is not mandated by DOM Level 3 XPath module API,
1.88 - * so in returned copies of DOM tree, namespaces prefix strings are not preserved
1.89 - * and Prefix() returns NULL.
1.90 - *
1.91 - * @lib XmlEngineDOM.lib
1.92 - * @since S60 v3.1
1.93 - */
1.94 + @file
1.95 + @publishedAll
1.96 + @released
1.97 +*/
1.98 +#ifndef XMLENGNAMESPACE_H
1.99 +#define XMLENGNAMESPACE_H
1.100 +
1.101 +#include <xml/dom/xmlengnode.h>
1.102 +
1.103 +/**
1.104 +This class represents an existing namespace declaration in the DOM tree or a
1.105 +namespace node returned in RXmlEngNodeSet as a result of some XPath expression.
1.106 +
1.107 +All elements and attributes may have a namespace instance associated with them.
1.108 +Once added to an element, a namespace declaration (instance of
1.109 +TXmlEngNamespace) may be referred to by all attributes and descendants of the
1.110 +element (unless the prefix that this namespace-to-prefix binding uses is
1.111 +overriden somewhere below in the document tree).
1.112 +
1.113 +General rules for namespace handling:
1.114 +
1.115 +- A NULL prefix in the namespace node means NO PREFIX. An empty string "" can
1.116 +be used to specify the absence of a prefix when setting it, however, NULL will
1.117 +be stored and returned.
1.118 +
1.119 +- A NULL value for a namespace URI is legal only with a NULL prefix and is only
1.120 +used in the undeclaration of a namespace (@c xmlns="" ). An empty string ""
1.121 +can be used too, however, it will be returned as NULL.
1.122 +
1.123 +- A NULL or empty string namespace URI with a non-NULL prefix is illegal
1.124 +acording to the XML specification.
1.125 +
1.126 +- The namespace of an element is a default namespace if it has a NULL prefix.
1.127 +
1.128 +- Elements with namespace undeclarations (@c xmlns="" ), have no namespace and
1.129 +are treated as local names.
1.130 +
1.131 +- Attributes do not have a default namespace. Even if a namespace is applied at
1.132 +element scope, the default namespace declaration is not applied to the
1.133 +element's attributes (according to the XML specification).
1.134 +
1.135 +- The namespace of a node (element or attribute) is undefined if no namespace
1.136 +declaration is associated with it.
1.137 +
1.138 +- A node with an undefined namespace is serialized as having no prefix. In
1.139 +general, the DOM API handles the complexity of namespace declaration handling,
1.140 +creating neccessary namespace declarations and undeclaring default namespaces.
1.141 +However, some node-creation methods (e.g. TXmlEngElement::AddNewElementL()) do
1.142 +not ensure that a node created with an undefined namespace (i.e. without a
1.143 +prefix) will be treated after serialization as having the default namespace.
1.144 +
1.145 +Note:
1.146 +Namespace nodes that are the result of XPath expressions have following restrictions:
1.147 +
1.148 +- They cannot be used as namespace definitions, because they are not part of
1.149 +the DOM tree, but rather copies of existing namespace definitions.
1.150 +
1.151 +- The namespace prefix is not available because it is not mandated by the DOM
1.152 +Level 3 XPath API. So, in returned copies of the DOM tree, namespace prefix
1.153 +strings are not preserved and Prefix() returns NULL.
1.154 +*/
1.155 class TXmlEngNamespace: public TXmlEngNode
1.156 {
1.157 + friend class TXmlEngElement;
1.158 + friend class TXmlEngNode;
1.159 +
1.160 public:
1.161 - /**
1.162 - * Default constructor
1.163 - *
1.164 - * @since S60 v3.1
1.165 - */
1.166 + /** Default constructor */
1.167 inline TXmlEngNamespace();
1.168
1.169 /**
1.170 - /**
1.171 - * Get namespace URI
1.172 - *
1.173 - * @since S60 v3.1
1.174 - * @return Namespace URI string
1.175 - * @note "" is never returned - it is replaced with NULL
1.176 - *
1.177 - * For TXmlEngNamespace(NULL) or namespace undeclaration (xmlns=""), which are
1.178 - * treatet as <i>undefined namespace</i> returns NULL,
1.179 - * otherwise result is not a NULL string and not a "" (empty string).
1.180 - */
1.181 + Gets the namespace URI
1.182 + @return Namespace URI string or an empty string if the namespace is either
1.183 + NULL or undeclared (@c xmlns="" )
1.184 + */
1.185 IMPORT_C TPtrC8 Uri() const;
1.186
1.187 /**
1.188 - * Get namespace prefix.
1.189 - *
1.190 - * @since S60 v3.1
1.191 - * @return prefix that is bound in the namespace declaration
1.192 - * or NULL string for default namespace or if no binding exist
1.193 - */
1.194 + Gets the namespace prefix.
1.195 + @return The prefix bound in the namespace declaration or an empty string
1.196 + when there is a default namespace or if no binding exists
1.197 + */
1.198 IMPORT_C TPtrC8 Prefix() const;
1.199
1.200 /**
1.201 - * Check if namespace is default.
1.202 - *
1.203 - * @since S60 v3.1
1.204 - * @return Whether it is a definition of default namespace
1.205 - * TRUE -- is a default namespace (no prefix)
1.206 - * FALSE -- not a default namespace (bound to prefix) or empty TXmlEngNamespace(NULL) instance
1.207 - */
1.208 + Check if the namespace is default.
1.209 + @return ETrue if the namespace is default (no prefix), EFalse if the
1.210 + namespace is not default (bound to prefix) or the namespace is NULL
1.211 + */
1.212 IMPORT_C TBool IsDefault() const;
1.213
1.214 /**
1.215 - * Check if namespace is undefined
1.216 - *
1.217 - * @since S60 v3.1
1.218 - * @return Whether the namespace is undefined
1.219 - *
1.220 - * A node's namespace is undefined if no namespace declaration associated with it.
1.221 - * @note Same as TXmlEngNode::IsNull()
1.222 - */
1.223 + Check if the namespace is undefined. A node's namespace is undefined if no
1.224 + namespace declaration is associated with it. This is the same as
1.225 + TXmlEngNode::IsNull().
1.226 + @return ETrue if the namespace is undefined, EFalse otherwise
1.227 + */
1.228 IMPORT_C TBool IsUndefined() const;
1.229
1.230 protected:
1.231 /**
1.232 - * Workaround to avoid misuse of TXmlEngNode::NamespaceUri() method, which should not be
1.233 - * applied to TXmlEngNamespace node. Since the name of the inherited method from TXmlEngNode
1.234 - * is too similar to TXmlEngNamespace::Uri(), NamespaceUri() is disabled for direct
1.235 - * use.
1.236 - * If NamespaceUri() is called on the TXmlEngNamespace object that is downcasted to TXmlEngNode, then
1.237 - * NamespaceUri()'s result equals to result of Uri() method.
1.238 - *
1.239 - * @since S60 v3.1
1.240 - * @return NULL
1.241 - */
1.242 + This method is inherited from TXmlEngNode. To prevent its use, no function body
1.243 + has been supplied. The method Uri() should be used instead.
1.244 +
1.245 + @see Uri().
1.246 + */
1.247 inline TPtrC8 NamespaceUri();
1.248
1.249 protected:
1.250 /**
1.251 - * Constructor
1.252 - *
1.253 - * @since S60 v3.1
1.254 - * @param aPtr Namespace pointer
1.255 - */
1.256 + Constructor
1.257 + @param aPtr Namespace pointer
1.258 + */
1.259 inline TXmlEngNamespace(void* aPtr);
1.260 -
1.261 - friend class TXmlEngElement;
1.262 - friend class TXmlEngNode;
1.263 };
1.264
1.265 -#include "xmlengnamespace.inl"
1.266 +#include <xml/dom/xmlengnamespace.inl>
1.267
1.268 -#endif /* XMLENGINE_NAMESPACE_H_INCLUDED */
1.269 +#endif /* XMLENGNAMESPACE_H */
1.270