// Copyright (c) 2001-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:

// This file contains the declaration of the CMDXMLDocument class which

// is the root class for a Mini-DOM tree.

// 

//

/**

 * @file 

 * @publishedPartner

 * @released

 */

#ifndef __GMXMLDOCUMENT_H__

#define __GMXMLDOCUMENT_H__

#include <e32base.h>

#include <e32std.h>

#include <badesca.h>

class CMDXMLElement;

class MXMLDtd;

/**

MXMLDtd is a mixin class. If User wants  to  derive from MXMLDtd class ,

then  one  should not derive from any other class at the same time. 

i.e A class can not derive from CBase  at all  using MXMLDtd.

Interface for DTD defintion classes. 

A class derived from this interface can be used by CMDXMLParser or CMDXMLComposer 

to check that the data conforms to a specific DTD. 

@publishedPartner

@released

*/

class MXMLDtd

	{

public:

	/** Tests if an element name is valid in the DTD.

	@param aElement The element name to be tested

	@return ETrue the if element name valid, else EFalse

	@leave KErrNoMemory Out of memory */

	virtual TBool IsValidElementL(const TDesC& aElement) const = 0;

	/** Tests if an attribute name and value is valid in DTD.

	@param aElement The element to which the attributes belong

	@param aAttribute The attribute to be tested

	@param aAttributeValue The attribute value to be tested

	@return KErrNone if the name and value are valid, KXMLBadAttributeName if the 

	attribute name is invalid, or KXMLBadAttributeValue if the attribute value 

	is invalid 

	@leave KErrNoMemory Out of memory */

	virtual TInt IsValidAttributeForElementL(const TDesC& aElement, const TDesC& aAttribute, const TDesC& aAttributeValue) const = 0;

	/** Tests if the parent/child relationship is valid in DTD.

	@param aParentElement The name of the parent element to be tested

	@param aChildElements An array of child element names to be tested

	@return ETrue if parent/child relationship is valid

	@leave KErrNoMemory Out of memory */

	virtual TBool AreValidChildElementsL(const TDesC& aParentElement, const CDesCArray& aChildElements) const = 0;

	/** Tests it is valid for a particular element to have children.

	@param aElement The name of the element to be tested

	@return ETrue if it is valid for the element to have children */

	virtual TBool CanElementHaveChildren(const TDesC& aElement) const = 0;

	};

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

#include "gmxmldummydtd.h"

#endif

class CMDXMLDocument : public CBase

/** An XML document.

An object of this type owns the root element of a DOM tree and is not itself 

an XML node.

@publishedPartner

@released

 */

{

public:

	/**

	 Allocates and constructs a new CMDXMLDocument.

	 @param iDtdRepresentation DTD for the document

	 @return The new CMDXMLDocument object

	 @leave KErrNoMemory Out of memory 

	 */

  	IMPORT_C static CMDXMLDocument* NewL(MXMLDtd& iDtdRepresentation);

	/**

	 Allocates and constructs a new CMDXMLDocument, leaving the object on the cleanup stack.

	 @param iDtdRepresentation DTD for the document

	 @return The new CMDXMLDocument object

	 @leave KErrNoMemory Out of memory 

	 */

  	IMPORT_C static CMDXMLDocument* NewLC(MXMLDtd& iDtdRepresentation);

	/** Allocates and constructs a new CMDXMLDocument, without specifying a DTD.

	Documents created using this function will not be able to validate the XML.

	@return The new CMDXMLDocument

	@leave KErrNoMemory Out of memory  */

  	IMPORT_C static CMDXMLDocument* NewL();

	/** Allocates and constructs a new CMDXMLDocument, without specifying a DTD, 

	leaving the object on the cleanup stack.

	Documents created using this function will not be able to validate the XML.

	@return The new CMDXMLDocument

	@leave KErrNoMemory Out of memory  */

  	IMPORT_C static CMDXMLDocument* NewLC();

	/** Destructor. */

  	IMPORT_C virtual ~CMDXMLDocument();

	/** Gets the root element of the DOM tree.

	@return The root element of the DOM tree */

  	inline CMDXMLElement* DocumentElement() {return iRootElement;}

	/** Sets the document's XML version processing instruction.

	@param aVersionTag The XML version processing instruction. This must begin 

	with <?xml and end with >, for example <?xml version="1.0"?>.

	@return ETrue if successful, EFalse if the parameter format is not correct

	@leave KErrNoMemory Out of memory */

  	IMPORT_C TBool SetVersionTagL(const TDesC& aVersionTag);

	/** Sets the document's DOCTYPE declaration.

	@param aDocTypeTag The XML DOCTYPE declaration. This must begin<!DOCTYPE and 

	end >.

	@return ETrue if operation succeeds, EFalse if the parameter format is not 

	correct

	@leave KErrNoMemory Out of memory */

  	IMPORT_C TBool SetDocTypeTagL(const TDesC& aDocTypeTag);

	/** Tests whether an element name is valid for the document.

	@param aElement The element name to be tested

	@return True the if element name valid, else false

	@leave KErrNoMemory Out of memory */

	IMPORT_C TBool ValidElementNameL(const TDesC& aElement) const;

	/**

	 Tests whether it is valid for a particular element to have children.

	 @param aElement the name of the element to be tested

	 @return ETrue if it is valid for element to have children

	 */

	IMPORT_C TBool CanElementHaveChildren(const TDesC& aElement) const;

	/** Gets the document's XML version processing instruction.

	@return The document's XML version processing instruction. */

  	inline const TDesC& VersionTag() const {return *iVersionTag;}

	/** Gets the document's DOCTYPE declaration.

	@return The document's DOCTYPE declaration. */

  	inline const TDesC& DocTypeTag() const  {return *iDocTypeTag;}

	/** Gets a reference to the MXMLDtd object to use for DTD validation checking.

	@return DTD */

	const MXMLDtd& CMDXMLDocument::DtdRepresentation() const;

private:  

  	CMDXMLDocument(MXMLDtd& aDtdRepresentation);

  	CMDXMLDocument();

	/*

  	 * sets the root elememnt of the DOM tree.

  	 */

  	inline void SetDocumentElement(CMDXMLElement* aRootElement) {iRootElement = aRootElement;}

  	void ConstructL();

  	IMPORT_C void PlaceholderForRemovedExport1(MXMLDtd& aDtdRepresentation);

  	IMPORT_C void PlaceholderForRemovedExport2();

private:

   	CMDXMLElement* iRootElement;	// Root element node of the DOM tree

protected:

	/** XML Version text */

	HBufC* iVersionTag;				// XML Version text

	/** Document type text */

  	HBufC* iDocTypeTag;				// Document type text

private:

	MXMLDtd* iDtdRepresentation;	

	TBool iOwnsDtd;

};

#endif