diff -r 000000000000 -r e35f40988205 xml/xmldomandxpath/inc/xmlengineserializer/xmlengdeserializer.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/xmldomandxpath/inc/xmlengineserializer/xmlengdeserializer.h Thu Dec 17 09:29:21 2009 +0200 @@ -0,0 +1,296 @@ +// 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: +// XML Deserializer +// + + + +/** + @file + @publishedAll + @released +*/ +#ifndef XMLENGDESERIALIZER_H +#define XMLENGDESERIALIZER_H + +#include +#include + +#include +#include +#include + +class RFs; +class TXmlEngDataContainer; + +/** Controls the format of deserialization */ +enum TXmlEngDeserializerType + { + /** Default deserialization (XML) */ + EDeserializerDefault, + /** Deserialization from MIME Multipart containing XOP */ + EDeserializerXOP, + /** Deserialization from XOP Infoset */ + EDeserializerXOPInfoset, + /** Deserialization from GZip */ + EDeserializerGZip + }; + +/** Controls the source of the deserialization */ +enum TXmlEngDeserializationSource + { + EDeserializeFromFile, + EDeserializeFromBuffer, + EDeserializeFromStream + }; + +/** +Provides deserialization and parsing for XML content using a SAX callback +interface. Derived classes provide deserialization for specific formats, +whereas this class defines the interface and provides default (plain XML) +deserialization. + +@see TXmlEngDeserializerType + +Deserialization generates SAX events that are passed to a MContentHandler. + +@see Xml::MContentHandler + +For deserialization to a DOM tree, see CXmlEngDeserializerDOM. +@see CXmlEngDeserializerDOM + +Support for data stored outside the DOM tree, such as data linked by +xop:include references, is provided. The external data must be set with +UseExternalDataL() prior to deserialization. The data is then returned through +the MContentHandler interface. +*/ +class CXmlEngDeserializer: public CBase +{ + friend class CXmlEngDeserializerXOP; + friend class CXmlEngDeserializerGZIP; + + public: + /** + Creates a deserializer of the given type. Returns an instance of this + class or a derived class. + + @param aHandler Content handler for SAX events triggered by deserialization + @param aType Deserializer type + @return The deserializer + @leave - One of the system-wide error codes + */ + IMPORT_C static CXmlEngDeserializer* NewL( Xml::MContentHandler& aContentHandler, TXmlEngDeserializerType aType = EDeserializerDefault); + + /** + Sets the input type to file and saves the file name for later + deserialization. + @param aFileName The file name of the file to deserialize + @leave - One of the system-wide error codes + */ + IMPORT_C void SetInputFileL(const TDesC& aFileName); + + /** + Sets the input type to buffer and saves the buffer for later deserialization. + @param aBuffer The buffer to deserialize + */ + IMPORT_C void SetInputBuffer(const TDesC8& aBuffer); + + /** + Sets the content handler which handles SAX events raised during + deserialization. Clients must derive from Xml::MContentHandler in order to + receive SAX callbacks. + + @param aContentHandler The content handler + @leave - One of the system-wide error codes + */ + IMPORT_C virtual void SetContentHandlerL(Xml::MContentHandler& aContentHandler); + + /** + Sets parsing options used for deserialization. + @param aOptions Parsing options to set. A copy of the options is stored. + */ + IMPORT_C virtual void SetParsingOptions(TXmlEngParsingOptions& aOptions); + + /** + Gets the parsing options + @return The parsing options + */ + IMPORT_C virtual const TXmlEngParsingOptions& ParsingOptions(); + + /** + Sets a list of data containers and indicates that the XML to be + deserialized contains references (such as xop:include) to data stored + outside the DOM tree. + + Upon deserialization, the references are substituted with the matching data + containers and returned via the content handler. + + This often occurs when a multipart MIME message is received. The text XML + content may be in one part, while the binary content is in another part. + Each part containing binary content must be placed into a data container using + RXmlEngDocument::CreateBinaryContainerL() or similar. When deserialization + of the XML occurs, the data containers are retrieved by content-id. + + Ownership is not transferred and the list must stay in scope for the + lifetime of the deserializer. + + @param aList The list of data containers + @leave - Any system-wide error code + */ + IMPORT_C void UseExternalDataL(RArray& aList); + + /** + Gets the list of external data containers. + @return The list of data containers or NULL if no external data is registered + */ + IMPORT_C RArray* ExternalData(); + + /** + Enables parser features. + + @see Xml::CParser::EnableFeature() + @see Xml::CParser::TParserFeature + @param aParserFeature The parser feature to enable + @return KErrNone if successful, otherwise one of the system-wide error codes + */ + IMPORT_C virtual TInt EnableFeature(TInt aParserFeature); + + /** + Disables parser features. + + @see Xml::CParser::DisableFeature() + @see Xml::CParser::TParserFeature + @param aParserFeature The parser feature to disable + @return KErrNone if successful, otherwise one of the system-wide error codes + */ + IMPORT_C virtual TInt DisableFeature(TInt aParserFeature); + + /** + Checks if a parser feature is enabled. + + @see Xml::CParser::IsFeatureEnabled() + @see Xml::CParser::TParserFeature + @param aParserFeature The parser feature to check + @return ETrue if feature is enabled, otherwise EFalse + */ + IMPORT_C virtual TBool IsFeatureEnabled(TInt aParserFeature) const; + + /** + Deserializes the file or buffer previously set by SetInputFileL() or + SetInputBuffer(). + + The result of deserialization is passed to the content handler as SAX + events. + + @leave KXmlEngErrNoParameters No file or buffer has been previously set + @leave - One of the system wide error codes or one of the Xml specific + ones defined in XmlFrameworkErrors.h + */ + IMPORT_C virtual void DeserializeL(); + + /** + Deserializes the given file. Any filename previously set with + SetInputFileL() is ignored. + + The result of deserialization is passed to the content handler as SAX + events. + + @param aFileName The file to be parsed + @param aOptions Parsing options + @leave - One of the system wide error codes or one of the Xml specific + ones defined in XmlFrameworkErrors.h + */ + IMPORT_C virtual void DeserializeL( const TDesC& aFileName, + const TXmlEngParsingOptions& aOptions = + TXmlEngParsingOptions()); + + /** + Deserializes the given file. Any filename previously set with + SetInputFileL() is ignored. + + The result of deserialization is passed to the content handler as SAX + events. + + @param aRFs File Server session + @param aFileName The file to be parsed + @param aOptions Parsing options + @leave - One of the system wide error codes or one of the Xml specific + ones defined in XmlFrameworkErrors.h + */ + IMPORT_C virtual void DeserializeL( RFs& aRFs, + const TDesC& aFileName, + const TXmlEngParsingOptions& aOptions = + TXmlEngParsingOptions()); + + /** + Deserializes the given buffer. Any buffer previously set with + SetInputBuffer() is ignored. + + The result of deserialization is passed to the content handler as SAX + events. + + @param aBuffer The buffer to be parsed + @param aOptions Parsing options + @leave - One of the system wide error codes or one of the Xml specific + ones defined in XmlFrameworkErrors.h + */ + IMPORT_C virtual void DeserializeL( const TDesC8& aBuffer, + const TXmlEngParsingOptions& aOptions = + TXmlEngParsingOptions()); + + /** Destructor */ + virtual ~CXmlEngDeserializer(); + + /** + Retrieves a pointer to the data container referenced by CID. + @param aCid The aCid corresponding to the data container required + @return The data container or NULL if no matching container is found + */ + TXmlEngDataContainer* GetDataContainer(const TDesC8& aCid); + +private: + /** Default constructor */ + CXmlEngDeserializer( ); + + /** 2nd phase constructor */ + virtual void ConstructL( Xml::MContentHandler& aContentHandler ); + +private: + /** SAX Parser */ + Xml::CParser* iParser; + + /** File to be parsed */ + HBufC* iInputFileName; + + /** Buffer to be parsed */ + TPtrC8 iBuffer; + + /** Deserialization format */ + TXmlEngDeserializationSource iSerializationOutput; + + /** Array of external data */ + RArray* iDataList; + + /** Features */ + TUint iFeatures; + + /** Parsing options */ + TXmlEngParsingOptions iParsingOptions; + +}; //class CXmlEngDeserializer + + + +#endif /* XMLENGDESERIALIZER_H */ +