1.1 --- a/epoc32/include/mw/sensoapenvelope2.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/sensoapenvelope2.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,350 @@
1.4 -sensoapenvelope2.h
1.5 +/*
1.6 +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: CSenSoapEnvelope is an utility class offering capability to
1.19 +* parse XML SOAP envelope and manipulation methods to alter its
1.20 +* contents.
1.21 +*
1.22 +*/
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +
1.30 +
1.31 +#ifndef SEN_SOAP_ENVELOPE2_H
1.32 +#define SEN_SOAP_ENVELOPE2_H
1.33 +
1.34 +// INCLUDES
1.35 +#include <SenDomFragmentBase.h>
1.36 +#include <SenSoapConstants.h>
1.37 +#include <MSenMessage.h>
1.38 +
1.39 +// CONSTANTS
1.40 +/*
1.41 +// Now declared in <SenSoapConstants.h>
1.42 +_LIT8(KSenSoapEnvelopeName, "Envelope");
1.43 +_LIT8(KSenSoapEnvelopePrefix, "S");
1.44 +_LIT8(KSenSoapEnvelopeXmlns, "http://schemas.xmlsoap.org/soap/envelope/");
1.45 +_LIT8(KSenSoap12EnvelopeXmlns, "http://www.w3.org/2003/05/soap-envelope");
1.46 +_LIT8(KSenSoapEnvelopeHeaderName, "Header");
1.47 +_LIT8(KSenSoapEnvelopeHeaderQName, "S:Header");
1.48 +_LIT8(KSenSoapEnvelopeBodyName, "Body");
1.49 +_LIT8(KSenSoapEnvelopeBodyQName, "S:Body");
1.50 +_LIT8(KSenSoapFaultName, "Fault");
1.51 +
1.52 +_LIT8(KSenSoapActionHeaderName, "SOAPAction");
1.53 +_LIT8(KSenSoapActionHeaderValueEmpty, "\"\"");
1.54 +
1.55 +const TInt KStateParsingSoapHeader = 20; // ignore state (even number)
1.56 +const TInt KStateParsingSoapBody = 40; // ignore state (even number)
1.57 +const TInt KStateParsingSoapFault = 5; // save state (odd number)
1.58 +
1.59 +enum TSOAPVersion
1.60 + {
1.61 + ESOAP11 = 1,
1.62 + ESOAP12
1.63 + };
1.64 +*/
1.65 +
1.66 +// FORWARD DECLARATIONS
1.67 +class CSenSoapFault2;
1.68 +class CSenTransportProperties;
1.69 +class CSenMessageContext;
1.70 +class MSenMessageContext;
1.71 +
1.72 +// CLASS DECLARATION
1.73 +
1.74 +/**
1.75 +* CSenSoapEnvelope is an utility class offering capability to parse
1.76 +* XML SOAP envelope and manipulation methods to alter its contents.
1.77 +* Typically WSC uses this class to parse messages received through
1.78 +* WSF HandleMessageL() and HandleErrorL() callbacks.
1.79 +* Class has convenience methods for checking if a SOAP envelope body
1.80 +* contains a fault and functionality to detach SOAP Fault object out
1.81 +* from it. Also possibility to set SOAPAction HTTP header is supported.
1.82 +* @lib SenUtils.lib
1.83 +* @since Series60 4.0
1.84 +*/
1.85 +class CSenSoapEnvelope2 : public CSenFragmentBase, public MSenMessage
1.86 + {
1.87 + public: // Constructors and destructor
1.88 +
1.89 + /**
1.90 + * Two-phased constructor.
1.91 + */
1.92 + IMPORT_C static CSenSoapEnvelope2* NewL();
1.93 +
1.94 + /**
1.95 + * Two-phased constructor.
1.96 + */
1.97 + IMPORT_C static CSenSoapEnvelope2* NewLC();
1.98 +
1.99 + /**
1.100 + * Two-phased constructor.
1.101 + */
1.102 + IMPORT_C static CSenSoapEnvelope2* NewL(MSenMessageContext& aContext);
1.103 +
1.104 + /**
1.105 + * Two-phased constructor.
1.106 + */
1.107 + IMPORT_C static CSenSoapEnvelope2* NewLC(MSenMessageContext& aContext);
1.108 +
1.109 + /**
1.110 + * Two-phased copy constructor.
1.111 + */
1.112 + IMPORT_C static CSenSoapEnvelope2* NewL(CSenSoapEnvelope2& aEnvelope);
1.113 +
1.114 + /**
1.115 + * Two-phased copy constructor.
1.116 + */
1.117 + IMPORT_C static CSenSoapEnvelope2* NewLC(CSenSoapEnvelope2& aEnvelope);
1.118 +
1.119 + /**
1.120 + * Destructor.
1.121 + */
1.122 + IMPORT_C virtual ~CSenSoapEnvelope2();
1.123 +
1.124 + // New functions
1.125 +
1.126 + /**
1.127 + * Sets body of the envelope.
1.128 + * @since Series60 4.0
1.129 + * @param aBody Body (content) to be set.
1.130 + * @return SOAP body (content) which was just set
1.131 + */
1.132 + IMPORT_C virtual TPtrC8 SetBodyL(const TDesC8& aBody);
1.133 +
1.134 + /**
1.135 + * Sets body of the envelope.
1.136 + * @since Series60 4.0
1.137 + * @param aBody Body (content) to be set.
1.138 + * @return SOAP body (content) which was just set
1.139 + */
1.140 + IMPORT_C virtual TXmlEngElement SetBodyL(TXmlEngElement aBodyElement);
1.141 +
1.142 + /**
1.143 + * Getter for envelopes body
1.144 + * @since Series60 4.0
1.145 + * @return body as TXmlEngElement
1.146 + */
1.147 + IMPORT_C virtual TXmlEngElement BodyL();
1.148 +
1.149 + /**
1.150 + * Getter for envelopes header
1.151 + * @since Series60 4.0
1.152 + * @return header as TXmlEngElement
1.153 + */
1.154 + IMPORT_C virtual TXmlEngElement HeaderL();
1.155 +
1.156 + /**
1.157 + * Adds an element to the header.
1.158 + * @since Series60 4.0
1.159 + * @param aHeaderElement new child element to be
1.160 + * added inside Header element. Ownership
1.161 + * is always transferred to CSenSoapEnvelope.
1.162 + * @return added TXmlEngElement
1.163 + */
1.164 + IMPORT_C virtual TXmlEngElement AddHeaderL(TXmlEngElement aHeaderElement);
1.165 +
1.166 + /**
1.167 + * Getter for the envelope body as a UTF-8 form XML string.
1.168 + * @since Series60 4.0
1.169 + * @return body as a HBufC8 pointer. Ownership is transferred to caller.
1.170 + */
1.171 + IMPORT_C virtual HBufC8* BodyAsStringL();
1.172 +
1.173 + /**
1.174 + * Checks if this SOAP envelope body contains SOAP fault or not.
1.175 + * @since Series60 4.0
1.176 + * @return TBool ETrue if there is a fault, EFalse if not.
1.177 + */
1.178 + IMPORT_C virtual TBool IsFault();
1.179 +
1.180 + /**
1.181 + * Detaches the <Fault> element from the envelope, removing the element
1.182 + * from the envelope.
1.183 + * @since Series60 4.0
1.184 + * @return pointer to the soap fault. Caller takes the ownership.
1.185 + * NULL if <Fault> element is non-existent.
1.186 + */
1.187 + IMPORT_C virtual CSenSoapFault2* DetachFaultL();
1.188 +
1.189 + /**
1.190 + * Gets the <Fault> element. Ownership is not transferred.
1.191 + * NULL if not a fault.
1.192 + * @since Series60 4.0
1.193 + * @return reference to SOAP fault object owned by this SOAP envelope
1.194 + */
1.195 + IMPORT_C virtual CSenSoapFault2* FaultL();
1.196 +
1.197 + /**
1.198 + * Sets the SOAP action HTTP header. WSF will use this value
1.199 + * while submitting this SOAP envelope request over HTTP/S transport.
1.200 + * @since Series60 4.0
1.201 + * @param aSoapAction the SOAP Action HTTP header to be set.
1.202 + * The default value is KSenSoapActionHeaderValueEmpty, which is
1.203 + * two double quotation marks - "" - without any character in between.
1.204 + * SOAP specification requires double quotation marks, even if action
1.205 + * is empty.
1.206 + * If a string without double quotation marks is passed, it will be
1.207 + * wrapped inside double quotation marks, added in the beginning and
1.208 + * at the end of the actual SOAP Action string.
1.209 + *
1.210 + * @return newly set SOAP action header. String might have been
1.211 + * extended to include double quotation marks, if those were missing
1.212 + * from the argument.
1.213 + */
1.214 + IMPORT_C virtual TPtrC8 SetSoapActionL(const TDesC8& aSoapAction);
1.215 +
1.216 + /**
1.217 + * Gets the soap action header.
1.218 + * @since Series60 4.0
1.219 + * @return current SOAP action header, which is always wrapped
1.220 + * inside double quotation marks. If SOAPAction has not been set
1.221 + * to this SOAP envelope instance, function will return zero-length
1.222 + * descriptor (KNullDesC8)
1.223 + */
1.224 + IMPORT_C virtual TPtrC8 SoapAction();
1.225 +
1.226 + /*
1.227 + * Getter for checking whether this message has at least one
1.228 + * valid <Header> element
1.229 + * @return ETrue, if <Header> element exists, EFalse otherwise.
1.230 + */
1.231 + IMPORT_C TBool HasHeader();
1.232 +
1.233 + /*
1.234 + * Getter for checking whether this message has valid <Body> element
1.235 + * @return ETrue, if <Body> element exists, EFalse otherwise.
1.236 + */
1.237 + IMPORT_C TBool HasBody();
1.238 +
1.239 + /**
1.240 + * Getter for currently effecitve SOAP version.
1.241 + * @return enumeration which dictates SOAP version.
1.242 + */
1.243 + IMPORT_C virtual TSOAPVersion SoapVersion();
1.244 +
1.245 + public: // From MSenMessage
1.246 + IMPORT_C virtual TClass Type();
1.247 + IMPORT_C virtual TDirection Direction();
1.248 + IMPORT_C virtual TInt SetContext(MSenMessageContext* apOwnedContext);
1.249 + IMPORT_C virtual MSenMessageContext* Context();
1.250 + IMPORT_C virtual TInt SetProperties(MSenProperties* apOwnedProperties);
1.251 + IMPORT_C virtual MSenProperties* Properties();
1.252 +
1.253 + IMPORT_C virtual TBool IsSafeToCast(TClass aType);
1.254 + IMPORT_C virtual TInt TxnId();
1.255 + IMPORT_C virtual MSenMessage* CloneL();
1.256 +
1.257 + protected:
1.258 +
1.259 + /**
1.260 + * Constructor.
1.261 + */
1.262 + CSenSoapEnvelope2();
1.263 + /**
1.264 + * This method should be called from the deriving
1.265 + * classes ConstructL() methods.
1.266 + * @since Series60 4.0
1.267 + */
1.268 + IMPORT_C void BaseConstructL(TSOAPVersion aVersion);
1.269 +
1.270 + /**
1.271 + * This method should be called from the deriving
1.272 + * classes ConstructL() methods.
1.273 + * @since Series60 4.0
1.274 + */
1.275 + IMPORT_C void BaseConstructL();
1.276 +
1.277 + /**
1.278 + * This method should be called from the deriving
1.279 + * classes ConstructL() methods.
1.280 + * @since Series60 4.0
1.281 + */
1.282 + IMPORT_C void BaseConstructL(MSenMessageContext& aMessage);
1.283 +
1.284 + /**
1.285 + * This method should be called from the deriving
1.286 + * classes ConstructL() methods.
1.287 + * @since Series60 4.0
1.288 + */
1.289 + IMPORT_C void BaseConstructL(MSenMessageContext& aMessage,
1.290 + TSOAPVersion aVersion);
1.291 +
1.292 + /**
1.293 + * This method should be called from the deriving
1.294 + * classes ConstructL() methods.
1.295 + * @since Series60 4.0
1.296 + */
1.297 + IMPORT_C void BaseConstructL(CSenSoapEnvelope2& aEnvelope);
1.298 +
1.299 + // New functions
1.300 +
1.301 + /**
1.302 + * This method should be overridden by subclasses.
1.303 + * Implements functionality to parse SOAP header if one is found
1.304 + * during parsing the envelope.
1.305 + * Parses all elements found under top <Header> element by
1.306 + * using DOM fragment.
1.307 + * @since Series60 4.0
1.308 + * @param aNsUri The namespace URI of the new element
1.309 + * @param aLocalName The local name of the new element
1.310 + * @param aQName The qualified name of the new element
1.311 + * @param aAttributes The attributes of the new element
1.312 + */
1.313 + IMPORT_C virtual void ParseHeaderL(const RTagInfo& aElement,
1.314 + const RAttributeArray& aAttributes);
1.315 +
1.316 + // Functions from base classes
1.317 +
1.318 + // From CSenFragmentBase
1.319 + IMPORT_C virtual void OnStartElementL(const RTagInfo& aElement,
1.320 + const RAttributeArray& aAttributes,
1.321 + TInt aErrorCode);
1.322 +
1.323 + IMPORT_C virtual void OnEndElementL(const RTagInfo& aElement,
1.324 + TInt aErrorCode);
1.325 +
1.326 + IMPORT_C virtual CSenFragmentBase* CreateBodyFragmentL(const TDesC8& aNsUri,
1.327 + const TDesC8& aLocalName,
1.328 + const TDesC8& aPrefix,
1.329 + const RAttributeArray& aAttributes,
1.330 + TXmlEngElement& aParent,
1.331 + RSenDocument& aOwnerDocument);
1.332 +
1.333 + protected: // Data
1.334 + // Internal members, protected so that deriving classes have access to them.
1.335 + CSenFragmentBase* ipBodyFragment;
1.336 + CSenFragmentBase* ipHeaderFragment;
1.337 + HBufC8* ipSoapAction;
1.338 + TInt iTransactionId;
1.339 +
1.340 + MSenProperties* ipProperties; // owned => safe upward cast is performed in de-alloc
1.341 + MSenMessageContext* ipNotOwnedContext; // owned => safe upward cast is performed in de-alloc
1.342 +
1.343 + TAny* ipReserved;
1.344 +
1.345 + TBool iFault;
1.346 + TDirection iDirection;
1.347 + };
1.348 +
1.349 +#endif // SEN_SOAP_ENVELOPE_H
1.350 +
1.351 +// End of File
1.352 +
1.353 +
1.354 +