/*
* 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:        CSenSoapEnvelope is an utility class offering capability to 
*                 parse XML SOAP envelope and manipulation methods to alter its
*                 contents.
*
*/








#ifndef SEN_SOAP_ENVELOPE_H
#define SEN_SOAP_ENVELOPE_H

//  INCLUDES
#include <SenBaseFragment.h>
#include <SenSoapConstants.h>

// CONSTANTS
_LIT8(KSoapActionHeaderValueEmpty,	"\"\""); // default, if not set

/*
// Now declared in <SenSoapConstants.h>
_LIT8(KSenSoap12ContentTypeHeaderValue, "application/soap+xml; charset=\"UTF-8\"");
_LIT8(KSenSoap12AcceptHeaderValue,      "application/soap+xml");
_LIT8(KSenSoapEnvelopeName,             "Envelope");
_LIT8(KSenSoapEnvelopeQName,            "S:Envelope");

_LIT8(KSenSoapEnvelopeXmlns,            "http://schemas.xmlsoap.org/soap/envelope/");
_LIT8(KSenSoap12EnvelopeXmlns,          "http://www.w3.org/2003/05/soap-envelope");
_LIT8(KSenSoapEnvelopeHeaderName,       "Header");
_LIT8(KSenSoapEnvelopeHeaderQName,      "S:Header");
_LIT8(KSenSoapEnvelopeBodyName,         "Body");
_LIT8(KSenSoapEnvelopeBodyQName,        "S:Body");
_LIT8(KSenSoapFaultName,                "Fault");

_LIT8(KSenSoapActionHeaderName,         "SOAPAction");
_LIT8(KSenSoapActionHeaderValueEmpty,   "\"\"");


const TInt KStateParsingSoapHeader  = 20; // ignore state   (even number)
const TInt KStateParsingSoapBody    = 40; // ignore state   (even number)
const TInt KStateParsingSoapFault   = 5;  // save state     (odd number)

enum TSOAPVersion
        {
        ESOAP11 = 1,
        ESOAP12
        };
*/

// FORWARD DECLARATIONS
class CSenSoapFault;

// CLASS DECLARATION

/**
* CSenSoapEnvelope is an utility class offering capability to parse
* XML SOAP envelope and manipulation methods to alter its contents.
* Typically WSC uses this class to parse messages received through
* WSF HandleMessageL() and HandleErrorL() callbacks.
* Class has convenience methods for checking if a SOAP envelope body
* contains a fault and functionality to detach SOAP Fault object out
* from it. Also possibility to set SOAPAction HTTP header is supported.
*  @lib SenUtils.lib
*  @since Series60 3.0
*/
class CSenSoapEnvelope : public CSenBaseFragment
    {
    public:  // Constructors and destructor
        
        /**
        * Two-phased constructor.
        */
        IMPORT_C static CSenSoapEnvelope* NewL();
        
        /**
        * Destructor.
        */
        IMPORT_C virtual ~CSenSoapEnvelope();

        // New functions
        
        /**
        * Sets body of the envelope.
        * @since Series60 3.0 
        * @param aBody      Body (content) to be set.
        * @return SOAP body (content) which was just set
        */
        IMPORT_C virtual TPtrC8 SetBodyL(const TDesC8& aBody);

        /**
        * Getter for envelopes body
        * @since Series60 3.0 
        * @return body as CSenElement
        */
        IMPORT_C virtual CSenElement& BodyL();

        /**
        * Getter for envelopes header
        * @since Series60 3.0 
        * @return header as CSenElement
        */
        IMPORT_C virtual CSenElement& HeaderL();

        /**
        * Adds an element to the header.
        * @since Series60 3.0 
        * @param aHeaderElement new child element to be
        *        added inside Header  element. Ownership
        *        is always transferred to CSenSoapEnvelope.
        * @return added CSenElement
        */
        IMPORT_C virtual CSenElement& AddHeaderL(CSenElement& aHeaderElement);

        /**
        * Getter for the envelope body as a UTF-8 form XML string.
        * @since Series60 3.0 
        * @return body as a HBufC8 pointer. Ownership is transferred to caller.
        */
        IMPORT_C virtual HBufC8* BodyAsStringL();

        /**
        * Checks if this SOAP envelope body contains SOAP fault or not.
        * @since Series60 3.0 
        * @return TBool ETrue if there is a fault, EFalse if not.
        */
        IMPORT_C virtual TBool IsFault();

        /**
        * Detaches the <Fault> element from the envelope, removing the element
        * from the envelope.
        * @since Series60 3.0 
        * @return pointer to the soap fault. Caller takes the ownership. 
        *         NULL if <Fault> element is non-existent.
        */
        IMPORT_C virtual CSenSoapFault* DetachFaultL();
        
        /**
        * Gets the <Fault> element. Ownership is not transferred. 
        * NULL if not a fault.
        * @since Series60 3.0 
        * @return reference to SOAP fault object owned by this SOAP envelope
        */
        IMPORT_C virtual CSenSoapFault* FaultL();

        /**
        * Sets the SOAP action HTTP header. WSF will use this value
        * while submitting this SOAP envelope request over HTTP/S transport.
        * @since Series60 3.0 
        * @param aSoapAction    the SOAP Action HTTP header to be set.
        * The default value is KSenSoapActionHeaderValueEmpty, which is
        * two double quotation marks - "" - without any character in between.
        * SOAP specification requires double quotation marks, even if action
        * is empty.
        * If a string without double quotation marks is passed, it will be 
        * wrapped inside double quotation marks, added in the beginning and 
        * at the end of the actual SOAP Action string.
        *
        * @return newly set SOAP action header. String might have been
        * extended to include double quotation marks, if those were missing 
        * from the argument. 
        */
        IMPORT_C virtual TPtrC8 SetSoapActionL(const TDesC8& aSoapAction);

        /**
        * Gets the soap action header.
        * @since Series60 3.0 
        * @return   current SOAP action header, which is always wrapped
        * inside double quotation marks. If SOAPAction has not been set
        * for this SOAP envelope, function will return zero-length 
        * descriptor (KNullDesC8)
        */
        IMPORT_C virtual TPtrC8 SoapAction();      

        /**
        * Gets the soap action header.
        * @since Series60 5.0 
        * @return   current SOAP action header, which is always wrapped
        * inside double quotation marks. If SOAPAction has not been set
        * for this SOAP envelope, function will return zero-length 
        * descriptor (KNullDesC8)
        */
			IMPORT_C TPtrC8 SoapAction2() ;
        
        /**
        * Method parses given piece of XML into this SOAP envelope
        */
        IMPORT_C void ParseL(const TDesC8& aXml); 

        /*
        * Getter for checking whether this message has at least one
        * valid <Header> element
        * @return ETrue, if <Header> element exists, EFalse otherwise.
        */
        IMPORT_C TBool HasHeader();

        /*
        * Getter for checking whether this message has valid <Body> element
        * @return ETrue, if <Body> element exists, EFalse otherwise.
        */
        IMPORT_C TBool HasBody();

        /**
        * Getter for currently effecitve SOAP version.
        * @return enumeration which dictates SOAP version.
        */
        IMPORT_C TSOAPVersion SoapVersion();


    protected:  
            
        /**
         *    Constructor.
         */
        CSenSoapEnvelope();
        
        /**
        * This method should be called from the deriving
        * classes ConstructL() methods. 
        * @since Series60 3.0
        */
        IMPORT_C void BaseConstructL(TSOAPVersion aVersion);

        /**
        * This method should be called from the deriving
        * classes ConstructL() methods. 
        * @since Series60 3.0
        */
        IMPORT_C void BaseConstructL();
        
        // New functions
        
        /**
        * This method should be overridden by subclasses. 
        * Implements functionality to parse SOAP header if one is found
        * during parsing the envelope.
        * Parses all elements found under top <Header> element by
        * using DOM fragment.
        * @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 aAttributes    The attributes of the new element
        */
        IMPORT_C virtual void ParseHeaderL( const TDesC8& aNsUri,
                                            const TDesC8& aLocalName,
                                            const TDesC8& aQName,
                                            const RAttributeArray& aAttributes);
                                            
        // Functions from base classes
        
        // From CSenBaseFragment 
        
        /**
        * Callback function which implement the XML content handler interface.
        * This callback will occur on each start element tag found in the XML
        * document.
        * The SOAP envelope recognizes and parses the following elements and
        * their corresponding attributes inside namespace defined in 
        * KSenSoapEnvelopeXmlns:
        *  KSenSoapEnvelopeName,    "Envelope"
        *  KSenSoapHeaderName,      "Header"
        *  KSenSoapBodyName,        "Body"
        *  KSenSoapFault,           "Fault" (only if found inside Body element)
        *
        * @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 aAttributes    The attributes of the new element
        */
        IMPORT_C virtual void StartElementL(const TDesC8& aNsUri,
                                            const TDesC8& aLocalName,
                                            const TDesC8& aQName,
                                            const RAttributeArray& aAttributes);

        /**
        * Callback function which implement the XML content handler interface.
        * This callback will occur on each end element tag found in the XML
        * document.
        * @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);

    protected: // Data
        // Internal members, protected so that deriving classes have access to them.
        CSenBaseFragment* ipBodyFragment;
        CSenBaseFragment* ipHeaderFragment;
        HBufC8* ipSoapAction;

    private: // Data
        TBool iFault;
       };

#endif // SEN_SOAP_ENVELOPE_H

// End of File