/*

* Copyright (c) 2003 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: 

* A simple XML writer API for generating

* non-unicode XML documents.

* The API does not require its implementations

* to validate the generated XML document in any

* way. It is up to the application using the API

* to create well-formed and valid XML documents.

*

*/

#ifndef __XW_API__

#define __XW_API__

#include <e32base.h>

class MXmlWriter 

    { 

public:

    /**

     * Adds a prolog tag <?xml version='1.0' encoding='ISO-8859-1'?>

     * to the document.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddPrologL() = 0;

    /**

     * Adds a prolog tag to the document.

     *

     * @param aVersionNum The version number in the prolog.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddPrologL(const TDesC8& aVersionNum) = 0;

    /**

     * Adds a start tag to the document.

     *

     * @param aName The name of the start tag.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddStartTagL(const TDesC8& aName) = 0;

    /**

     * Adds an open start tag to the document.

     *

     * @param aName The name of the element

     * 

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void OpenStartTagL(const TDesC8& aName) = 0;

    /**

     * Adds an attribute to the currently open start tag.

     *

     * @param aName The name of the attribute

     *

     * @param aValue The value of the attribute

     * Predefined entities are inserted.

     * <  ->  &lt;

     * >  ->  >

     * &  ->  &

     * '  ->  '

     * "  ->  "

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddAttributeL(const TDesC8& aName, const TDesC8& aValue) = 0;

    /**

     * Ends an already opened start tag in the XML document.

     *

     * @param aEndElement If ETrue, specifies that the start tag also

     * ends the element (i.e. the element is an empty element and will

     * not have a separate end tag). If EFalse, specifies that the

     * element will end with a separate end tag that will be added

     * with the AddEndTagL method.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void CloseStartTagL(TBool aEndElement) = 0;

    /**

     * Adds text to an element whose start tag has been added to

     * the XML document.

     *

     * @param aText The element text

     * Predefined entities are inserted.

     * <  ->  &lt;

     * >  ->  >

     * &  ->  &

     * '  ->  '

     * "  ->  "

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddTextL(const TDesC8& aText) = 0;

    /**

     * Adds text to an element whose start tag has been added to

     * the XML document.

     *

     * @param aText The element text, that is NOT modified in any way.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddXmlTextL(const TDesC8& aText) = 0;

    /**

     * Adds an end tag to the document.

     *

     * @param aName The name of the end tag.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddEndTagL(const TDesC8& aName) = 0;

    /**

     * Adds an CDATA section to document.

     *

     * @param aText The text in the CDATA section.

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void AddCdataSectL(const TDesC8& aText) = 0;

    /**

     * Inserts text to the specified position in the document.

     * The text may include any kind of text, including XML.

     *

     * @param aPos The position in the document where

     * the text is to be inserted.

     *

     * @param aText The text to insert

     * Predefined entities are inserted.

     * <  ->  &lt;

     * >  ->  >

     * &  ->  &

     * '  ->  '

     * "  ->  "

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void InsertTextL(TInt aPos, const TDesC8& aText) = 0;

    /**

     * Inserts text to the specified position in the document.

     * The text may include any kind of text, including XML.

     *

     * @param aPos The position in the document where

     * the text is to be inserted.

     *

     * @param aText The text to insert

     *

     * On unexceptional conditions, the method leaves with

     * one of the system-wide error codes.

     */

    virtual void InsertXmlTextL(TInt aPos, const TDesC8& aText) = 0;

    /**

     * Returns the current length of the XML document.

     *

     * @return The current length of the XML document

     */

    virtual TInt Length() = 0;

    /**

     * Returns the specified part of the current

     * XML document to the caller

     *

     * @param aStartPos The position of the first character

     * to return

     * 

     * @param aEndPos The position of the last character

     * to return

     * 

     * @return A part of the current XML document

     */

    virtual TPtrC8 DocPart(TInt aStartPos, TInt aEndPos) = 0;

    /**

     * Resets the writer. A new XML-document can be written

     * using the same instance.

     */

    virtual void Reset() = 0;

    };

#endif // __XW_API__