1 /*

     2 * Copyright (c) 2003 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * A simple XML writer API for generating

    16 * non-unicode XML documents.

    17 * The API does not require its implementations

    18 * to validate the generated XML document in any

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

    20 * to create well-formed and valid XML documents.

    21 *

    22 */

    23 

    24 

    25 #ifndef __XW_API__

    26 #define __XW_API__

    27 

    28 #include <e32base.h>

    29 

    30 class MXmlWriter 

    31     { 

    32 public:

    33     /**

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

    35      * to the document.

    36      *

    37      * On unexceptional conditions, the method leaves with

    38      * one of the system-wide error codes.

    39      */

    40     virtual void AddPrologL() = 0;

    41 

    42     /**

    43      * Adds a prolog tag to the document.

    44      *

    45      * @param aVersionNum The version number in the prolog.

    46      *

    47      * On unexceptional conditions, the method leaves with

    48      * one of the system-wide error codes.

    49      */

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

    51 

    52     /**

    53      * Adds a start tag to the document.

    54      *

    55      * @param aName The name of the start tag.

    56      *

    57      * On unexceptional conditions, the method leaves with

    58      * one of the system-wide error codes.

    59      */

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

    61     

    62     /**

    63      * Adds an open start tag to the document.

    64      *

    65      * @param aName The name of the element

    66      * 

    67      * On unexceptional conditions, the method leaves with

    68      * one of the system-wide error codes.

    69      */

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

    71 

    72     /**

    73      * Adds an attribute to the currently open start tag.

    74      *

    75      * @param aName The name of the attribute

    76      *

    77      * @param aValue The value of the attribute

    78      * Predefined entities are inserted.

    79      * <  ->  &lt;

    80      * >  ->  >

    81      * &  ->  &

    82      * '  ->  '

    83      * "  ->  "

    84      *

    85      * On unexceptional conditions, the method leaves with

    86      * one of the system-wide error codes.

    87      */

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

    89 

    90     /**

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

    92      *

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

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

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

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

    97      * with the AddEndTagL method.

    98      *

    99      * On unexceptional conditions, the method leaves with

   100      * one of the system-wide error codes.

   101      */

   102     virtual void CloseStartTagL(TBool aEndElement) = 0;

   103 

   104     /**

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

   106      * the XML document.

   107      *

   108      * @param aText The element text

   109      * Predefined entities are inserted.

   110      * <  ->  &lt;

   111      * >  ->  >

   112      * &  ->  &

   113      * '  ->  '

   114      * "  ->  "

   115      *

   116      * On unexceptional conditions, the method leaves with

   117      * one of the system-wide error codes.

   118      */

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

   120 

   121     /**

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

   123      * the XML document.

   124      *

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

   126      *

   127      * On unexceptional conditions, the method leaves with

   128      * one of the system-wide error codes.

   129      */

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

   131 

   132     /**

   133      * Adds an end tag to the document.

   134      *

   135      * @param aName The name of the end tag.

   136      *

   137      * On unexceptional conditions, the method leaves with

   138      * one of the system-wide error codes.

   139      */

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

   141 

   142     /**

   143      * Adds an CDATA section to document.

   144      *

   145      * @param aText The text in the CDATA section.

   146      *

   147      * On unexceptional conditions, the method leaves with

   148      * one of the system-wide error codes.

   149      */

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

   151 

   152     /**

   153      * Inserts text to the specified position in the document.

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

   155      *

   156      * @param aPos The position in the document where

   157      * the text is to be inserted.

   158      *

   159      * @param aText The text to insert

   160      * Predefined entities are inserted.

   161      * <  ->  &lt;

   162      * >  ->  >

   163      * &  ->  &

   164      * '  ->  '

   165      * "  ->  "

   166      *

   167      * On unexceptional conditions, the method leaves with

   168      * one of the system-wide error codes.

   169      */

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

   171 

   172     /**

   173      * Inserts text to the specified position in the document.

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

   175      *

   176      * @param aPos The position in the document where

   177      * the text is to be inserted.

   178      *

   179      * @param aText The text to insert

   180      *

   181      * On unexceptional conditions, the method leaves with

   182      * one of the system-wide error codes.

   183      */

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

   185 

   186     /**

   187      * Returns the current length of the XML document.

   188      *

   189      * @return The current length of the XML document

   190      */

   191     virtual TInt Length() = 0;

   192     

   193     /**

   194      * Returns the specified part of the current

   195      * XML document to the caller

   196      *

   197      * @param aStartPos The position of the first character

   198      * to return

   199      * 

   200      * @param aEndPos The position of the last character

   201      * to return

   202      * 

   203      * @return A part of the current XML document

   204      */

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

   206 

   207     /**

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

   209      * using the same instance.

   210      */

   211     virtual void Reset() = 0;

   212     };

   213 

   214 #endif // __XW_API__