00001 /* 00002 * ============================================================================== 00003 * Name : SenServiceConnection.h 00004 * Part of : Web Services Connection 00005 * Interface : 00006 * Description : CSenServiceConnection offers public API for 00007 * service consumers to access invocable services, 00008 * as a part of the Web Services Framework (WSF). 00009 * Version : 00010 * 00011 * Copyright © 2002-2005 Nokia. All rights reserved. 00012 * This material, including documentation and any related 00013 * computer programs, is protected by copyright controlled by 00014 * Nokia. All rights are reserved. Copying, including 00015 * reproducing, storing, adapting or translating, any 00016 * or all of this material requires the prior written consent of 00017 * Nokia. This material also contains confidential 00018 * information which may not be disclosed to others without the 00019 * prior written consent of Nokia. 00020 * ============================================================================== 00021 */ 00022 00023 #ifndef SEN_SERVICE_CONNECTION_H 00024 #define SEN_SERVICE_CONNECTION_H 00025 00026 // INCLUDES 00027 #include <e32base.h> // for CActive 00028 00029 #include <MSenServiceConsumer.h> 00030 #include <MSenServiceDescription.h> 00031 #include <SenSoapEnvelope.h> 00032 #include <SenFragment.h> 00033 00034 // CONSTANTS 00035 const TInt KErrSenNotInitialized = -30291; 00036 const TInt KErrSenServiceConnectionBusy = -30292; 00037 const TInt KErrConnectionInitializing = -30293; 00038 const TInt KErrConnectionExpired = -30294; 00039 const TInt KErrSubmitting = -30295; 00040 const TInt KErrSenSoapFault = -30296; 00041 const TInt KErrSenInternal = -30297; 00042 const TInt KErrSenNoEndpoint = -30298; 00043 const TInt KErrSenNoContract = -30299; 00044 const TInt KErrSenProviderIdInUseByAnotherEndpoint = -30305; 00045 const TInt KErrSenNoContractNoEndPoint = -30306; 00046 const TInt KSenConnectionStatusNew = 0; 00047 const TInt KSenConnectionStatusReady = 1; 00048 const TInt KSenConnectionStatusExpired = 2; 00049 00050 _LIT8(KDefaultBasicWebServicesFrameworkID, "WS-I"); 00051 00052 _LIT8(KDefaultIdWsfFrameworkID, "ID-WSF"); 00053 00054 // FORWARD DECLARATIONS 00055 class CSenServicePattern; 00056 00057 // CLASS DECLARATION 00058 00112 class CSenServiceConnection : public CActive, public MSenFragment 00113 { 00114 public: // Constructors and destructor 00115 00151 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer, 00152 const TDesC8& aContract); 00153 00188 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver, 00189 const TDesC8& aContract); 00190 00210 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver, 00211 MSenServiceDescription& aServiceDescription); 00212 00234 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver, 00235 MSenServiceDescription& aServiceDescription); 00236 00237 /* 00238 * The ServicePattern version of two phased constructor. 00239 * Note, that this method is intended to be used by service consumers 00240 * wishing to initialize connection in specific context called 00241 * consumer policy. In consumer policy, certain properties 00242 * can be set to further define what kind of connection is acceptable 00243 * and how the connection interacts with transport (for example, which 00244 * Internet Access Point (IAP) will be used). 00245 * However, any ConsumerPolicy feature is applicable in 00246 * one-policy-per-client scope and not used as a common policy. 00247 * To set permanent information about known WSP, please use the 00248 * CSenXmlServiceDescription, which implements MSenProviderPolicy 00249 * interface. 00250 * This constructor is ASYNCHRONOUS and the actual state of 00251 * created connection has to be observed from SetStatus() and 00252 * HandleErrorL() functions. 00253 * If service is found, the SetStatus() call-back is executed 00254 * with a status value KSenConnectionStatusReady (1) 00255 * For ID-WSF connections, the authentication for the Web Service 00256 * Provider (WSP) connection is resolved using one of the identity 00257 * providers which have been associated with the contract found in 00258 * the SD. At minimum, the contract of the service (typically some URN) 00259 * has to provided in the SD. 00260 * Basic Web Service consumers instantiate a SD where an endpoint 00261 * and framework ID KDefaultBasicWebServicesFrameworkID are defined. 00262 * @param aObserver connection observer. 00263 * @param aServiceDescription is the description used to 00264 * obtain a service connection. 00265 * @return a pointer to a CSenServiceConnection instance. 00266 */ 00267 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver, 00268 CSenServicePattern& aServicePattern); 00269 00270 /* 00271 * The ServicePattern version of two phased constructor. 00272 * Note, that this method is intended to be used by service consumers 00273 * wishing to initialize connection in specific context called 00274 * consumer policy. In consumer policy, certain properties 00275 * can be set to further define what kind of connection is acceptable 00276 * and how the connection interacts with transport (for example, which 00277 * Internet Access Point (IAP) will be used). 00278 * However, any ConsumerPolicy feature is applicable in 00279 * one-policy-per-client scope and not used as a common policy. 00280 * To set permanent information about known WSP, please use the 00281 * CSenXmlServiceDescription, which implements MSenProviderPolicy 00282 * interface. 00283 * This constructor is ASYNCHRONOUS and the actual state of 00284 * created connection has to be observed from SetStatus() and 00285 * HandleErrorL() functions. 00286 * If service is found, the SetStatus() call-back is executed 00287 * with a status value KSenConnectionStatusReady (1) 00288 * For ID-WSF connections, the authentication for the Web Service 00289 * Provider (WSP) connection is resolved using one of the identity 00290 * providers which have been associated with the contract found in 00291 * the SD. At minimum, the contract of the service (typically some URN) 00292 * has to provided in the SD. 00293 * Basic Web Service consumers instantiate a SD where an endpoint 00294 * and framework ID KDefaultBasicWebServicesFrameworkID are defined. 00295 * @param aObserver connection observer. 00296 * @param aServiceDescription is the description used to 00297 * obtain a service connection. 00298 * @return a pointer to a CSenServiceConnection instance. 00299 * The pointer is left on the cleanup stack. 00300 */ 00301 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver, 00302 CSenServicePattern& aServicePattern); 00303 00304 // New functions 00305 00334 virtual TInt SendL(const TDesC8& aRequest) = 0; 00335 00368 virtual TInt SubmitL(const TDesC8& aRequest, HBufC8*& aResponse) = 0; 00369 00381 virtual TInt IsReady(TBool& aReady) = 0; 00382 00416 virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0; 00417 00448 virtual TInt CompleteServerMessagesOnOff(const TBool& aCompleteOnOff) = 0; 00449 00450 /* 00451 * Sends a SOAP message to the service. The SOAP envelope may contain 00452 * proprietary headers. The system will augment the message with the 00453 * appropriate headers specified in the service invocation framework, 00454 * so a client application should add only non-standard headers; and 00455 * if it doesn't need to set such headers it is strongly recommended 00456 * to use SendL(TDesC8&), which is meant for this. 00457 * This is an asynchronous function, that returns immediately. 00458 * When the service responds, the SOAP envelope content will 00459 * be received via HandleMessageL() callback. In case of an 00460 * error - like a SOAP fault - HandleErrorL() will be called 00461 * with appropriate error code. 00462 * There are two default frameworks available - 00463 * the Identity Based Web Service Framework (which ID is "ID-WSF") 00464 * and the Basic Web Services Framework (which ID is "WS-I"). 00465 * Please note, that ID-WSF does NOT support this method. 00466 * Instead, one should send SOAP envelope Bodies using 00467 * SendL(const TDesC8&). 00468 * So, currently this method is supported only in Basic Web Services framework. 00469 * @param aMessage The service specific message - a full SOAP envelope 00470 * @return status/error code. 00471 * Status codes: 00472 * KErrNone ok 00473 * Error codes: 00474 * KErrSenNotInitialized Connection has not been initialized. 00475 * KErrSenServiceConnectionBusy Connection is already busy with another 00476 * request. 00477 * KErrConnectionInitializing Connection is still initializing and 00478 * cannot yet process commands. 00479 * KErrConnectionExpired Connection is expired and needs to be 00480 * renewed. 00481 * KErrSubmitting An internal error has occurred. 00482 * KErrNoMemory Not enough memory to process the 00483 * message. 00484 * Other error codes are system-wide Symbian error codes. 00485 */ 00486 virtual TInt SendL(CSenSoapEnvelope& aMessage) = 0; 00487 00488 /* 00489 * Submits a SOAP message to the service. This is a synchronous call, 00490 * returning a SOAP envelope that was received from the service. 00491 * There are two default frameworks available: 00492 * the Identity Based Web Service Framework (which ID is "ID-WSF") 00493 * and the Basic Web Services Framework (which ID is "WS-I"). 00494 * Please note, that ID-WSF does NOT support this method. 00495 * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&). 00496 * So, currently this method is supported only in Basic Web Services framework. 00497 * @param aMessage SOAPEnvelope with the service specific message 00498 * without any framework wrapping 00499 * @param aResponseTo This is a ref-to-pointer where response 00500 * from the service will be allocated. If the 00501 * complete server messages mode is set to OFF, 00502 * then only <Body> element will be returned, 00503 * otherwise a complete SOAP envelope. 00504 * The ownership of aResponse is transfered to 00505 * the caller. 00506 * @return status/error code 00507 * Status codes: 00508 * KErrNone ok 00509 * Error codes: 00510 * KErrSenNotInitialized Connection has not been initialized. 00511 * KErrSenServiceConnectionBusy Connection is already busy with another 00512 * request. 00513 * KErrConnectionInitializing Connection is still initializing and 00514 * cannot yet process commands. 00515 * KErrConnectionExpired Connection is expired and needs to be 00516 * renewed. 00517 * KErrSubmitting An internal error has occurred. 00518 * KErrNoMemory Not enough memory to process the 00519 * message. 00520 * KErrSenInternal Internal state is invalid. 00521 * Other error codes are system-wide Symbian error codes. 00522 */ 00523 virtual TInt SubmitL(CSenSoapEnvelope& aMessage, HBufC8*& aResponseTo) = 0; 00524 00544 virtual TInt ServiceDescriptionL(HBufC8*& aServiceDescription) = 0; 00545 00555 virtual TInt StartTransaction() = 0; 00556 00564 virtual TInt TransactionCompleted() = 0; 00565 00566 protected: 00567 00571 CSenServiceConnection(); 00572 00573 }; 00574 00575 //SEN_SERVICE_CONNECTION_H 00576 #endif 00577 00578 // End of File 00579