1 /*

     2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:        CSenSoapEnvelope is an utility class offering capability to

    15 *                parse XML SOAP envelope and manipulation methods to alter its

    16 *                contents.

    17 *

    18 */

    19 

    20 

    21 

    22 

    23 

    24 

    25 

    26 

    27 #ifndef SEN_SOAP_ENVELOPE2_H

    28 #define SEN_SOAP_ENVELOPE2_H

    29 

    30 //  INCLUDES

    31 #include <SenDomFragmentBase.h>

    32 #include <SenSoapConstants.h>

    33 #include <MSenMessage.h>

    34 

    35 // CONSTANTS

    36 /*

    37 // Now declared in <SenSoapConstants.h>

    38 _LIT8(KSenSoapEnvelopeName,    	        "Envelope");

    39 _LIT8(KSenSoapEnvelopePrefix,   	    "S");

    40 _LIT8(KSenSoapEnvelopeXmlns,            "http://schemas.xmlsoap.org/soap/envelope/");

    41 _LIT8(KSenSoap12EnvelopeXmlns,          "http://www.w3.org/2003/05/soap-envelope");

    42 _LIT8(KSenSoapEnvelopeHeaderName,       "Header");

    43 _LIT8(KSenSoapEnvelopeHeaderQName,      "S:Header");

    44 _LIT8(KSenSoapEnvelopeBodyName,         "Body");

    45 _LIT8(KSenSoapEnvelopeBodyQName,        "S:Body");

    46 _LIT8(KSenSoapFaultName,                "Fault");

    47 

    48 _LIT8(KSenSoapActionHeaderName,         "SOAPAction");

    49 _LIT8(KSenSoapActionHeaderValueEmpty,   "\"\"");

    50 

    51 const TInt KStateParsingSoapHeader  = 20; // ignore state   (even number)

    52 const TInt KStateParsingSoapBody    = 40; // ignore state   (even number)

    53 const TInt KStateParsingSoapFault   = 5;  // save state     (odd number)

    54 

    55 enum TSOAPVersion

    56 		{

    57 		ESOAP11 = 1,

    58 		ESOAP12

    59 		};

    60 */

    61 

    62 // FORWARD DECLARATIONS

    63 class CSenSoapFault2;

    64 class CSenTransportProperties;

    65 class CSenMessageContext;

    66 class MSenMessageContext;

    67 

    68 // CLASS DECLARATION

    69 

    70 /**

    71 * CSenSoapEnvelope is an utility class offering capability to parse

    72 * XML SOAP envelope and manipulation methods to alter its contents.

    73 * Typically WSC uses this class to parse messages received through

    74 * WSF HandleMessageL() and HandleErrorL() callbacks.

    75 * Class has convenience methods for checking if a SOAP envelope body

    76 * contains a fault and functionality to detach SOAP Fault object out

    77 * from it. Also possibility to set SOAPAction HTTP header is supported.

    78 *  @lib SenUtils.lib

    79 *  @since Series60 4.0

    80 */

    81 class CSenSoapEnvelope2 : public CSenFragmentBase, public MSenMessage

    82     {

    83     public:  // Constructors and destructor

    84 

    85         /**

    86         * Two-phased constructor.

    87         */

    88         IMPORT_C static CSenSoapEnvelope2* NewL();

    89 

    90         /**

    91         * Two-phased constructor.

    92         */

    93         IMPORT_C static CSenSoapEnvelope2* NewLC();

    94 

    95         /**

    96         * Two-phased constructor.

    97         */

    98         IMPORT_C static CSenSoapEnvelope2* NewL(MSenMessageContext& aContext);

    99 

   100         /**

   101         * Two-phased constructor.

   102         */

   103         IMPORT_C static CSenSoapEnvelope2* NewLC(MSenMessageContext& aContext);

   104 

   105         /**

   106         * Two-phased copy constructor.

   107         */

   108         IMPORT_C static CSenSoapEnvelope2* NewL(CSenSoapEnvelope2& aEnvelope);

   109 

   110         /**

   111         * Two-phased copy constructor.

   112         */

   113         IMPORT_C static CSenSoapEnvelope2* NewLC(CSenSoapEnvelope2& aEnvelope);

   114 

   115         /**

   116         * Destructor.

   117         */

   118         IMPORT_C virtual ~CSenSoapEnvelope2();

   119 

   120         // New functions

   121 

   122         /**

   123         * Sets body of the envelope.

   124         * @since Series60 4.0

   125         * @param aBody      Body (content) to be set.

   126         * @return SOAP body (content) which was just set

   127         */

   128         IMPORT_C virtual TPtrC8 SetBodyL(const TDesC8& aBody);

   129 

   130         /**

   131         * Sets body of the envelope.

   132         * @since Series60 4.0

   133         * @param aBody      Body (content) to be set.

   134         * @return SOAP body (content) which was just set

   135         */

   136         IMPORT_C virtual TXmlEngElement SetBodyL(TXmlEngElement aBodyElement);

   137 

   138         /**

   139         * Getter for envelopes body

   140         * @since Series60 4.0

   141         * @return body as TXmlEngElement

   142         */

   143         IMPORT_C virtual TXmlEngElement BodyL();

   144 

   145         /**

   146         * Getter for envelopes header

   147         * @since Series60 4.0

   148         * @return header as TXmlEngElement

   149         */

   150         IMPORT_C virtual TXmlEngElement HeaderL();

   151 

   152         /**

   153         * Adds an element to the header.

   154         * @since Series60 4.0

   155         * @param aHeaderElement new child element to be

   156         *        added inside Header  element. Ownership

   157         *        is always transferred to CSenSoapEnvelope.

   158         * @return added TXmlEngElement

   159         */

   160         IMPORT_C virtual TXmlEngElement AddHeaderL(TXmlEngElement aHeaderElement);

   161 

   162         /**

   163         * Getter for the envelope body as a UTF-8 form XML string.

   164         * @since Series60 4.0

   165         * @return body as a HBufC8 pointer. Ownership is transferred to caller.

   166         */

   167         IMPORT_C virtual HBufC8* BodyAsStringL();

   168 

   169         /**

   170         * Checks if this SOAP envelope body contains SOAP fault or not.

   171         * @since Series60 4.0

   172         * @return TBool ETrue if there is a fault, EFalse if not.

   173         */

   174         IMPORT_C virtual TBool IsFault();

   175 

   176         /**

   177         * Detaches the <Fault> element from the envelope, removing the element

   178         * from the envelope.

   179         * @since Series60 4.0

   180         * @return pointer to the soap fault. Caller takes the ownership.

   181         *         NULL if <Fault> element is non-existent.

   182         */

   183         IMPORT_C virtual CSenSoapFault2* DetachFaultL();

   184 

   185         /**

   186         * Gets the <Fault> element. Ownership is not transferred.

   187         * NULL if not a fault.

   188         * @since Series60 4.0

   189         * @return reference to SOAP fault object owned by this SOAP envelope

   190         */

   191         IMPORT_C virtual CSenSoapFault2* FaultL();

   192 

   193         /**

   194         * Sets the SOAP action HTTP header. WSF will use this value

   195         * while submitting this SOAP envelope request over HTTP/S transport.

   196         * @since Series60 4.0

   197         * @param aSoapAction    the SOAP Action HTTP header to be set.

   198         * The default value is KSenSoapActionHeaderValueEmpty, which is

   199         * two double quotation marks - "" - without any character in between.

   200         * SOAP specification requires double quotation marks, even if action

   201         * is empty.

   202         * If a string without double quotation marks is passed, it will be

   203         * wrapped inside double quotation marks, added in the beginning and

   204         * at the end of the actual SOAP Action string.

   205         *

   206         * @return newly set SOAP action header. String might have been

   207         * extended to include double quotation marks, if those were missing

   208         * from the argument.

   209         */

   210         IMPORT_C virtual TPtrC8 SetSoapActionL(const TDesC8& aSoapAction);

   211 

   212         /**

   213         * Gets the soap action header.

   214         * @since Series60 4.0

   215         * @return   current SOAP action header, which is always wrapped

   216         * inside double quotation marks. If SOAPAction has not been set

   217         * to this SOAP envelope instance, function will return zero-length

   218         * descriptor (KNullDesC8)

   219         */

   220         IMPORT_C virtual TPtrC8 SoapAction();

   221 

   222         /*

   223         * Getter for checking whether this message has at least one

   224         * valid <Header> element

   225         * @return ETrue, if <Header> element exists, EFalse otherwise.

   226         */

   227         IMPORT_C TBool HasHeader();

   228 

   229         /*

   230         * Getter for checking whether this message has valid <Body> element

   231         * @return ETrue, if <Body> element exists, EFalse otherwise.

   232         */

   233         IMPORT_C TBool HasBody();

   234         

   235         /**

   236         * Getter for currently effecitve SOAP version.

   237         * @return enumeration which dictates SOAP version.

   238         */

   239         IMPORT_C virtual TSOAPVersion SoapVersion();

   240 

   241     public: // From MSenMessage

   242         IMPORT_C virtual TClass Type();

   243         IMPORT_C virtual TDirection Direction();

   244         IMPORT_C virtual TInt SetContext(MSenMessageContext* apOwnedContext);

   245         IMPORT_C virtual MSenMessageContext* Context();

   246         IMPORT_C virtual TInt SetProperties(MSenProperties* apOwnedProperties);

   247         IMPORT_C virtual MSenProperties* Properties();

   248 

   249         IMPORT_C virtual TBool IsSafeToCast(TClass aType);

   250         IMPORT_C virtual TInt TxnId();

   251 		IMPORT_C virtual MSenMessage* CloneL();

   252 

   253     protected:

   254 

   255         /**

   256          *  Constructor.

   257          */

   258         CSenSoapEnvelope2();

   259 		/**

   260 		* This method should be called from the deriving

   261 		* classes ConstructL() methods.

   262 	    * @since Series60 4.0

   263 		*/

   264 	    IMPORT_C void BaseConstructL(TSOAPVersion aVersion);

   265 

   266         /**

   267         * This method should be called from the deriving

   268         * classes ConstructL() methods.

   269         * @since Series60 4.0

   270         */

   271         IMPORT_C void BaseConstructL();

   272 

   273         /**

   274         * This method should be called from the deriving

   275         * classes ConstructL() methods.

   276         * @since Series60 4.0

   277         */

   278         IMPORT_C void BaseConstructL(MSenMessageContext& aMessage);

   279 

   280         /**

   281         * This method should be called from the deriving

   282         * classes ConstructL() methods.

   283         * @since Series60 4.0

   284         */

   285         IMPORT_C void BaseConstructL(MSenMessageContext& aMessage,

   286                                      TSOAPVersion aVersion);

   287 

   288         /**

   289         * This method should be called from the deriving

   290         * classes ConstructL() methods.

   291         * @since Series60 4.0

   292         */

   293         IMPORT_C void BaseConstructL(CSenSoapEnvelope2& aEnvelope);

   294 

   295         // New functions

   296 

   297         /**

   298         * This method should be overridden by subclasses.

   299         * Implements functionality to parse SOAP header if one is found

   300         * during parsing the envelope.

   301         * Parses all elements found under top <Header> element by

   302         * using DOM fragment.

   303         * @since Series60 4.0

   304         * @param aNsUri         The namespace URI of the new element

   305         * @param aLocalName     The local name of the new element

   306         * @param aQName         The qualified name of the new element

   307         * @param aAttributes    The attributes of the new element

   308         */

   309         IMPORT_C virtual void ParseHeaderL(const RTagInfo& aElement,

   310                                            const RAttributeArray& aAttributes);

   311 

   312         // Functions from base classes

   313 

   314         // From CSenFragmentBase

   315         IMPORT_C virtual void OnStartElementL(const RTagInfo& aElement,

   316     	                                      const RAttributeArray& aAttributes,

   317     	                                      TInt aErrorCode);                                            

   318 

   319         IMPORT_C virtual void OnEndElementL(const RTagInfo& aElement,

   320                                             TInt aErrorCode);

   321 

   322         IMPORT_C virtual CSenFragmentBase* CreateBodyFragmentL(const TDesC8& aNsUri,

   323                                                        const TDesC8& aLocalName,

   324                                                        const TDesC8& aPrefix,

   325                                                        const RAttributeArray& aAttributes,

   326                                                        TXmlEngElement& aParent,

   327                                                        RSenDocument& aOwnerDocument);

   328 

   329     protected: // Data

   330         // Internal members, protected so that deriving classes have access to them.

   331         CSenFragmentBase*           ipBodyFragment;

   332         CSenFragmentBase*           ipHeaderFragment;

   333         HBufC8*                     ipSoapAction;

   334         TInt                        iTransactionId;

   335 

   336         MSenProperties*             ipProperties;      // owned => safe upward cast is performed in de-alloc

   337         MSenMessageContext*         ipNotOwnedContext; // owned => safe upward cast is performed in de-alloc

   338         

   339         TAny* ipReserved;

   340 

   341         TBool               iFault;

   342         TDirection          iDirection;

   343     };

   344 

   345 #endif // SEN_SOAP_ENVELOPE_H

   346 

   347 // End of File

   348 

   349 

   350