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