/*
* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Class implements XML base fragment using libxml2 classes
*
*/
#ifndef SEN_FRAGMENT_BASE_H
#define SEN_FRAGMENT_BASE_H
// INCLUDES
#include <s32mem.h>
#include <Xml/ContentHandler.h>
#include <RSenDocument.h>
#include <SenParser.h>
#include <XmlEngElement.h>
using namespace Xml;
// CONSTANTS
// Fragment's internal states.
const TInt KSenStateNotSet = -1;
const TInt KSenStateIgnore = 0;
const TInt KSenStateSave = 1;
const TInt KSenStateResume = 2;
const TInt KSenStateDelegate = 3;
// FORWARD DECLARATIONS
class RWriteStream;
//class CSenParser;
class CSenNamespaceData;
// CLASS DECLARATION
/**
* Class implements basic functionality of an XML fragment
* Typically base fragment is used to parse certain part of some XML document.
* The element is identified by local name (or qualified name) and namespace.
* All child elements between start tag and and end tag defined this fragment
* will become content of this BaseFragment. In other words, BaseFragment has
* all data inside a single element.
* BaseFragment will parse only namespace (xmlns) attributes from a document
* and rest of the attributes are to be handled by subclasses, which should
* overwrite SetAttributesL() method to achieve this.
* The CSenFragmentReader class will do the actual parsing and this class will
* act as content handler for XML parser SAX events.
* @lib SenFragment.dll
* @since Series60 4.0
*/
class CSenFragmentBase : public CBase, public MContentHandler
{
friend class CSenParserImpl;
public: // Constructors and destructor
/**
* Standard 2 phase constructor.
* @since Series60 4.0
* @param aElement is the element where construction
* data will be copied from.
*/
IMPORT_C static CSenFragmentBase* NewL(const TXmlEngElement& aElement);
/**
* Standard 2 phase constructor.
* @since Series60 4.0
* @param aLocalName: is the XML localname for this fragment
*/
IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aLocalName);
/**
* Standard 2 phase constructor.
* @since Series60 4.0
* @param aNsUri: XML namespace URI
* @param aLocalName: XML localname
*/
IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
const TDesC8& aLocalName);
/**
* Standard 2 phase constructor.
* @since Series60 4.0
* @param aNsUri XML namespace URI
* @param aLocalName XML localname
* @param aPrefix XML prefix
*/
IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix);
/**
* Standard 2 phase constructor.
* @since Series60 4.0
* @param aNsUri XML namespace URI
* @param aLocalName XML localname
* @param aPrefix XML prefix
* @param apAttrs XML attributes
*/
IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix,
const RAttributeArray& apAttrs);
/**
* Standard 2 phase constructor.
* @param aParent Element to be set as fragment's parent element.
* @since Series60 4.0
* @param aNsUri XML namespace URI
* @param aLocalName XML localname
* @param aPrefix XML prefix
* @param apAttrs XML attributes
* @param aParent Parent element
*/
IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix,
const RAttributeArray& apAttrs,
TXmlEngElement& aParent);
/**
* Standard 2 phase constructor.
* @param aParent Element to be set as fragment's parent element.
* @since Series60 4.0
* @param aNsUri XML namespace URI
* @param aLocalName XML localname
* @param aPrefix XML prefix
* @param apAttrs XML attributes
* @param aParent Parent element
* @param aOwnerDocument The document which will be the owner of
* the elements of this fragment
*/
IMPORT_C static CSenFragmentBase* NewL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix,
const RAttributeArray& apAttrs,
TXmlEngElement& aParent,
RSenDocument& aOwnerDocument);
/**
* Standard 2 phase constructor.
* @param aParent Element to be set as fragment's parent element.
* @since Series60 4.0
* @param aRootElement The element which will be the root element
* of this fragment.
* @param aOwnerDocument The document which will be the owner of
* the elements of this fragment
*/
IMPORT_C static CSenFragmentBase* NewL(TXmlEngElement& aRootElement,
RSenDocument& aOwnerDocument);
/**
* Destructor.
*/
IMPORT_C virtual ~CSenFragmentBase();
// Functions from base classes
// From MContentHandler:
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnStartElementL(const RTagInfo& aElement, const RAttributeArray& aAttributes, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnEndElementL(const RTagInfo& aElement, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnStartDocumentL(const RDocumentParameters& aDocParam, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnEndDocumentL(TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnContentL(const TDesC8& aBytes, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnStartPrefixMappingL(const RString& aPrefix, const RString& aUri, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnEndPrefixMappingL(const RString& aPrefix, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnIgnorableWhiteSpaceL(const TDesC8& aBytes, TInt ErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnSkippedEntityL(const RString& aName, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnProcessingInstructionL(const TDesC8& aTarget, const TDesC8& aData, TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual void OnError(TInt aErrorCode);
/**
* Callback function implementing the XML content handler interface.
* Inheriting classes can override these.
* @since Series60 3.1
* @see MContentHandler
*/
IMPORT_C virtual TAny* GetExtendedInterface(const TInt32 aUid);
// New functions
/**
* Getter for the content,which is returned as UTF-8 form XML.
* @since Series60 4.0
* @return content as UTF-8 form XML.
*/
IMPORT_C virtual TPtrC8 ContentL();
/**
* Gets the namespace object with a given prefix.
* @since Series60 4.0
* @param aPrefix: prefix that wanted namespace should have.
* @return namespace with the given prefix. If not found or given prefix
* is zero length, will return NULL.
*/
IMPORT_C virtual TXmlEngNamespace Namespace(const TDesC8& aPrefix);
/**
* @since Series60 4.0
* @return Detaches this fragment from its owner. All namespace
* references from possible parent fragments are declared in
* the scope of this fragment prior detaching.
*/
// IMPORT_C virtual void DetachL();
/**
* Resets the content of the fragment, and resets the namespaces.
* @since Series60 4.0
*/
IMPORT_C virtual void ResetContentL();
/**
* @since Series60 4.0
* @return the localname of this fragment as UTF-8 form descriptor
*/
IMPORT_C virtual TPtrC8 LocalName() const;
/**
* Getter for Fragment's namespace URI..
* @since Series60 4.0
* @return Namespace URI or KNullDesC if not set.
*/
IMPORT_C virtual TPtrC8 NsUri() const;
/**
* Getter for namespace prefix of this fragment.
* @since Series60 4.0
* @return namespace prefix or KNullDesC if not set.
*/
IMPORT_C virtual TPtrC8 NsPrefix() const;
/**
* Returns the current XML element of this fragment. If element
* has not been set, this method will initialize new, un-initialized
* element.
* Method leaves with if there is not enough memory (OOM)
* @return reference to the element of this fragment
*/
IMPORT_C virtual TXmlEngElement AsElementL();
/**
* Returns the current XML element of this fragment. If element
* has not been set, this method will initialize new, un-initialized
* element.
* Method leaves with if there is not enough memory (OOM)
* @return reference to the element of this fragment
*/
IMPORT_C virtual RSenDocument& AsDocumentL();
/**
* Etracts the XML element from the fragment, leaving the fragment empty.
* Note(!): the return value (CSenElement) STRONGLY suggests that
* subclasses INHERIT CSenFragment in order properly comply the
* requirement of the ExtractElement() implementation.
* @since Series60 4.0
* @return the current object as element. May return NULL.
* Ownership IS TRANSFERRED to the caller.
*/
IMPORT_C virtual TXmlEngElement ExtractElement();
/**
* Let the delegate MSenFragment handle the following SAX events.
* This fragment is made the owner of the delegate and the delegate
* is expected to make this MSenFragment the receiver of SAX events
* once it has seen the end element for itself.
* @since Series60 4.0
* @param aDelegate is the fragment to start handling the SAX events.
*/
IMPORT_C virtual void OnDelegateParsingL(CSenFragmentBase& aDelegate);
/**
* Creates a new fragment and lets the created MSenFragment handle the
* following SAX events. This fragment is made the owner of the delegate
* and the delegate is expected to make this MSenFragment act as receiver
* for SAX events (callbacks) once it has seen the end element for itself.
* @since Series60 4.0
* @param aElement The RTagInfo class holding information that
* describes the element.
* @param aAttributes The attributes of the new element
* @param aErrorCode Error code
*/
IMPORT_C virtual void OnDelegateParsingL(const RTagInfo& aElement,
const RAttributeArray& aAttributes,
TInt aErrorCode);
/**
* Sets a new parent for this fragment.
* @since Series60 4.0
* @param aFragment: the new parent.
*/
IMPORT_C virtual void SetOwner(CSenFragmentBase& aFragment);
/**
* Leave codes:
* Resumes parsing to be handled by this fragment. Usually called by some
* delegate fragment which was set to be content handler because this
* fragment called DelegateParsingL().
* @since Series60 4.0
* @param aElement The RTagInfo class holding information that
* describes the element.
* @param aErrorCode Error code
*/
IMPORT_C virtual void OnResumeParsingFromL(const RTagInfo& aElement, TInt aErrorCode);
/**
* Sets the attributes for the fragment. BaseFragment parses only
* namespace (xmlns) attributes from the document.
* Subclasses should override this method if they are intrested
* of handling any other XML attributes and their corresponding
* values.
* @since Series60 4.0
* @param aAttrs: the array of attributes.
*/
// IMPORT_C virtual void SetAttributesL(const RAttributeArray& aAttrs);
/**
* Writes the start element tag to the content stream.
* Derivants can override the basic usage used in BaseFragment.
* @since Series60 4.0
* @param aElement The RTagInfo class holding information that
* describes the element.
* @param aAttributes The attributes of the new element
*/
IMPORT_C void OnWriteStartElementL(const RTagInfo& aElement,
const RAttributeArray& aAttributes);
/**
* Writes the end element tag to the content stream.
* Derivants can override the basic usage used in BaseFragment.
* @since Series60 4.0
* @param aElement The RTagInfo class holding information that
* describes the element.
*/
IMPORT_C void OnWriteEndElementL(const RTagInfo& aElement);
/**
* Gets the fragment data as an unicode XML.
* @since Series60 4.0
* @return fragment as XML. Caller takes ownership.
*/
IMPORT_C virtual HBufC* AsXmlUnicodeL();
/**
* Gets the fragment data as an UTF-8 form XML.
* @since Series60 4.0
* @return fragment as XML. Caller takes ownership.
*/
IMPORT_C virtual HBufC8* AsXmlL();
/**
* Invokes AsElement().WriteAsXMLToL(aWs);
* @since Series60 4.0
* @param aWs is the stream into which the UTF-8 form XML will
* be written.
*/
IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWs);
/**
* Checks if fragment matches to another fragment
* by its content and child elements.
* Fragment can contain more data than the given candidate.
* @since Series60 4.0
* @param aCandidate The pattern to be matched. Must contain same or
* less data for match to come true.
* @return ETrue if content and possible children match exactly
* to given pattern. EFalse otherwise.
*/
IMPORT_C virtual TBool ConsistsOfL(CSenFragmentBase& aCandidate);
//From SenParserImpl.h
IMPORT_C void SetContentHandler(CSenFragmentBase& aContentHandler);
/**
* Sets the RSenDocument
* @param aDocument
*/
IMPORT_C void SetDocument(RSenDocument& aDocument);
protected:
/**
* C++ default constructor.
*/
IMPORT_C CSenFragmentBase();
/**
* Following BaseConstructL methods should be called from ConstructL()
* methods of some deriving (fragment) class.
*/
/**
* BaseConstructL, where an element is given as initializer.
* @since Series60 4.0
* @param aElement from which this fragment will be constructed from.
*/
IMPORT_C void BaseConstructL(const TXmlEngElement& aSrc);
/**
* BaseConstructL setting XML localname for this fragment.
* @since Series60 4.0
* @param aLocalName XML localname for this fragment
*/
IMPORT_C void BaseConstructL(const TDesC8& aLocalName);
/**
* BaseConstructL offering possibility to set XML namespace and localname.
* @since Series60 4.0
* @param aNsUri XML namespace URI for this fragment
* @param aLocalName XML localname for this fragment
*/
IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
const TDesC8& aLocalName);
/**
* Base constructor
* @since Series60 4.0
* @param aNsUri XML namespace URI for this fragment
* @param aLocalName XML localname for this fragment
* @param aQName XML qualifiedname for this fragment
*/
IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix);
/**
* Base constructor
* @since Series60 4.0
* @param aNsUri XML namespace URI for this fragment
* @param aLocalName XML localname for this fragment
* @param aQName XML qualifiedname for this fragment
* @param aAttrs XML attributes for this fragment
*/
IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix,
const RAttributeArray& aAttrs);
/**
* Base constructor
* @since Series60 4.0
* @param aNsUri XML namespace URI for this fragment
* @param aLocalName XML localname for this fragment
* @param aQName XML qualifiedname for this fragment
* @param aAttrs XML attributes for this fragment
* @param aParent parent to be set for this fragmemt
*/
IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix,
const RAttributeArray& aAttrs,
TXmlEngElement& aParent);
/**
* Base constructor
* @since Series60 4.0
* @param aNsUri XML namespace URI for this fragment
* @param aLocalName XML localname for this fragment
* @param aQName XML qualifiedname for this fragment
* @param aAttrs XML attributes for this fragment
* @param aParent Parent to be set for this fragmemt
* @param aOwnerDocument The document which will be the owner of
* the elements of this fragment
*/
IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
const TDesC8& aLocalName,
const TDesC8& aPrefix,
const RAttributeArray& aAttrs,
TXmlEngElement& aParent,
RSenDocument& aOwnerDocument);
/**
* Base constructor
* @since Series60 4.0
* @param aRootElement The element which will be the root element
* of this fragment
* @param aOwnerDocument The document which will be the owner of
* the elements of this fragment
*/
IMPORT_C void BaseConstructL(TXmlEngElement& aRootElement,
RSenDocument& aOwnerDocument);
// New functions
/**
* Adds new XML attributes to this fragment.
* Can be overridden to replace old attributes.
* @param aAttrs: the array of attributes.
*/
IMPORT_C virtual void AddAttributesL(const RAttributeArray& apAttrs);
/**
* Adds new XML attributes to specified element.
* Can be overridden to replace old attributes.
* @param aAttrs: the array of attributes.
*/
IMPORT_C virtual void AddAttributesToElementL(TXmlEngElement element,
const RAttributeArray& apAttrs);
/**
* Method renames the XML properties of this fragment.
* @param aLocalName XML localname for this fragment
* @param aPrefix XML namespace prefix for this fragment
* @param aNamespace XML namespace URI for this fragment
* Method leaves with if there is not enough memory (OOM)
*/
void RenameL(const TDesC8& aLocalName, const TDesC8& aPrefix, const TDesC8& aNamespace);
/**
* Method renames the XML properties of this fragment.
* @param aLocalName XML localname for this fragment
* @param aNamespace XML namespace URI for this fragment
* Method leaves with if there is not enough memory (OOM)
*/
void RenameL(const TDesC8& aLocalName, const TDesC8& aNamespace);
/**
* Renames local name for this XML fragment.
* @param aLocalName XML localname for this fragment
* Method leaves with if there is not enough memory (OOM)
*/
void RenameLocalNameL(const TDesC8& aLocalName);
/**
* Renames namespace URI for this XML fragment.
* @param aNamespace XML namespace URI for this fragment
* Method leaves with if there is not enough memory(OOM)
*/
void RenameNamespaceL(const TDesC8& aNamespace);
/**
* Renames namespace prefix for this XML fragment.
* @param aPrefix XML namespace prefix for this fragment
* Method leaves with if there is not enough memory (OOM)
*/
void RenamePrefixL(const TDesC8& aPrefix);
/**
* Renames namespace prefix and namespace URI for this XML fragment.
* @param aPrefix XML namespace prefix for this fragment
* @param aNamespace XML namespace URI for this fragment
* Method leaves with if there is not enough memory (OOM)
*/
void RenameNamespaceL(const TDesC8& aPrefix, const TDesC8& aNamespace);
/**
* Sets content to a child element. If no element with given local name
* is not found, new one is added and content is set to that one.
* @since Series60 4.0
* @param aLocalName The local name of element which content
* is about to be set
* @param aContent Content to be set.
* @return the element where content was set.
* Leave codes:
* KErrSenInvalidCharacters if aLocalName contains illegal characters.
* KErrSenZeroLengthDescriptor if aLocalName is zero length.
*/
IMPORT_C TXmlEngElement SetContentOfL(const TDesC8& aLocalName,
const TDesC8& aContent);
/**
* Gets the content of a given element.
* @since Series60 4.0
* @param aLocalName The local name of the element which content is
* asked
* @return the content which was asked
*/
IMPORT_C TPtrC8 ContentOf(const TDesC8& aLocalName);
IMPORT_C virtual TBool ConsistsOfL(TXmlEngElement& aElement, TXmlEngElement& aCandidate);
/**
* Adds namespaces from internal array for the fragment.
* @since Series60 4.0
*/
IMPORT_C virtual void AddNamespacesL();
/**
* Sets content to a child element. If no element with given local name
* is not found, new one is added and content is set to that one.
* @since Series60 4.0
* @param aContent Content to be set.
*/
IMPORT_C virtual void SetContentL(const TDesC8& aContent);
/**
* Adds the content.
* @since Series60 4.0
* @param aContent Content to be set.
*/
IMPORT_C virtual void AddContentL(const TDesC8& aContent);
/**
* StartSavingContent changes the internal SAX parsing state of
* this fragment to KSenStateSave, which means that next call
* to OnStartElementL is treated as data, and not ignored
* (in DOM fragment implementation, it would be "extended"
* into a DOM object).
*/
IMPORT_C void StartSavingContent();
private: // New functions
/**
* Sets the XML parser to be used for parsing for the fragment.
* @since Series60 4.0
* @param aReader: the reader to be used.
* Ownership is NOT transferred.
*/
IMPORT_C virtual void SetParser(CSenParser& aParser);
protected: // Data
// State variable indicating what this fragment
// is currently parsing. Even states (like 0)
// mean that this fragment is ignoring the
// data, and odd states indicate, that fragment
// is storing the data into itself.
TInt iState;
// Owned element containing this XML fragment data.
TXmlEngElement iElement;
// Owned document representing this XML fragment
RSenDocument iDocument;
// Pointer to XML parser. Not owned.
CSenParser* ipParser; // Not owned
// Possible owner fragment, if such exists. Not owned.
CSenFragmentBase* ipOwner; // Not owned
CSenFragmentBase* ipDelegate; // Owned
RPointerArray<CSenNamespaceData>* ipNamespaceArray; // Owned
CBufFlat* ipContentBuf; // Owned
RBufWriteStream* ipContentWriteStream; // Owned
};
class CSenNamespaceData : public CBase
{
public:
virtual ~CSenNamespaceData();
public:
HBufC8* ipLocalName;
HBufC8* ipNamespaceUri;
HBufC8* ipPrefix;
};
#endif //SEN_FRAGMENT_BASE_H
// End of File