CSenServiceConnection Class Reference

API published in: S60 3rd Ed

Link against: senservconn.lib

Capability Information

Required Capabilities

NetworkServices ReadUserData WriteUserData

#include <senserviceconnection.h>

Inherits MSenFragment.

Detailed Description

The class for connecting to service providers through Web Services Framework (WSF).

The class offers asynchronous construction of a service connection. Further, there are asynchronous and synchronous interaction methods for e.g. sending and receiving data from (possibly remote) service.

WSF offers two default frameworks:

1. Identity Based Web Services Framework (ID-WSF). The framework ID for this is KDefaultIdWsfFrameworkID ("ID-WSF").

2. Basic Web Services Framework. Framework ID is KDefaultBasicWebServicesFrameworkID ("WS-I").

The most typical use of CSenServiceConnection is to interact with a service of certain type through some invocable framework and submitting and receiving messages.

In case of WebServices, the actual service is remote and submitted messages are SOAP envelopes. However, CSenServiceConnection supports accessing any ServiceInvocationFramework which ECOM plug-in implementation is present. These plug-ins may further communicate with some service, including local services.

The link between CSenServiceConnection and any plug-in implementation interacting with some service is the framework ID, which is a property of ServiceDescription (SD) and accessible via MSenServiceDescription interface, which each SD class must implement.

When creating a connection, one offers predefined SD as an argument for asynchronous constructor. Or, optionally only a Liberty Alliance ID-WSF specific contract string

typically some URN. If only contract is offered, then the created connection defaults to ID-WSF service and ID-WSF framework (ID) will be used.

The WSF further uses the offered framework ID while looking up any matching framework plug-in implementation. As a result the SD might be offered to several plug-ins.


Public Member Functions
virtual TInt	SendL (const TDesC8 &aRequest)=0
	Send an ASYNCHRONOUS request to a service.
virtual TInt	SubmitL (const TDesC8 &aRequest, HBufC8 *&aResponse)=0
	Submit a request via SYNCHRONOUS call to a service (in ID-WSF, the SOAP message Body) and receive a response as XML.
virtual TInt	IsReady (TBool &aReady)=0
	Consumer application can use this method to check that service connection is in ready state.
virtual TInt	HasFacetL (const TDesC8 &aURI, TBool &aHasFacet)=0
	Check if the underlying service connection has a certain characteristic called a facet.
virtual TInt	CompleteServerMessagesOnOff (const TBool &aCompleteOnOff)=0
	Consumer application can use this method to set flag which defines whether or not the consumer wishes to receive complete SOAP envelope from the service.
virtual TInt	SendL (CSenSoapEnvelope &aMessage)=0
virtual TInt	SubmitL (CSenSoapEnvelope &aMessage, HBufC8 *&aResponseTo)=0
virtual TInt	ServiceDescriptionL (HBufC8 *&aServiceDescription)=0
	Gets service description of current connection.
virtual TInt	StartTransaction ()=0
	Starts an application level transaction.
virtual TInt	TransactionCompleted ()=0
	Stops application level transaction by resetting the "refToMessageId".
Static Public Member Functions
static IMPORT_C CSenServiceConnection *	NewL (MSenServiceConsumer &aConsumer, const TDesC8 &aContract)
	Two-phased constructor intended for Identity based service consumers (like ID-WSF).
static IMPORT_C CSenServiceConnection *	NewLC (MSenServiceConsumer &aObserver, const TDesC8 &aContract)
	Two-phased constructor intended for Identity based service consumers (like ID-WSF).
static IMPORT_C CSenServiceConnection *	NewL (MSenServiceConsumer &aObserver, MSenServiceDescription &aServiceDescription)
	Two-phased constructor using a service description.
static IMPORT_C CSenServiceConnection *	NewLC (MSenServiceConsumer &aObserver, MSenServiceDescription &aServiceDescription)
	Two-phased constructor using a service description.
static IMPORT_C CSenServiceConnection *	NewL (MSenServiceConsumer &aObserver, CSenServicePattern &aServicePattern)
static IMPORT_C CSenServiceConnection *	NewLC (MSenServiceConsumer &aObserver, CSenServicePattern &aServicePattern)
Protected Member Functions
	CSenServiceConnection ()
	C++ default constructor.

Constructor & Destructor Documentation

CSenServiceConnection::CSenServiceConnection ( ) [protected]

C++ default constructor.

Member Function Documentation

virtual TInt CSenServiceConnection::CompleteServerMessagesOnOff ( const TBool & aCompleteOnOff ) [pure virtual]

Consumer application can use this method to set flag which defines whether or not the consumer wishes to receive complete SOAP envelope from the service.

If complete server messages mode is off, then only the <Body> element is received from the SOAP envelope, otherwise full SOAP envelope. Note: Calling this function must not be done before connection is initialized (the observer's SetStatus() has been called with value KSenConnectionStatusReady). Calling this function should be done before sending or submitting anything.

Parameters:

aCompleteOnOff

defines the content of HandleMessageL() callback. If set to ETrue (ON), then complete SOAP envelopes are received, including <Header> element. If set to EFalse (OFF), only the service specific content - SOAP envelope <Body> element - is received. In WSF frameworks the default settings are: 1. In ID-WSF, the complete server messages is OFF. 2. In Basic Web Services, the default is ON.

Returns:: status/error code. Status codes: KErrNone ok Error codes: KErrSenNotInitialized Connection has not been initialized. KErrConnectionInitializing Connection is still initializing and cannot yet process commands. KErrConnectionExpired Connection is expired and needs to be renewed. Other error codes are system-wide Symbian error codes.

virtual TInt CSenServiceConnection::HasFacetL	(	const TDesC8 &	aURI,
		TBool &	aHasFacet
	)	`[pure virtual]`

Check if the underlying service connection has a certain characteristic called a facet.

Currently, only ID-WSF framework supports facets. For example, if consumer application is interested to resolve if initialized service connection has a facet indicating that service is free of charge (for e.g. "urn:framework.com.free:cost"), the method used to check this would be: _LIT8(KFacetOfFreeService, "urn:some.service.free:cost"); int err = HasFacetL(KFacetOfFreeService, hasFacet);

In the service session of initialed connection, this would be the form of the facet element: <Facet name="urn:framework.com.free:cost">

If there is no facet in the service connection then the element is not present.

Parameters:

	aURI	the name of the facet
	aHasFacet	will indicate if underlying service has a certain characteristic.

Returns:: status/error code. Status codes: KErrNone ok Error codes: KErrSenNotInitialized Connection has not been initialized. KErrConnectionInitializing Connection is still initializing and cannot yet process commands. KErrConnectionExpired Connection is expired and needs to be renewed. KErrBadDescriptor The aUri parameter was an invalid descriptor. Other error codes are system-wide Symbian error codes.

virtual TInt CSenServiceConnection::IsReady ( TBool & aReady ) [pure virtual]

Consumer application can use this method to check that service connection is in ready state.

In ID-WSF, this means that WSF interprets that credentials for the service connection are valid (not expired).

Parameters:

aReady

indicates that the connection is ready to be used.

Returns:: status/error code. Status codes: KErrNone ok Error codes are system-wide Symbian error codes.

static IMPORT_C CSenServiceConnection* CSenServiceConnection::NewL	(	MSenServiceConsumer &	aObserver,
		CSenServicePattern &	aServicePattern
	)	`[static]`

static IMPORT_C CSenServiceConnection* CSenServiceConnection::NewL	(	MSenServiceConsumer &	aObserver,
		MSenServiceDescription &	aServiceDescription
	)	`[static]`

Two-phased constructor using a service description.

This constructor is ASYNCHRONOUS and the actual state of created connection has to be observed from SetStatus() and HandleErrorL() functions. If service is found, the SetStatus() call-back is executed with a status value KSenConnectionStatusReady (1) For ID-WSF connections, the authentication for the Web Service Provider (WSP) connection is resolved using one of the identity providers which have been associated with the contract found in the SD. At minimum, the contract of the service (typically some URN) has to provided in the SD. Basic Web Service consumers instantiate a SD where an endpoint and framework ID KDefaultBasicWebServicesFrameworkID are defined.

Parameters:

	aObserver	connection observer.
	aServiceDescription	is the description used to obtain a service connection.

Returns:: a pointer to a CSenServiceConnection instance.

static IMPORT_C CSenServiceConnection* CSenServiceConnection::NewL	(	MSenServiceConsumer &	aConsumer,
		const TDesC8 &	aContract
	)	`[static]`

Two-phased constructor intended for Identity based service consumers (like ID-WSF).

The pointer is left on the cleanup stack. This constructor is ASYNCHRONOUS and the actual state of created connection has to be observed from SetStatus() AND HandleErrorL() functions. If service is found, the SetStatus() call-back is performed with a status value KSenConnectionStatusReady (1). Contract of the service (typically some URN) is provided. Authentication for the Web Service Provider (WSP) connection is resolved using one of the identity providers which have been associated with this contract (typically an URN).

This constructor is ASYNCHRONOUS and the actual state of newly created connection has to be observed from SetStatus() AND HandleErrorL() functions. If service is found, a SetStatus call-back with value KSenConnectionStatusReady (1) is executed. If some error occurs, HandleErrorL() will be called to inform the creator of this connection (service consumer application)

For example, if service is not found, a system wide error code of -1 is deliver via HandleErrorL() to WSC.

Second example: server response HTTP 501 means, that this error code. 501 will be delivered via HandleErrorL() to WSC. This can happen in ID-WSF connection being initialized, if either Authentication Service (AS) or Discovery Service (DS) cannot be reached.

Parameters:

	aConsumer	(web) service consumer (for call-backs)
	aContract	contract of the service, typically an URI.

Returns:: a pointer to a CSenServiceConnection instance.

static IMPORT_C CSenServiceConnection* CSenServiceConnection::NewLC	(	MSenServiceConsumer &	aObserver,
		CSenServicePattern &	aServicePattern
	)	`[static]`

static IMPORT_C CSenServiceConnection* CSenServiceConnection::NewLC	(	MSenServiceConsumer &	aObserver,
		MSenServiceDescription &	aServiceDescription
	)	`[static]`

Two-phased constructor using a service description.

The pointer is left on the cleanup stack. This constructor is ASYNCHRONOUS and the actual state of created connection has to be observed from SetStatus() AND HandleErrorL() functions. If service is found, the SetStatus() call-back is executed with a status value KSenConnectionStatusReady (1) For ID-WSF connections, the authentication for the Web Service Provider (WSP) connection is resolved using one of the identity providers which have been associated with the contract found in the SD. At minimum, the contract of the service (typically some URN) has to provided in the SD. Basic Web Service consumers instantiate a SD where an endpoint and framework ID KDefaultBasicWebServicesFrameworkID are defined.

Parameters:

	aObserver	connection observer.
	aServiceDescription	is the description used to obtain a service connection.

Returns:: a pointer to a CSenServiceConnection instance. The pointer is left on the cleanup stack.

static IMPORT_C CSenServiceConnection* CSenServiceConnection::NewLC	(	MSenServiceConsumer &	aObserver,
		const TDesC8 &	aContract
	)	`[static]`

Two-phased constructor intended for Identity based service consumers (like ID-WSF).

This constructor is ASYNCHRONOUS and the actual state of created connection has to be observed from SetStatus() and HandleErrorL() functions. If service is found, the SetStatus() call-back is performed with a status value KSenConnectionStatusReady (1). Contract of the service (typically some URN) is provided. Authentication for the Web Service Provider (WSP) connection is resolved using one of the identity providers which have been associated with this contract (typically an URN). This constructor is ASYNCHRONOUS and the actual state of newly created connection has to be observed from SetStatus() AND HandleErrorL() functions. If service is found, a SetStatus call-back with value KSenConnectionStatusReady (1) is executed. If some error occurs, HandleErrorL() will be called to inform the creator of this connection (service consumer application)

For example, if service is not found, a system wide error code of -1 is deliver via HandleErrorL() to WSC.

Parameters:

	aConsumer	(web) service consumer (for call-backs)
	aContract	contract of the service, typically an URI.

Returns:: a pointer to a CSenServiceConnection instance. The pointer is left on the cleanup stack.

virtual TInt CSenServiceConnection::SendL ( CSenSoapEnvelope & aMessage ) [pure virtual]

virtual TInt CSenServiceConnection::SendL ( const TDesC8 & aRequest ) [pure virtual]

Send an ASYNCHRONOUS request to a service.

The request data is either in ID-WSF SOAP Body. Observer will deliver the response message via either HandleMessageL() or HandleErrorL() callback. There are two default frameworks available - the Identity Based Web Service Framework (which ID is "ID-WSF") and the Basic Web Services Framework (which ID is "WS-I"). Please note, that Basic Web Services framework does NOT support this method. Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&). So, currently this method is supported only in ID-WSF.

Parameters:

aRequest

outgoing request message.

Returns:: status/error code. Return codes: KErrNone ok KErrSenNotInitialized Connection has not been initialized. KErrSenServiceConnectionBusy Connection is already busy with another request. KErrConnectionInitializing Connection is still initializing and cannot yet process commands. KErrConnectionExpired Credential for the connection is expired and needs to be renewed. This can be done by instantiating a new ServiceConnection. KErrSubmitting An error occurred KErrNoMemory Not enough memory to process the message. Other error codes are system-wide Symbian error codes.

virtual TInt CSenServiceConnection::ServiceDescriptionL ( HBufC8 *& aServiceDescription ) [pure virtual]

Gets service description of current connection.

Parameters:

aServiceDescription

Contains the service description on return

Returns:: status/error code. Status codes: KErrNone ok Error codes: KErrSenNotInitialized Connection has not been initialized. KErrSenServiceConnectionBusy Connection is already busy with another request. KErrConnectionInitializing Connection is still initializing and cannot yet process commands. KErrConnectionExpired Connection is expired and needs to be renewed. KErrUnderFlow Server side returned invalid service description. KErrUnknown Client-Server request mismatch. Other error codes are system-wide Symbian error codes.

virtual TInt CSenServiceConnection::StartTransaction ( ) [pure virtual]

Starts an application level transaction.

The consumer may now start to communicate with some service withing a chain of correlated messages. When responding to a certain SOAP message inside a transaction, the last received message ID is used as "refToMessageId". From default frameworks, only ID-WSF supports transactions.

Returns:: KErrNone if no errors occur. Other error codes are system-wide Symbian error codes.

virtual TInt CSenServiceConnection::SubmitL	(	CSenSoapEnvelope &	aMessage,
		HBufC8 *&	aResponseTo
	)	`[pure virtual]`

virtual TInt CSenServiceConnection::SubmitL	(	const TDesC8 &	aRequest,
		HBufC8 *&	aResponse
	)	`[pure virtual]`

Submit a request via SYNCHRONOUS call to a service (in ID-WSF, the SOAP message Body) and receive a response as XML.

There are two default frameworks available - the Identity Based Web Service Framework (which ID is "ID-WSF") and the Basic Web Services Framework (which ID is "WS-I"). Please note, that Basic Web Services framework does NOT support this method. Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&). So, currently this method is supported only in ID-WSF.

Parameters:

	aRequest	outgoing request message.
	aResponse	the resolved response message. The ownership of the aResponse is transfered to the caller. The response is service specific part of the response. For ID-WSF services response contents is the SOAP Body, or complete SOAP envelope as XML, depending on the complete server messages on/off setting (default is off).

Returns:: status/error code. Status codes: KErrNone ok Error codes: KErrSenNotInitialized Connection has not been initialized. KErrSenServiceConnectionBusy Connection is already busy with another request. KErrConnectionInitializing Connection is still initializing and cannot yet process commands. KErrConnectionExpired Credential for the connection is expired and needs to be renewed. This can be done by instantiating a new ServiceConnection. KErrSubmitting An internal error occurred. KErrSenInternal Internal state is invalid. Other error codes are system-wide Symbian error codes.

virtual TInt CSenServiceConnection::TransactionCompleted ( ) [pure virtual]

Stops application level transaction by resetting the "refToMessageId".

After stopping a transaction the next message will have no "refToMessageId"

Returns:: KErrNone if no errors occur. Other error codes are system-wide Symbian error codes.

The documentation for this class was generated from the following file:

senserviceconnection.h

CSenServiceConnection Class Reference

Capability Information

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation