FCL/sf/mw/websrv: comparison websrv_pub/xml_extensions

equal deleted inserted replaced

--1:000000000000
+:62f9d29f7211
+/*
+* Copyright (c) 2002-2005 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:        Class implements basic functionality of an XML fragment
+*
+*/
+#ifndef SEN_BASE_FRAGMENT_H
+#define SEN_BASE_FRAGMENT_H
+//  INCLUDES
+#include <MSenContentHandlerClient.h>
+#include <SenElement.h>
+#include <SenFragment.h>
+// CONSTANTS
+// Fragment's internal states.
+const TInt KStateNotSet = -1;
+const TInt KStateIgnore =  0;
+const TInt KStateSave   =  1;
+const TInt KStateResume =  2;
+// FORWARD DECLARATIONS
+class CSenXmlReader;
+// CLASS DECLARATION
+/**
+* Class implements basic functionality of an XML fragment
+* Typically BaseFragment is used to parse certain part of some XML document.
+* The element is identified by localname (or qualifiedname) 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 CSenXmlReader class will do the actual parsing and this class will
+* act as content handler for XML parser SAX events.
+* @lib SenXML.dll
+* @since Series60 3.0
+*/
+class CSenBaseFragment : public CSenFragment, public MSenContentHandlerClient
+{
+public:  // Constructors and destructor
+/**
+*  Standard 2 phase constructor.
+*  @since Series60 3.0
+*  @param aElement is the element where construction
+*                  data will be copied from.
+*/
+IMPORT_C static CSenBaseFragment* NewL(const CSenElement& aElement);
+/**
+*  Standard 2 phase constructor.
+*  Leave codes:
+*      KErrSenInvalidCharacters if aLocalName contains
+*      illegal characters.
+*      KErrSenZeroLengthDescriptor if aLocalName is zero length.
+*  @since Series60 3.0
+*  @param aLocalName: is the XML localname for this fragment
+*/
+IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aLocalName);
+/**
+*  Standard 2 phase constructor.
+*  Leave codes:
+*      KErrSenInvalidCharacters if aLocalName contains
+*      illegal characters.
+*      KErrSenZeroLengthDescriptor if aLocalName is zero length.
+*  @since Series60 3.0
+*  @param aNsUri:  XML namespace URI
+*  @param aLocalName:  XML localname
+*/
+IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
+const TDesC8& aLocalName);
+/**
+*  Standard 2 phase constructor.
+*  Leave codes:
+*      KErrSenInvalidCharacters if aLocalName or aQName contains
+*      illegal characters.
+*      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
+*  @since Series60 3.0
+*  @param aNsUri:  XML namespace URI
+*  @param aLocalName:  XML localname
+*  @param aQName:  XML qualifiedname
+*/
+IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName);
+/**
+* Standard 2 phase constructor.
+* Leave codes:
+*      KErrSenInvalidCharacters if aLocalName or aQName contains
+*      illegal characters.
+*      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
+* @since Series60 3.0
+* @param aNsUri:   XML namespace URI
+* @param aLocalName:   XML localname
+* @param aQName:   XML qualifiedname
+* @param apAttrs:  XML attributes
+*/
+IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName,
+const RAttributeArray& apAttrs);
+/**
+*  Standard 2 phase constructor.
+*  @param aParent  Element to be set as fragment's parent element.
+*    Leave codes:
+*          KErrSenInvalidCharacters if aLocalName or aQName contains
+*          illegal characters.
+*          KErrSenZeroLengthDescriptor if aLocalName or aQName is of
+*      zero length.
+*  @since Series60 3.0
+*  @param aNsUri:  XML namespace URI
+*  @param aLocalName:  XML localname
+*  @param aQName:  XML qualifiedname
+*  @param apAttrs: XML attributes
+*  @param aParent: Parent element
+*/
+IMPORT_C static CSenBaseFragment* NewL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName,
+const RAttributeArray& apAttrs,
+CSenElement& aParent);
+/**
+* Destructor.
+*/
+IMPORT_C virtual ~CSenBaseFragment();
+// New functions
+/**
+* Getter for the content,which is returned as UTF-8 form XML.
+* @since Series60 3.0
+* @return content as UTF-8 form XML.
+*/
+IMPORT_C virtual TPtrC8 Content();
+/**
+* Gets the namespace object with a given prefix.
+* @since Series60 3.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 CSenNamespace* Namespace(const TDesC8& aPrefix);
+/**
+* @since Series60 3.0
+* @param aPrefix is the XML namespace prefix
+*/
+IMPORT_C virtual void EnsureNamespace(const TDesC8& aPrefix);
+/**
+* @since Series60 3.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();
+/**
+* @since Series60 3.0
+* @param aAttrs are the attributes from which the namespaces
+*        are searched from.
+* @param aEnsure if set to TRUE, the namespaces are copied into
+*         this fragment. If FALSE, then the namespaces are only
+*         referenced, but not copied and owned by this class.
+*/
+IMPORT_C virtual void SaveNamespacesL(const RAttributeArray& aAttrs,
+TBool aEnsure);
+/**
+* Resets the content of the fragment, and resets the namespaces.
+* @since Series60 3.0
+*/
+IMPORT_C virtual void ResetContentL();
+// Functions from base classes
+// From CSenFragment
+/**
+* @since Series60 3.0
+* @return the localname of this fragment as UTF-8 form descriptor
+*/
+IMPORT_C virtual const TDesC8& LocalName() const;
+/**
+* Getter for Fragment's namespace URI..
+* @since Series60 3.0
+* @return Namespace URI or KNullDesC if not set.
+*/
+IMPORT_C virtual const TDesC8& NsUri() const;
+/**
+* Getter for namespace prefix of this fragment.
+* @since Series60 3.0
+* @return namespace prefix or KNullDesC if not set.
+*/
+IMPORT_C virtual const TDesC8& NsPrefix() const;
+/**
+* Getting the fragment as an XML element. This method will panic if
+* element has not been initialized for any reason.
+* @since Series60 3.0
+* @return the current object as element. Ownership is not transferred.
+*/
+IMPORT_C virtual CSenElement& AsElement();
+/**
+* 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 3.0
+* @return the current object as element. May return NULL.
+* Ownership IS TRANSFERRED to the caller.
+*/
+IMPORT_C virtual CSenElement* ExtractElement();
+/**
+* Gets the XML reader which this fragment uses for parsing.
+* @since Series60 3.0
+* @return the XML reader. Ownerships is not transferred,
+* due even this class does not own the XML reader instance.
+*/
+IMPORT_C virtual CSenXmlReader* Reader();
+/**
+* Sets the XML reader to be used for parsing for the fragment.
+* @since Series60 3.0
+* @param aReader:      the reader to be used.
+*                      Ownership is NOT transferred.
+*/
+IMPORT_C virtual void SetReader(CSenXmlReader& aReader);
+/**
+*  Leave codes:
+*  KErrSenXmlReaderNotSet  if XML reader has not been set.
+*  Method to invoke parsing of a XML data.
+*  Note that SetReader() must be called before this method can be used.
+*  Note that CSenBaseFragment does not parse any other
+*  attributes, but XML namespace attributes only. This
+*  is due to allow subclasses to process only those attributes
+*  they are interested in, and not others.
+*  @since Series60 3.0
+*  @param aXml:    The data to be parsed.
+*/
+IMPORT_C virtual void ParseL(const TDesC8& aXml);
+/**
+* Same as ParseL() except that it doesn't leave in case of an error.
+* Instead errors are trapped and error is returned.
+* SetReader() must be called before this method can be used.
+* @since Series60 3.0
+* @param aXml: The data to be parsed.
+* @return KErrNone or other system-wide Symbian error codes.
+*/
+IMPORT_C virtual TInt BuildFrom(const TDesC8& aXml);
+/**
+* Leave codes:
+* KErrSenXmlReaderNotSet   if XML reader has not been set.
+* 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 3.0
+* @param aDelegate is the fragment to start handling the SAX events.
+*/
+IMPORT_C virtual void DelegateParsingL(MSenFragment& aDelegate);
+/**
+* Leave codes:
+* KErrSenXmlReaderNotSet   if XML reader has not been set.
+* 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 3.0
+* @param aNsUri    The XML namespace URI for the delegate to be created
+* @param aLocalName    The XML localname for the delegate to be created
+* @param aQName    The XML qualifiedname for the delegate to be created
+* @param aAttrs:   The XML attributes for the delegate to be created
+*/
+IMPORT_C virtual void DelegateParsingL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName,
+const RAttributeArray& aAttrs);
+/**
+* Sets the reader for this fragment and sets this to be the
+* content handler of the following SAX events.
+* @since Series60 3.0
+* @param aReader is the XML parser to be used.
+*/
+IMPORT_C virtual void ParseWithL(CSenXmlReader& aReader);
+/**
+* Sets a new parent for this fragment.
+* @since Series60 3.0
+* @param aFragment:    the new parent.
+*/
+IMPORT_C virtual void SetOwner(MSenFragment& aFragment);
+/**
+* Leave codes:
+* KErrSenXmlReaderNotSet   if XML reader has not been set.  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 3.0
+* @param aNsUri    The namespace URI of the current element
+* @param aLocalName    The local name of the current element
+* @param aQName    The qualified name of the current element
+*/
+IMPORT_C virtual void ResumeParsingFromL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName);
+/**
+* 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 3.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 3.0
+* @param aNsUri        The namespace URI of the current element
+* @param aLocalName        The local name of the current element
+* @param aQName        The qualified name of the current element
+* @param aAttrs        is the array of attributes.
+*/
+IMPORT_C void WriteStartElementL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName,
+const RAttributeArray& aAttrs);
+/**
+* Writes the end element tag to the content stream.
+* Derivants can override the basic usage used in BaseFragment.
+* @since Series60 3.0
+* @param aNsUri        The namespace URI of the current element
+* @param aLocalName    The local name of the current element
+* @param aQName        The qualified name of the current element
+*/
+IMPORT_C void WriteEndElementL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName);
+/**
+* Gets the fragment data as an unicode XML.
+* @since Series60 3.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 3.0
+* @return  fragment as XML. Caller takes ownership.
+*/
+IMPORT_C virtual HBufC8* AsXmlL();
+/**
+* Invokes AsElement()->WriteAsXMLToL(aWs);
+* @since Series60 3.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 3.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(MSenFragment& aCandidate);
+protected:
+/**
+* C++ default constructor.
+*/
+IMPORT_C CSenBaseFragment();
+/**
+* Following BaseConstructL methods should be called from ConstructL()
+* methods of some deriving (fragment) class.
+*/
+/**
+* BaseConstructL, where an element is given as initializer.
+* @since Series60 3.0
+* @param aElement from which this fragment will be constructed from.
+*/
+IMPORT_C void BaseConstructL(const CSenElement& aElement);
+/**
+* BaseConstructL setting XML localname for this fragment.
+* @since Series60 3.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 3.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 3.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& aQName);
+/**
+* Base constructor
+* @since Series60 3.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& aQName,
+const RAttributeArray& aAttrs);
+/**
+* Base constructor
+* @since Series60 3.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& aQName,
+const RAttributeArray& aAttrs,
+CSenElement& aParent);
+/**
+* BaseConstructL() setting the XML reader for this fragment
+* @since Series60 3.0
+* @param aReader is the XML reader for this fragment
+*/
+IMPORT_C void BaseConstructL(CSenXmlReader& aReader);
+// New functions
+/**
+* Makes the content internal stream for content saving available.
+* @since Series60 3.0
+*/
+IMPORT_C virtual void AllocContentSaverL();
+/**
+* Callback function implementing the XML content handler interface.
+* Inheriting classes can override these.
+* @since Series60 3.0
+* @param aNsUri        The namespace URI of the new element
+* @param aLocalName    The local name of the new element
+* @param aQName        The qualified name of the new element
+* @param aAttrs        The attributes of the new element
+*/
+IMPORT_C virtual void StartElementL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName,
+const RAttributeArray& aAttrs);
+/**
+* Callback function which implement the XML content handler interface.
+* Inheriting classes can override these.
+* @since Series60 3.0
+* @param aNsUri     The namespace URI of the new element
+* @param aLocalName     The local name of the new element
+* @param aQName     The qualified name of the new element
+*/
+IMPORT_C virtual void EndElementL(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName);
+/**
+* Function which implement the XML content handler interface.
+* Inheriting classes can override these.
+* This one is called when content is starting.
+* @since Series60 3.0
+* @param aChars     The content characters.
+* @param aStart     The starting index
+* @param aLength        The length of the characters.
+*/
+IMPORT_C virtual void CharactersL(const TDesC8& aChars,
+TInt aStart,
+TInt aLength);
+/**
+*  Callback function which implement the XML content handler interface.
+*  Inheriting classes can override these. Note that overrides should
+*  return TRUE (1) on success and FALSE (0) on failure to parser.
+*
+*  @since Series60 3.0
+*  @param aName     The entity name
+*
+*/
+IMPORT_C TInt StartEntity(TDesC8& aName);
+/**
+* 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 3.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 MSenElement& SetContentOfL(const TDesC8& aLocalName,
+const TDesC8& aContent);
+/**
+* Gets the content of a given element.
+* @since Series60 3.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);
+private: // New functions
+/**
+* Leaving variant which is then trapped in the non-leaving function.
+*/
+TPtrC8 ContentL();
+// Functions from base classes
+// From MSenContentHandlerClient
+IMPORT_C virtual TInt StartDocument();
+IMPORT_C virtual TInt EndDocument();
+IMPORT_C virtual TInt StartElement(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName,
+const RAttributeArray& aAttrs);
+IMPORT_C virtual TInt EndElement(const TDesC8& aNsUri,
+const TDesC8& aLocalName,
+const TDesC8& aQName);
+IMPORT_C virtual TInt Characters(const TDesC8& aChars,
+const TInt aStart,
+const TInt aLength);
+IMPORT_C virtual TInt Error(TInt aErrorCode);
+//IMPORT_C TInt StartEntityL(const TDesC8& aName);
+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.
+CSenElement* ipElement;
+// Pointer to XML parser. Not owned.
+CSenXmlReader* iXmlReader;
+// Possible owner fragment, if such exists. Not owned.
+MSenFragment* ipOwner;
+// Internal write stream, into which UTF-8 form XML is stored
+RWriteStream iWs;
+private: // Data
+// Owned pointer to delegate fragment
+CSenFragment* ipDelegate;
+// Not owned. Holds namespaces that are referred to from
+// within the content but were not declared within this
+// BaseFragment.
+RPointerArray<CSenNamespace> iNamespaces;
+// Owned. Holds prefixes that have been declared within the
+// scope of this BaseFragment
+RPointerArray<HBufC8> iPrefixes;
+// Actual flat buffer to content which includes namespaces.
+CBufFlat* ipContentWithNamespaces;
+// Indicating that content writing stream is initialized.
+TBool hasContentWriteStream;
+// Indicates whether or not ipElement member is an owned
+TBool iElementOwned;
+};
+#endif //SEN_BASE_FRAGMENT_H
+// End of File