| class CSenServiceConnection : public CActive |
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.
| Protected Member Functions | |
|---|---|
| CSenServiceConnection () | |
| Inherited Enumerations | |
|---|---|
| CActive:TPriority | |
| Inherited Attributes | |
|---|---|
| CActive::iStatus | |
| TInt | CancelTransaction | ( | TInt | aTransactionID | ) | [pure virtual] |
Cancels any active request, if pending transaction (txn) can be found with given txn ID.
| TInt aTransactionID | is the transaction ID to be cancelled. This id has earlier been acquired from a call to some of the asynchronous SendL variants. |
| TInt | 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.
| const TBool & 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. |
| void | DataTrafficDetails | ( | TSenDataTrafficDetails & | aDetails, |
| TSenDataTrafficOperations & | aOperations | |||
| ) | [pure virtual] | |||
Registers observer of BLOBs transfer progress.
| TSenDataTrafficDetails & aDetails | |
| TSenDataTrafficOperations & aOperations |
| TInt | 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.
| TInt | IdentityProviderL | ( | CSenIdentityProvider *& | apIdentityProvider | ) | [pure virtual] |
Getter for the identity provider (XML) service description.
| CSenIdentityProvider *& 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. |
| TAny * | InterfaceByUid | ( | TUid | aUID | ) | [pure virtual] |
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
| TUid aUID | is the UID of the interface being requested |
| TInt | 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).
| TBool & aReady | indicates that the connection is ready to be used. |
| 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.
| MSenServiceConsumer & aConsumer | (web) service consumer (for call-backs) |
| const TDesC8 & aContract | contract of the service, typically an URI. |
| 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.
| MSenServiceConsumer & aObserver | connection observer. |
| MSenServiceDescription & aServiceDescription | is the description used to obtain a service connection. |
| IMPORT_C CSenServiceConnection * | NewL | ( | MSenServiceConsumer & | aObserver, |
| CSenServicePattern & | aServicePattern | |||
| ) | [static] | |||
| MSenServiceConsumer & aObserver | |
| CSenServicePattern & aServicePattern |
| 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.
| MSenServiceConsumer & aConsumer | (web) service consumer (for call-backs) |
| const TDesC8 & aContract | contract of the service, typically an URI. |
| MSenExtendedConsumerInterface & aExtendedConsumer |
| 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.
| MSenServiceConsumer & aConsumer | connection observer. |
| MSenServiceDescription & aServiceDescription | is the description used to obtain a service connection. |
| MSenExtendedConsumerInterface & aExtendedConsumer |
| IMPORT_C CSenServiceConnection * | NewL | ( | MSenServiceConsumer & | aConsumer, |
| CSenServicePattern & | aServicePattern, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [static] | |||
| MSenServiceConsumer & aConsumer | |
| CSenServicePattern & aServicePattern | |
| MSenExtendedConsumerInterface & aExtendedConsumer |
| 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.
| MSenServiceConsumer & aObserver | |
| const TDesC8 & aContract | contract of the service, typically an URI. |
| 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.
| MSenServiceConsumer & aObserver | connection observer. |
| MSenServiceDescription & aServiceDescription | is the description used to obtain a service connection. |
| IMPORT_C CSenServiceConnection * | NewLC | ( | MSenServiceConsumer & | aObserver, |
| CSenServicePattern & | aServicePattern | |||
| ) | [static] | |||
| MSenServiceConsumer & aObserver | |
| CSenServicePattern & aServicePattern |
| 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.
| MSenServiceConsumer & aConsumer | (web) service consumer (for call-backs) |
| const TDesC8 & aContract | contract of the service, typically an URI. |
| MSenExtendedConsumerInterface & aExtendedConsumer |
| 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.
| MSenServiceConsumer & aConsumer | connection observer. |
| MSenServiceDescription & aServiceDescription | is the description used to obtain a service connection. |
| MSenExtendedConsumerInterface & aExtendedConsumer |
| IMPORT_C CSenServiceConnection * | NewLC | ( | MSenServiceConsumer & | aConsumer, |
| CSenServicePattern & | aServicePattern, | |||
| MSenExtendedConsumerInterface & | aExtendedConsumer | |||
| ) | [static] | |||
| MSenServiceConsumer & aConsumer | |
| CSenServicePattern & aServicePattern | |
| MSenExtendedConsumerInterface & aExtendedConsumer |
| MSenMessage * | Response | ( | ) | [pure virtual] |
Getter for currently active transaction (service response) that is being handled by the service consumer.
| TInt | SendL | ( | const TDesC8 & | aRequest | ) | [pure virtual] |
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.
| const TDesC8 & aRequest | outgoing request message. |
| TInt | SendL | ( | CSenSoapEnvelope & | aMessage | ) | [pure virtual] |
| CSenSoapEnvelope & aMessage |
| TInt | SendL | ( | const TDesC8 & | aRequest, |
| const TDesC8 & | aProperties | |||
| ) | [pure virtual] | |||
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.
| TInt | SendL | ( | CSenSoapEnvelope & | aMessage, |
| const TDesC8 & | aProperties | |||
| ) | [pure virtual] | |||
| CSenSoapEnvelope & aMessage | |
| const TDesC8 & aProperties |
| TInt | SendL | ( | MSenMessage & | aMessage | ) | [pure virtual] |
| MSenMessage & aMessage |
| TInt | ServiceDescriptionL | ( | HBufC8 *& | aServiceDescription | ) | [pure virtual] |
Gets service description of current connection.
| HBufC8 *& aServiceDescription | Contains the service description on return |
| TInt | SetTransportPropertiesL | ( | const TDesC8 & | aProperties | ) | [pure virtual] |
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.
| const TDesC8 & aProperties | contains the transport properties in serialized (UTF-8) form. With HTTP, this descriptor is typically created by utilizing CSenHttpProperties class. |
| 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.
| TInt | SubmitL | ( | const TDesC8 & | aRequest, |
| HBufC8 *& | aResponse | |||
| ) | [pure virtual] | |||
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.
| const TDesC8 & aRequest | outgoing request message. |
| HBufC8 *& 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). |
| TInt | SubmitL | ( | CSenSoapEnvelope & | aMessage, |
| HBufC8 *& | aResponseTo | |||
| ) | [pure virtual] | |||
| CSenSoapEnvelope & aMessage | |
| HBufC8 *& aResponseTo |
| TInt | SubmitL | ( | const TDesC8 & | aRequest, |
| const TDesC8 & | aProperties, | |||
| 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.
| const TDesC8 & aRequest | outgoing request message. |
| const TDesC8 & aProperties | contains transport spesific properties, serialized into descriptor. With HTTP, one can create this by utilizing specialized CSenHttpProperties class. |
| HBufC8 *& 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). |
| TInt | SubmitL | ( | CSenSoapEnvelope & | aMessage, |
| const TDesC8 & | aProperties, | |||
| HBufC8 *& | aResponseTo | |||
| ) | [pure virtual] | |||
| TInt | SubmitL | ( | MSenMessage & | aMessage, |
| CSenSoapEnvelope2 *& | aResponseTo | |||
| ) | [pure virtual] | |||
| MSenMessage & aMessage | |
| CSenSoapEnvelope2 *& aResponseTo |
| TInt | SubmitL | ( | RFile & | aFileHandle, |
| HBufC8 *& | 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"
| TInt | TransportPropertiesL | ( | HBufC8 *& | aProperties | ) | [pure virtual] |
| HBufC8 *& aProperties |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.