1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // This file contains the declaration of the generic CMDXMLComposer class

    15 // which is responsible for creating an XML file

    16 // from a given DOM structure.

    17 // 

    18 //

    19 

    20 /**

    21  @file

    22 */

    23 

    24 

    25 #ifndef __GMXMLCOMPOSER_H__

    26 #define __GMXMLCOMPOSER_H__

    27 

    28 #include <e32base.h>

    29 #include <f32file.h>

    30 #include <gmxmlconstants.h>

    31 #include <charconv.h>

    32 

    33 //forward reference

    34 class CMDXMLDocument;

    35 class CMDXMLEntityConverter;

    36 class CMDXMLNode;

    37 

    38 class MMDXMLComposerObserver

    39 /** Abstract observer interface for notification when XML composition is complete.

    40 

    41 It should be implemented by users of CMDXMLComposer.

    42 

    43 @publishedPartner

    44 @released

    45 */

    46 	{

    47 public:

    48 	/**

    49 	 Call back function used to inform a client of the composer that the composer has completed.

    50 	 */

    51 	virtual void ComposeFileCompleteL() = 0;

    52 	};

    53 

    54 

    55 class CMDXMLComposer: public CActive

    56 /** Creates an XML file from a given DOM structure.

    57 	@publishedPartner

    58     @released

    59  */

    60 	{

    61 public:

    62 	/** Destructor. */

    63 	IMPORT_C ~CMDXMLComposer();

    64 

    65 	/** Allocates and constructs a new XML composer.

    66 	

    67 	@param aComposerObserver Composer observer

    68 	@leave KErrNoMemory Out of memory

    69 	@return New XML composer */

    70 	IMPORT_C static CMDXMLComposer* NewL(MMDXMLComposerObserver* aComposerObserver);

    71 	

    72 	/** Allocates and constructs a new XML composer.

    73 	

    74 	@param aComposerObserver Composer observer

    75 	@param aOutputProlog Whether to output Version and Doctype tags.

    76 	@leave KErrNoMemory Out of memory

    77 	@return New XML composer */

    78 	IMPORT_C static CMDXMLComposer* NewL(MMDXMLComposerObserver* aComposerObserver, TBool aOutputProlog);

    79 

    80 

    81 	/** Allocates and constructs a new XML composer, leaving the object on the cleanup 

    82 	stack.

    83 	

    84 	@leave KErrNoMemory Out of memory

    85 	@param aComposerObserver Composer observer

    86 	@return New XML composer */

    87 	IMPORT_C static CMDXMLComposer* NewLC(MMDXMLComposerObserver* aComposerObserver);

    88 	

    89 	/** Allocates and constructs a new XML composer, leaving the object on the cleanup 

    90 	stack.

    91 	

    92 	@leave KErrNoMemory Out of memory

    93 	@param aComposerObserver Composer observer

    94 	@param aOutputProlog Whether to output Version and Doctype tags.

    95 	@return New XML composer */

    96 	IMPORT_C static CMDXMLComposer* NewLC(MMDXMLComposerObserver* aComposerObserver, TBool aOutputProlog);

    97 

    98 	/** Starts file composition.

    99 	

   100 	This function must not be called when file sizing is in progress. If it is necessary to calulate

   101 	the size and generate the XML simultaneously then two instances of the composer should be used,

   102 	one for sizing and one for composition.

   103   

   104 	@param aRFs A file server session

   105 	@param aFileToCompose Name of the file to create

   106 	@param aDocument The document object to compose to the file

   107 	@param aFileType Type of the output file

   108 	@return KErrNone if successful */

   109 	IMPORT_C TInt ComposeFile(RFs aRFs, const TDesC& aFileToCompose, CMDXMLDocument* aDocument, TXMLFileType aFileType);

   110 

   111 	IMPORT_C TInt ComposeFile(RFile& aFileHandleToCompose, CMDXMLDocument* aDocument, TXMLFileType aFileType);

   112 

   113 	/** Starts calculating the size of the XML output without actually writing it to the file.

   114 

   115 	File size calculation is asyncronous, the size value is only updated when ComposeFileComplete

   116 	is called on the MMDXMLComposerObserver passed in in the NewL.

   117 

   118 	This function must not be called when file composition or another sizing operation is

   119 	in progress. If it is necessary to calulate the size and generate the XML simultaneously

   120 	then two instances of the composer should be used, one for sizing and one for composition.

   121 

   122 	@param aSize Will be set to the size of the XML document when composition has completed.

   123 	@param aDocument The document object to size

   124 	@param aFileType Type of the output file, required because it will affect the size of the XML

   125 	@return KErrNone if successful */

   126 

   127 	IMPORT_C TInt CalculateFileSize(TInt& aSize, CMDXMLDocument* aDocument, TXMLFileType aFileType);

   128 

   129 	/** Gets the composer's last error.

   130 	

   131 	@return Error code */

   132 	IMPORT_C TInt Error() const;

   133 

   134 	/**

   135 	 Get the severity of the most severe error found.

   136 	 @return the maximum error severity

   137 	 */

   138 	IMPORT_C TXMLErrorCodeSeverity ErrorSeverity() const; 

   139 

   140 	//Defect fix for INC036136 - Enable the use of custom entity converters in GMXML

   141 	/** Outputs raw data.

   142 	    it's only intended to be used from within a custom entity converter as

   143         it relies on a Composer sesssion already being in progress

   144 	

   145 	   @param aData Data to output

   146 	   @return KErrNone if successful, otherwise a file writing error. 

   147 	 */

   148 	IMPORT_C TInt OutputDataL(const TDesC& aData);

   149 

   150 	/**

   151 	 * Sets the entity converter to be used

   152 	 * and  take ownership of the passed entity converter

   153 	 * @param aEntityConverter The entity converter to be used

   154 	 */

   155 	IMPORT_C void SetEntityConverter(CMDXMLEntityConverter* aEntityConverter); 

   156 	//End Defect fix for INC036136

   157 

   158 public: // public functions used by other classes within the .dll, not for Export.

   159 	/** Gets the entity converter used by the composer.

   160 	

   161 	@return The entity converter used by the composer. */

   162 	IMPORT_C CMDXMLEntityConverter* EntityConverter() const;

   163 

   164 	/** Outputs a comment.

   165 	

   166 	@param aComment Comment to output

   167 	@return KErrNone if successful, otherwise a file writing error. */

   168 	TInt OutputCommentL(const TDesC& aComment);

   169 

   170 	/** Outputs a processing instruction.

   171 	

   172 	@param aInstruction Processing instruction text to output

   173 	@return KErrNone if successful, otherwise a file writing error. */

   174 	TInt OutputProcessingInstructionL(const TDesC& aInstruction);

   175 

   176 	/** Outputs a CDATA section.

   177 	

   178 	@param aCDataSection CDATA section to output

   179 	@return KErrNone if successful, otherwise a file writing error. */

   180 	TInt OutputCDataSectionL(const TDesC& aCDataSection);

   181 

   182 

   183 	/** Outputs a start of element tag.

   184 	

   185 	@param aElementName The name of the tag to output

   186 	@return KErrNone if successful, otherwise a file writing error. */

   187 	IMPORT_C TInt OutputStartOfElementTagL(const TDesC& aElementName);

   188 

   189 	/** Outputs an end of element start tag (</).

   190 	

   191 	@param aHasChildren True if the element has children

   192 	@return KErrNone if successful, otherwise a file writing error. */

   193 	IMPORT_C TInt OutputEndOfElementTagL(const TBool aHasChildren);

   194 

   195 	/** Output an end of element tag.

   196 	

   197 	@param aElementName The name of the tag to output

   198 	@return KErrNone if successful, otherwise a file writing error. */

   199 	TInt OutputEndTagL(const TDesC& aElementName);

   200 

   201 	/** Outputs an attribute name and value. 

   202 	

   203 	@param aAttributeName Attribute name

   204 	@param aAttributeValue Attribute value

   205 	@return KErrNone if successful, otherwise a file writing error. */

   206 	IMPORT_C TInt OutputAttributeL(const TDesC& aAttributeName, const TDesC& aAttributeValue);

   207 

   208 private:

   209 	/*

   210 	 * BaseConstructL function to be called by dervived classes during their construction

   211 	 */

   212 	void BaseConstructL();

   213 

   214 	/*

   215 	 * RunError function inherited from CActive base class - intercepts any Leave from

   216 	 * the RunL() function, sets an appropriate errorcode and calls ComposeFileCompleteL

   217 	 */

   218 	IMPORT_C TInt RunError(TInt aError);

   219 

   220 	 /*

   221 	 * DoCancel function inherited from CActive base class

   222 	 */

   223 	IMPORT_C virtual void DoCancel();

   224 

   225 	/*

   226 	 * RunL function inherited from CActive base class - does the actual composition

   227 	 * @leave can Leave due to OOM

   228 	 */

   229 	virtual void RunL();

   230 

   231 	/*

   232 	 * Function to write string to required file format - handles format conversion

   233 	 * @param aStringToWrite the string to output

   234 	 * @return returns KERRNone if successful or a file write error.

   235 	 */

   236 	virtual TInt WriteFileL(const TDesC& aStringToWrite);

   237 

   238 	/*

   239 	 * Function to flush output string to required file format - handles format conversion

   240 	 * @return returns KERRNone if successful or a file write error.

   241 	 */

   242 	virtual TInt FlushOutputBufferL();

   243 

   244 	/*

   245 	 * Constructor

   246 	 */

   247 	CMDXMLComposer(MMDXMLComposerObserver* aComposerObserver);

   248 

   249 	/*

   250 	 * Constructor

   251 	 */

   252 	CMDXMLComposer(MMDXMLComposerObserver* aComposerObserver, TBool aOutputProlog);

   253 

   254 

   255 	/*

   256 	 * Sets iError to new errorcode if more serious than any error so far encountered

   257 	 */

   258 	IMPORT_C void SetError(const TInt aErrorCode, const TXMLErrorCodeSeverity aSeverity);

   259 

   260 

   261 	/*

   262      * Outputs a start tag for the node which includes the

   263      * tag name and all attribute name value pairs currently

   264      * specified.  If the node is an empty node then it

   265      * makes the tag an empty node tag, otherwise it creates

   266      * a start tag.

   267      * @param aNode The Node for which the start tag is being written

   268      * @return Returns KerrNone if successful or a file write error

   269      */

   270 	IMPORT_C TInt ComposeStartTagL(CMDXMLNode& aNode);

   271 

   272 	/*

   273      * Outputs an end tag for the node.

   274      * @param aNode the node for which the tag is being written.

   275      * @return Returns KerrNone if successful or a file write error

   276      */

   277 

   278 

   279 	IMPORT_C TInt ComposeEndTagL(CMDXMLNode& aNode);

   280 

   281 	/*

   282 	 * Second stage constructor

   283 	 * @param aEntityStrings the string table which lists the entity references and conversion

   284 	 */

   285 	void ConstructL();

   286 	TInt ComposeL();

   287 	

   288 	void InitialiseCompose(CMDXMLDocument* aDocument, TXMLFileType aFileType);

   289 

   290 	IMPORT_C void PlaceholderForRemovedExport1(MMDXMLComposerObserver* aComposerObserver);

   291 	IMPORT_C void PlaceholderForRemovedExport2();

   292 	IMPORT_C void PlaceholderForRemovedExport3();

   293 	TInt ReplaceXmlCharactersL(const TDesC16& aXmlData, const TDesC& aString);

   294 

   295 private:

   296 	MMDXMLComposerObserver* iComposerObserver;

   297 	CMDXMLEntityConverter* iEntityConverter;	// Entity converter to use

   298 	CMDXMLDocument* iXMLDoc;					// XML document being composed

   299 	RFile iXMLFile;								// File being composed

   300 	TXMLFileType iFileType;						// Type of file being composed

   301 	TInt iError;								// Current error

   302 	TXMLErrorCodeSeverity iSeverity;			// ErrorCode severity

   303 	CCnvCharacterSetConverter* iCharconv;

   304 	TBuf<KWriteBufferLen> iOutputBuffer;

   305 	RFs iRFs;									// File system to use

   306 	TBool iOutputProlog;							// Whether to output Version and Doctype tags

   307 

   308 	TInt iSizeTally;

   309 	TInt* iSize;

   310 	TBool iOnlyCalculatingSize;

   311 

   312 #ifdef _DEBUG

   313 	TInt iIndentationLevel;

   314 #endif

   315 	};

   316 

   317 #endif