diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/xml/dom/xmlengnamespace.h --- a/epoc32/include/xml/dom/xmlengnamespace.h Wed Mar 31 12:27:01 2010 +0100 +++ b/epoc32/include/xml/dom/xmlengnamespace.h Wed Mar 31 12:33:34 2010 +0100 @@ -1,161 +1,138 @@ -/* -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). -* All rights reserved. -* This component and the accompanying materials are made available -* 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 -* which accompanies this distribution, and is available -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". -* -* Initial Contributors: -* Nokia Corporation - initial contribution. -* -* Contributors: -* -* Description: Namespace node functions -* -*/ +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// - - - - -#ifndef XMLENGINE_NAMESPACE_H_INCLUDED -#define XMLENGINE_NAMESPACE_H_INCLUDED - -#include "xmlengnode.h" - /** - * Represents existing namespace declaration in DOM tree OR namespace node returned - * in RXmlEngNodeSet as a result of some XPath expression. - * - * All elements and attributes may have a namespace instance associated. - * Once put in element, a namespace declaration (instance of TXmlEngNamespace) may be - * referred to by all attributes and descentants of the element (unless - * prefix that this namespace-to-prefix binding uses is overriden somewhere below in the document tree) - * - * General rules of namespace handling: - * - * - NULL prefix in namespace node means NO PREFIX. ""(empty string '\\0') can be used for specifying - * absense of prefix when setting it, however NULL will be stored and returned. - * - * - NULL value of namespace URI is legal only with NULL prefix and only met in - * undeclaration of namespace (xmlns=""). "" (empty string) can be used too, however it - * will be returned as NULL. - * - * - NULL or "" namespace URI with non-NULL prefix is illegal acording to the XML specification. - * - * - Namespace of a element is default if it is associated with some namespace declaration with NULL prefix. - * - * - Elements are never associated with namespace undeclarations (xmlns=""), instead, such elements have no - * namespace declaration referred to. - * - * - Attributes do not have default namespace. Even if it is effective at element scope, - * default namespace declaration is not applied to element's attributes (according to the XML specification) - * - * - Namespace of a node (element or attribute) is undefined if no namespace declaration is - * associated with it. - * - * - Node with undefined namespace is serialized as having no prefix. In general, - * DOM API handles the complexity of namespace declaration handling and creates neccessary - * namespace declarations and undeclares default namespace. However, some node-creation methods (e.g. TXmlEngElement::AddNewElementL()) - * do not ensure that created node with undefined namespace (thus, without a prefix) will - * actually treated after serialization as having some default namespace - * - * @note - * Namespace nodes that are result of XPath expression have following restrictions: - * - they cannot be used as namespace definitions, because they are not part of - * the DOM tree, but copies of existing namespace definitions. - * - namespace prefix is not available because it is not mandated by DOM Level 3 XPath module API, - * so in returned copies of DOM tree, namespaces prefix strings are not preserved - * and Prefix() returns NULL. - * - * @lib XmlEngineDOM.lib - * @since S60 v3.1 - */ + @file + @publishedAll + @released +*/ +#ifndef XMLENGNAMESPACE_H +#define XMLENGNAMESPACE_H + +#include + +/** +This class represents an existing namespace declaration in the DOM tree or a +namespace node returned in RXmlEngNodeSet as a result of some XPath expression. + +All elements and attributes may have a namespace instance associated with them. +Once added to an element, a namespace declaration (instance of +TXmlEngNamespace) may be referred to by all attributes and descendants of the +element (unless the prefix that this namespace-to-prefix binding uses is +overriden somewhere below in the document tree). + +General rules for namespace handling: + +- A NULL prefix in the namespace node means NO PREFIX. An empty string "" can +be used to specify the absence of a prefix when setting it, however, NULL will +be stored and returned. + +- A NULL value for a namespace URI is legal only with a NULL prefix and is only +used in the undeclaration of a namespace (@c xmlns="" ). An empty string "" +can be used too, however, it will be returned as NULL. + +- A NULL or empty string namespace URI with a non-NULL prefix is illegal +acording to the XML specification. + +- The namespace of an element is a default namespace if it has a NULL prefix. + +- Elements with namespace undeclarations (@c xmlns="" ), have no namespace and +are treated as local names. + +- Attributes do not have a default namespace. Even if a namespace is applied at +element scope, the default namespace declaration is not applied to the +element's attributes (according to the XML specification). + +- The namespace of a node (element or attribute) is undefined if no namespace +declaration is associated with it. + +- A node with an undefined namespace is serialized as having no prefix. In +general, the DOM API handles the complexity of namespace declaration handling, +creating neccessary namespace declarations and undeclaring default namespaces. +However, some node-creation methods (e.g. TXmlEngElement::AddNewElementL()) do +not ensure that a node created with an undefined namespace (i.e. without a +prefix) will be treated after serialization as having the default namespace. + +Note: +Namespace nodes that are the result of XPath expressions have following restrictions: + +- They cannot be used as namespace definitions, because they are not part of +the DOM tree, but rather copies of existing namespace definitions. + +- The namespace prefix is not available because it is not mandated by the DOM +Level 3 XPath API. So, in returned copies of the DOM tree, namespace prefix +strings are not preserved and Prefix() returns NULL. +*/ class TXmlEngNamespace: public TXmlEngNode { + friend class TXmlEngElement; + friend class TXmlEngNode; + public: - /** - * Default constructor - * - * @since S60 v3.1 - */ + /** Default constructor */ inline TXmlEngNamespace(); /** - /** - * Get namespace URI - * - * @since S60 v3.1 - * @return Namespace URI string - * @note "" is never returned - it is replaced with NULL - * - * For TXmlEngNamespace(NULL) or namespace undeclaration (xmlns=""), which are - * treatet as undefined namespace returns NULL, - * otherwise result is not a NULL string and not a "" (empty string). - */ + Gets the namespace URI + @return Namespace URI string or an empty string if the namespace is either + NULL or undeclared (@c xmlns="" ) + */ IMPORT_C TPtrC8 Uri() const; /** - * Get namespace prefix. - * - * @since S60 v3.1 - * @return prefix that is bound in the namespace declaration - * or NULL string for default namespace or if no binding exist - */ + Gets the namespace prefix. + @return The prefix bound in the namespace declaration or an empty string + when there is a default namespace or if no binding exists + */ IMPORT_C TPtrC8 Prefix() const; /** - * Check if namespace is default. - * - * @since S60 v3.1 - * @return Whether it is a definition of default namespace - * TRUE -- is a default namespace (no prefix) - * FALSE -- not a default namespace (bound to prefix) or empty TXmlEngNamespace(NULL) instance - */ + Check if the namespace is default. + @return ETrue if the namespace is default (no prefix), EFalse if the + namespace is not default (bound to prefix) or the namespace is NULL + */ IMPORT_C TBool IsDefault() const; /** - * Check if namespace is undefined - * - * @since S60 v3.1 - * @return Whether the namespace is undefined - * - * A node's namespace is undefined if no namespace declaration associated with it. - * @note Same as TXmlEngNode::IsNull() - */ + Check if the namespace is undefined. A node's namespace is undefined if no + namespace declaration is associated with it. This is the same as + TXmlEngNode::IsNull(). + @return ETrue if the namespace is undefined, EFalse otherwise + */ IMPORT_C TBool IsUndefined() const; protected: /** - * Workaround to avoid misuse of TXmlEngNode::NamespaceUri() method, which should not be - * applied to TXmlEngNamespace node. Since the name of the inherited method from TXmlEngNode - * is too similar to TXmlEngNamespace::Uri(), NamespaceUri() is disabled for direct - * use. - * If NamespaceUri() is called on the TXmlEngNamespace object that is downcasted to TXmlEngNode, then - * NamespaceUri()'s result equals to result of Uri() method. - * - * @since S60 v3.1 - * @return NULL - */ + This method is inherited from TXmlEngNode. To prevent its use, no function body + has been supplied. The method Uri() should be used instead. + + @see Uri(). + */ inline TPtrC8 NamespaceUri(); protected: /** - * Constructor - * - * @since S60 v3.1 - * @param aPtr Namespace pointer - */ + Constructor + @param aPtr Namespace pointer + */ inline TXmlEngNamespace(void* aPtr); - - friend class TXmlEngElement; - friend class TXmlEngNode; }; -#include "xmlengnamespace.inl" +#include -#endif /* XMLENGINE_NAMESPACE_H_INCLUDED */ +#endif /* XMLENGNAMESPACE_H */