// 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:

 //

 /**

  @file

  @publishedAll

  @released

 */

 #ifndef XMLENGNAMESPACE_H

 #define XMLENGNAMESPACE_H

 #include <xml/dom/xmlengnode.h>

 /**

 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 */

 	inline TXmlEngNamespace();

     /**

     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;

     /**

     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 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 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:

     /**

 	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

     @param aPtr Namespace pointer

     */

 	inline TXmlEngNamespace(void* aPtr);

 };

 #include <xml/dom/xmlengnamespace.inl>

 #endif /* XMLENGNAMESPACE_H */