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