#include <mw/SenServiceConnection.h>
| class CSenServiceConnection : public CActive |
| Protected Member Functions | |
|---|---|
| CSenServiceConnection() | |
| Inherited Attributes | |
|---|---|
| CActive::iStatus | |
| Inherited Enumerations | |
|---|---|
| CActive:TPriority | |
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.
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.
Cancels any active request, if pending transaction (txn) can be found with given txn ID.
| Parameter | Description |
|---|---|
| aTransactionID | is the transaction ID to be cancelled. This id has earlier been acquired from a call to some of the asynchronous SendL variants. |
Returns: KErrNone on success KErrNotFound, if there is no pending transaction (active request), or some of the system-wide error codes otheriwise.
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.
| Parameter | Description |
|---|---|
| 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.
| void | DataTrafficDetails | ( | TSenDataTrafficDetails & | aDetails, |
| TSenDataTrafficOperations & | aOperations | |||
| ) | [pure virtual] | |||
Registers observer of BLOBs transfer progress.
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.
| Parameter | Description |
|---|---|
| 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.
| TInt | Identifier | ( | ) | [pure virtual] |
Getter for the identifier of this connection.
Returns: the identifier as integer.
| TInt | IdentityProviderL | ( | CSenIdentityProvider *& | apIdentityProvider | ) | [pure virtual] |
Getter for the identity provider (XML) service description.
| Parameter | Description |
|---|---|
| apIdentityProvider | will point to a new IDP instance, if such is associated with this connection (and this connection was ready before calling this method), or NULL otherwise. |
Returns: KErrNone if IDP description can be found, or some of the system wide error code otherwise.
Service Consumer can call this method to acquire a new interface, which is identified by unique ID (UID). List of currently supported interfaces: KSenInterfaceUidAlrServiceConnection => MSenAlrServiceConnection
| Parameter | Description |
|---|---|
| aUID | is the UID of the interface being requested |
Returns: TAny* pointer to the interface, or if no interface to given UID exists, function returns NULL. In typical cases, returned pointer should be cast to some preknown M-class pointer (the actual new interface).
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).
| Parameter | Description |
|---|---|
| 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.
| IMPORT_C 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.
| Parameter | Description |
|---|---|
| aConsumer | (web) service consumer (for call-backs) |
| aContract | contract of the service, typically an URI. |
Returns: a pointer to a CSenServiceConnection instance.
| IMPORT_C 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.
| Parameter | Description |
|---|---|
| aObserver | connection observer. |
| aServiceDescription | is the description used to obtain a service connection. |
Returns: a pointer to a CSenServiceConnection instance.
| IMPORT_C CSenServiceConnection * | NewL | ( | MSenServiceConsumer & | aObserver, |
| CSenServicePattern & | aServicePattern | |||
| ) | [static] | |||
| IMPORT_C CSenServiceConnection * | NewL | ( | MSenServiceConsumer & | aConsumer, |
| const TDesC8 & | aContract, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [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.
| Parameter | Description |
|---|---|
| aConsumer | (web) service consumer (for call-backs) |
| aContract | contract of the service, typically an URI. |
Returns: a pointer to a CSenServiceConnection instance.
| IMPORT_C CSenServiceConnection * | NewL | ( | MSenServiceConsumer & | aConsumer, |
| MSenServiceDescription & | aServiceDescription, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [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.
| Parameter | Description |
|---|---|
| aConsumer | connection observer. |
| aServiceDescription | is the description used to obtain a service connection. |
Returns: a pointer to a CSenServiceConnection instance.
| IMPORT_C CSenServiceConnection * | NewL | ( | MSenServiceConsumer & | aConsumer, |
| CSenServicePattern & | aServicePattern, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [static] | |||
| IMPORT_C 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.
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.
| Parameter | Description |
|---|---|
| aContract | contract of the service, typically an URI. |
Returns: a pointer to a CSenServiceConnection instance. The pointer is left on the cleanup stack.
| IMPORT_C 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.
| Parameter | Description |
|---|---|
| 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.
| IMPORT_C CSenServiceConnection * | NewLC | ( | MSenServiceConsumer & | aObserver, |
| CSenServicePattern & | aServicePattern | |||
| ) | [static] | |||
| IMPORT_C CSenServiceConnection * | NewLC | ( | MSenServiceConsumer & | aConsumer, |
| const TDesC8 & | aContract, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [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.
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.
| Parameter | Description |
|---|---|
| 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.
| IMPORT_C CSenServiceConnection * | NewLC | ( | MSenServiceConsumer & | aConsumer, |
| MSenServiceDescription & | aServiceDescription, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [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.
| Parameter | Description |
|---|---|
| aConsumer | 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.
| IMPORT_C CSenServiceConnection * | NewLC | ( | MSenServiceConsumer & | aConsumer, |
| CSenServicePattern & | aServicePattern, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [static] | |||
| MSenMessage * | Response | ( | ) | [pure virtual] |
Getter for currently active transaction (service response) that is being handled by the service consumer.
Returns: a pointer to currently active transaction (service response). It is guarenteed, that the method returns a pointer to transaction only when called inside HandleMessageL or HandleErrorL callback methods of MSenServiceConsumer, otherwise it will return NULL.
Send an ASYNCHRONOUS request to a service. In ID-WSF, the request data is a SOAP Body. Response message is received either via 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.
| Parameter | Description |
|---|---|
| aRequest | outgoing request message. |
Returns: Transaction ID (positive integer) or error code, if method fails. Transaction ids: Positive integers SendL returns transaction ID of the request, which can be later on utilized inside HandleMessageL and HandleErrorL methods, in order to map request and its response together. 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 error occurred KErrNoMemory Not enough memory to process the message. Other error codes are system-wide Symbian error codes.
Send an ASYNCHRONOUS request to a service. In ID-WSF, the request data is a SOAP Body. Response message is received either via 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.
| Parameter | Description |
|---|---|
| aRequest | outgoing request message. |
| aProperties | contains transport spesific properties, serialized into descriptor. With HTTP, one can create this by utilizing specialized CSenHttpProperties class. |
Returns: Transaction ID (positive integer) or error code, if method fails. Transaction ids: Positive integers SendL returns transaction ID of the request, which can be later on utilized inside HandleMessageL and HandleErrorL methods, in order to map request and its response together. 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 error occurred KErrNoMemory Not enough memory to process the message. Other error codes are system-wide Symbian error codes.
Gets service description of current connection.
| Parameter | Description |
|---|---|
| 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.
Sets transport specific properties which apply as long as this connection is alive (session). Furthermore, the properties are effective for this session in cumulative manner: each property has unique key (name) which is associated to the actual value of that property. When SetTransportPropertiesL method is called multiple times - in sequence - the last value for each key overrides any previous definitions. If any latter call introduces new keys (property names), they are appended to the list of currently effective properties. Also note, that it is also possible to set message specific properties when making a SendL/SubmitL call. If such transport properties for message are provided, and those include updates to some properties, the new ones are effective only for that certain message, i.e. those are transaction specific. For any following message, that is sent over a service connection, the session specific properties apply, assuming that the new message does not (again) override some of the property values.
| Parameter | Description |
|---|---|
| aProperties | contains the transport properties in serialized (UTF-8) form. With HTTP, this descriptor is typically created by utilizing CSenHttpProperties class. |
Returns: KErrNone if successful or otherwise some system-wide error code.
| TInt | 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.
Submit a synchronous request 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.
| Parameter | Description |
|---|---|
| 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.
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.
| Parameter | Description |
|---|---|
| aRequest | outgoing request message. |
| aProperties | contains transport spesific properties, serialized into descriptor. With HTTP, one can create this by utilizing specialized CSenHttpProperties class. |
| 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.
| TInt | SubmitL | ( | MSenMessage & | aMessage, |
| CSenSoapEnvelope2 *& | aResponseTo | |||
| ) | [pure virtual] | |||
| TInt | 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.