/*
* 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 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:        Central place for debug-type macros
*
*/








#ifndef SEN_FRAGMENT_H
#define SEN_FRAGMENT_H

//  INCLUDES
#include <e32base.h>
#include <s32strm.h>
#include <xml/Attribute.h>
#include <SenXmlReader.h>
#include <SenElement.h>
#include <MSenFragment.h>
// CLASS DECLARATION

/**
* Abstract base class declaring XML fragment interface.
* @lib SenXML.dll
* @since Series60 3.0
*/
class CSenFragment : public CBase, public MSenFragment
    {
    public: // New functions

        /**
         * Getting the fragment as an XML element. This method will panic if 
         * element has not been initialized for any reason.
         * @return the current object as element. Ownership is not transferred.
         */
        virtual CSenElement& AsElement() = 0;

        /**
         * @return the current object as element. May return NULL.
         *          Caller takes ownership.
         *
         * Note(!): the return value (CSenElement) STRONGLY suggests that
         * subclasses INHERIT CSenFragment in order properly comply the
         * requirement of the ExtractElement() implementation.
         */
        virtual CSenElement* ExtractElement() = 0;

        /**
         * Sets the XML reader to be used for parsing for the fragment.
         * @param aReader:      the reader to be used. 
         *                      Ownership is NOT transferred.
         */
        virtual void SetReader(CSenXmlReader& aReader) = 0;

        /**
         * Gets the XML reader which this fragment uses for parsing.
         * @param aReader:      the reader to be used. 
         *                      Ownerships is not transferred.
         */
        virtual CSenXmlReader* Reader() = 0;

        /**
         * Method to invoke parsing of a XML data.
         * Note: SetReader() must be called before this method can be used.
         * @param aXml: The XML data to be parsed.
         */
        virtual void ParseL(const TDesC8& aXml) = 0;

        /**
         * 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.
         * @return KErrNone or other system-wide Symbian error codes.
         */
        virtual TInt BuildFrom(const TDesC8& aBuf) = 0;

        /**
         * 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.
         * @param aDelegate:    the fragment to start handling the SAX events.
         */
        virtual void DelegateParsingL(MSenFragment& aDelegate) = 0;

        /**
         * 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 the receiver
         * of SAX events once it has seen the end element for itself.
         * @param aNsUri:       the namespace URI of the new delegate
         * @param aLocalName:   the local name of the new delegate
         * @param aQName:       the qualified name of the new delegate
         * @param aAttrs:       the attributes which to be set for the new delegate
         */
        virtual void DelegateParsingL(const TDesC8& aNsUri,
                                      const TDesC8& aLocalName,
                                      const TDesC8& aQName,
                                      const RAttributeArray& aAttrs) = 0;

        /**
         * Sets the reader for this fragment and sets this to be the 
         * content handler of the following SAX events.
         * @param aReader:  Reader to be used.
         */
        virtual void ParseWithL(CSenXmlReader& aReader) = 0;

        /**
         * Sets a new parent for this fragment.
         * @param aFragment:    the new parent.
         */
        virtual void SetOwner(MSenFragment& aFragment) = 0;

        /**
         * Resumes the parsing. Usually called by the delegate fragment which was
         * parsing itself after DelegateParsingL().
         * @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
         */
        virtual void ResumeParsingFromL(const TDesC8& aNsUri,
                                        const TDesC8& aLocalName,
                                        const TDesC8& aQName) = 0;

        /**
         * Sets the attributes for the fragment.
         * @param aAttrs:   the array of attributes.
         */
        virtual void SetAttributesL(const RAttributeArray& aAttrs) = 0;

        /**
         * Writes the start element tag to the content stream. 
         * Derivants can override the basic usage used in BaseFragment.
         * @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:       the array of attributes.
         */
        virtual void WriteStartElementL(const TDesC8& aNsUri,
                                        const TDesC8& aLocalName,
                                        const TDesC8& aQName,
                                        const RAttributeArray& aAttrs) = 0;

        /**
         * Writes the end element tag to the content stream. 
         * Derivants can override the basic usage used in BaseFragment.
         * @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
         */
        virtual void WriteEndElementL(const TDesC8& aNsUri,
                                      const TDesC8& aLocalName,
                                      const TDesC8& aQName) = 0;

        /**
        * Getter for Fragment's local name.
        * @return Localname or KNullDesC if not set.
        */
        virtual const TDesC8& LocalName() const = 0;

        /**
        * Getter for Fragment's namespace URI.
        * @return Namespace URI or KNullDesC if not set.
        */
        virtual const TDesC8& NsUri() const = 0;

        /**
         * Getter for namespace prefix of this fragment.
         * @return namespace prefix or KNullDesC if not set.
         */
        virtual const TDesC8& NsPrefix() const = 0;

        /**
         * Fragment writes itself to a write stream using UTF-8 charset encoding.
         * @param aWriteStream: The stream to write to.
         */
        virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;

        /**
         * Gets the fragment as an unicode XML buffer. 
         * Buffer will contain all the childs etc.
         * @return  fragment as XML. Caller takes ownership.
         */
        virtual HBufC* AsXmlUnicodeL() = 0;

        /**
         * Gets the fragment as an XML buffer.
         * @return  fragment as XML. Caller takes ownership.
         */
        virtual HBufC8* AsXmlL() = 0;

        /**
         * Getter for the content. Returns content namespaces if there are any.
         * @return Content.
         */
        virtual TPtrC8 Content() = 0;

        /**
         * 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.
         */
        virtual TBool ConsistsOfL(MSenFragment& aCandidate) = 0;
    };

#endif // SEN_FRAGMENT_H

// End of File