Figure 1: The use cases of the Web Services API
WSF has characteristics of several types of APIs such as:
Framework API
The client implements the Service Connection library’s MSenServiceConsumer interface and registers itself as a content handler for receiving connection-related information (meaning the status, responses and possible errors).
Library API
The client uses the Service Description library to desribe the connection. The Service Connection library contains the classes, which are used in handling the response.
Virtual Machine API
Web Services Framework API can be seen as a Virtual Machine API. It encapsulates the usage of Web services (which can be seen as resources) and provides access to them. There is a certain protocol in using the connection, which dictates the error handling and state monitoring of the connection.
Settings API
WSF API also has characteristics of a Settings API. It can be used in describing the used service.
It is important to notice that when calling the specified Web service, the call can be done as blocking or non-blocking. In case of a blocking (synchronous) call, the service consumer receives the possible response from the service directly. In the non-blocking (asynchronous) case, the service consumer receives the possible response by a call to a specified callback function.
The blocking call can be used if the response of the service is a prerequisite for using the service consumer application; i.e. if the application is unusable without the service’s response or there is nothing that the end user can do while waiting for the response.
The actual call to the service is done in WSF’s server-side implementation using Symbian’s Client-Server API. The server-side is implemented using active objects, so the active scheduler has to have been started or the connection cannot be gotten. This has to be taken into consideration especially with console or headless applications. If the Web service consumer application uses CONE (which is the case in GUI applications), then CONE starts the active scheduler automatically.
Figure 1: The use cases of the Web Services API
The Service Connection (SC) library is used for connecting and sending messages to a specified Web service. Once a connection has been established, the Service Connection library is used in sending messages to the service and in handling the received responses. It also represents the functionality for SOAP messages and Basic Web Services security headers. Finally, this module is used to release the connection.
Errors in creating the connection to some framework are reported through this library (for example SOAP faults or XML type errors). The connection state (whether the session is valid) is received through the callback interface defined by this module. The Service Connection library offers asynchronous functions for key functionalities, hence offering easy and adequate UI integration.
Figure 2: Service Connection library
The Service Description (SD) library provides classes for describing the
service to be used. The main classes are MSenServiceDescription’s
subclasses. The Service Description library is also used when dealing with
policies, facets, and credentials. There are ready-to-use utility classes
in the Service Description library simplifying the use of the Service Connection
module. These classes represent e.g. the functionality for XML-type service
descriptions.
Figure 3: Service Description library
The Service Manager library is a one-class (CSenServiceManager) library, which offers an API for accessing and managing WSF’s service and identity related data. Typically, service consumers use Service Manager to register service or identity based data, which is required for accessing a Web service.
Figure 4: Service Manager library
The XML Extensions library provides a way to handle (parse) XML documents. This is especially useful when handling response or possible error messages from the used service.
Figure 5: XML Extensions library
Note: All of the operations and associations are not visible in the figures above.
