S60 3rd Edition SDK for Symbian OS
Example Applications Guide |
SIP Example
1. About this Example
2. Prerequisites
3. Design and Implementation
4. Class List
This tutorial explains the Session Initiation Protocol (SIP) Example Application. The SIPEx is a simple game for two players, but it is a complete application, which demonstrates the use of the SIP API to set up a connection to a remote device. The structure of the tutorial is based on the architecture of the application, which is shown in the UML component diagram below.
Figure 1.1: SIP Example Application architecture
The example demonstrates the basic usage of the SIP and shows the basic functionality of the SIP API in practice. The API classes are used in the example are defined in the following header files, among others:
- sipprofile.h
- sipprofileregistry.h
- sipprofileregistryobserver.h
- sdpdocument.h
- sip.h
- sipdialog.h
- sipinvitedialogassoc.h
- sipobserver.h
- sipconnectionobserver.h
- sipmessageelements.h
- siprequestelements.h
- sipresponseelements.h
- sipclienttransaction.h
- sipservertransaction.h
This example exists as a complete application, and has the standard Symbian OS application architecture employing the Application, Document, UI, and View classes. Previous knowledge of main Symbian OS concepts is essential to understand this example.
The example demonstrates the use of the SIP protocol in setting up communications between two peers. The scope of the technologies utilised is too broad for this tutorial, so the reader is urged to familiarize her/himself with the following:
- The Session Initiation Protocol (SIP).
- The Session Description Protocol (SDP).
- The TCP/IP protocol family and socket communications.
To use the application, a SIP server is needed. Due to the evolving nature of the networking world, server addresses are not listed in this document. Public SIP servers can be found with internet search engines with search strings like, for example, "public sip server".
The sample application also requires another terminal to be used, since it demonstrates how SIP session can be established between two terminals.
To build the SIP example application, change to the SIPEx directory, run bldmake bldfiles, and run abld build platform udeb, where platform is the platform architecture you are using (usually wins or winscw).
The SIPEx application consists of four modules, which should be built in the following order:
1. SIP Engine 2. Socket Engine 3. Game Engine 4. Game UI
The definition for the whole application can be found in the bld.inf file in the group subdirectory of the applications main directory.
Running the example application requires that an Internet Access Point (IAP) and a SIP profile (with Service profile defined as IETF) have been configured on the device or emulator.
Open the SIP settings application, select New, and define the data. For Service Profile, select IETF, select the Default access point, and define your Public username (your identity as known to SIP, e.g. "user@sipserver.com"). You also need to define the server addresses in the Proxy server and Registrar server tabs (e.g. "sipserver.com"). Check with the SIP server documentation.
Figure 2.1: SIP Settings dialog
When the profile has been defined, set it to be default by Options -> Default profile and select the profile.
Start the application by selecting the SIPEx icon on the desktop. The following screen appears:
Figure 2.2: SIP Example Application initial screen
The first thing to do after starting the application is to enable the default profile. Select Options->Enable profile from the application menu:
Figure 2.3: SIP Example Application initial menu
The application attempts to verify and enable the default profile. If the operation is successful, the following info appears on the Log-screen:
Figure 2.4: Profile is enabled
After the default profile has been enabled, instant messages can be sent to recipients who are proficient in SIP. Instant messaging doesn't require a SIP dialog between the user agents. Start writing your instant message by selecting Options->Send instant message from the menu:
Figure 2.5: SIP Example Application menu - Instant Messaging
The Instant message dialog is displayed. Write the recipients SIP address and your message to the dialog, and select OK:
Figure 2.6: SIP Example Application menu - Instant message dialog
Your message text is sent to the recipient using the SIP MESSAGE method. The recipient sees the message on Log-screen:
Figure 2.7: SIP Example Application menu - Instant message received
After the default profile has been enabled, you can send an invitation for a remote user to join a game with you. The invitation, if accepted, results in a SIP dialog and socket connection being formed between you and the remote party. Start sending the invitation by selecting Options->Invite for game:
Figure 2.8: SIP Example Application menu - Inviting
Invitees address dialog is displayed. Write the invitee's SIP address and select OK:
Figure 2.9 : SIP Example Application menu - Instant Messaging
The INVITE message is sent, and the remote party first responds with the provisional 180 (Ringing) response indicating that the remote terminal is reached and is ringing.
Figure 2.10: SIP Example Application menu - Inviting
Finally, after the remote party has accepted the invitation by sending 200 (OK) response, ACK is sent and SIP session is established. Peer-to-peer connection to remote party is made using TCP/IP for the game. After connection is set up, player inviting to the game has the first move.
Figure 2.11: SIP Example Application - Your move
It is possible to invite user into game even he/she does not have the SIPEx application running. What is however needed is that user is registered into network. In this case invitation is routed to user's terminal and SIP implementation requets permission to launch requested application. Dialog indicates who is the person inviting and what is the requested application. Select Yes to launch requested application and accept invitation.
If the application was already running, select Yes to accept invitation.
Figure 2.12: SIP Example Application - accept invitation
After the invitation is accepted, SIP response 200 OK is sent. SIP session is finally established when ACK is received and TCP/IP connection for game data is created. After connection is set up, user is to wait remote to make his/her first move.
Figure 2.13: SIP Example Application - waiting remote
Game move is made by arrow keys in wanted location. After the move is made, turn is given to remote party.
Figure 2.14: SIP Example Application - remote move
The game will go on until one player will get four pieces in the row. The winner is announced and both peer-to-peer connection and SIP session is disconnected.
Figure 2.15: SIP Example Application - game over
Alternatively, player can end the game from the menu in the middle of the game.
Figure 2.16: SIP Example Application - end game
After the game is ended a new one can be started by inviting a remote party again.
After Capabilities and ScalableUi chapters a brief overview of the Session Initiation Protocol (SIP) is followed. Then the next subchapters describes briefly three of the four components which make up the SIP Example Application: the SIPEx GUI, the SIPEx engine, and the socket engine. Finally, the main component (from this example's point of view), the SIP engine, is described more thoroughly, along with the API functionality used.
The application is implemented as one executable and three dynamic link libraries (dll).
The program capabilities are defined in ui.mmp file: NetworkServices LocalServices Location ReadUserData WriteUserData WriteDeviceData SwEvent ProtServ
SIP Example does not support different screen modes.
The SIP protocol is used to set up a communications session with a remote device on the network. The actual communications use different protocols, after the session has been accomplished. The exchange of messages used to control the session is called a SIP dialog. For more information on SIP, see the IETF RFC 3261.
The following image shows an example of SIP network architecture. In this case, two SIP enabled phones, in SIP lingo user agents, set up a connection using SIP servers in the IP network. The user agent which issues SIP requests is called the user agent client (UAC) and the recipient of these requests the user agent server (UAS). The role of the user agent, client or server, may change during the session - the terms are relevant during a single transaction, i.e. the sending of a request and subsequent responses and acknowledgements related to it.
Figure 3.1: SIP network architecture
Closely related to SIP is the Session Description Protocol (SDP). It defines the format of messages used to describe the type of information one wishes to exchange in a communication session.
In order to be reachable via SIP, the SIP device needs to register itself to a registration server in the network. When the session is initiated, the SIP device contacts a SIP server, which then queries the registration server for the actual contact information. The SIP API provides registration services using profiles.
The session creation commences with the sending of an INVITE message. The INVITE contains the SIP address of the remote party, and usually the desired session is defined in the INVITE message body using SDP.
On receiving the INVITE the remote party sends a provisional reply (e.g. "180 Ringing", implying the invite has been received) and, if it accepts the invitation, a final reply (usually "200 OK").
After the session has been established, the parties can continue communicating using the appropriate channels, e.g. TCP/IP. SIP is not intended for the actual communication, although messages can be sent using the SIP MESSAGE method. Usually the SIP session is kept active during the communication session and it can be used for reconfiguring the session (e.g. activating new session parameters) or tearing down the connection with the BYE method.
The SIPEx GUI is the interface with which the game application is used. The different functions are found in the menu. The active functions, which the user can select at the particular moment, are shown in a menu.
The SIPEx engine is in control of the whole process of setting up the GUI, opening the SIP session with the SIP engine, opening the socket connection to transfer game data, and closing the connections and sessions when exiting the game.
The socket engine handles the socket connection between the two devices. The socket connection transmits the actual game data.
The SIP engine handles the setting up and tearing down of the SIP sessions, the enabling and disabling of the default profile, and the sending and receiving of instant messages. It is implemented as a separate dll, and the engine API is defined in the headers SIPExSIPEngine.h and SIPExSIPEngineObserver.h.
The SIP Engine is a finite state machine, implemented using a state machine design pattern. The states, transitions, and observer methods are shown in the diagram below:
Figure 3.2: The SIP engine statediagram
When the application is started, the game engine creates an instance of the SIP engine object. It is initially in the Idle state. At the same time, the CSIP, CSIPProfileRegistry, and state machine object instances are created.
The SIP Profile Agent API provides a SIP registration service for applications. The behavior of the registration service depends on the profile type used. There are different profile types for different standards, e.g. 3GPP R5 IMS, IETF and proprietary. At any given time, zero or more profiles of any profile type may exist. Each profile has a one-to-one correspondence with one SIP registration.
The SIP engine has functions for enabling the default profile and disabling a previously enabled profile. One of the SIP profiles stored into the device can be designated the default profile. The SIP Example Application requires this to be of the IETF type.
After the SIP engine has instantiated the CSIP, it creates an instance of the CSIPProfileRegistry class. The profile registry object can be used to retrieve the default profile. After retrieval, the profile can be enabled and subsequently disabled. The sequence diagram below demonstrates the profile operations:
Figure 3.3: Profile operations
The SIP engine implements the MSIPProfileRegistryObserver and is thus notified of changes in the profile registration status.
In order to send a SIP request, application creates an instance CSIPRequestElements, and sets the desired parts of the request. Once CSIPRequestElements has been filled, application invokes CSIPConnection SendRequestL(CSIPRequestElements*) function. CSIPConnection takes the ownership of CSIPRequestElements and communicates the request to the server side of the SIP stack. CSIPConnection instantiates a CSIPClientTransaction and returns it to the application. SendRequestL initiates the server side processing of sending the MESSAGE, but the time consuming tasks like address resolving and socket operations are done only after the SendRequestL call has returned. If an error happends after the SendRequestL has returned, e.g. in the address resolving, the error will be communicated to the application by MSIPConnectionObserver::ErrorOccured. It is important to understand that when the SendRequestL returns, the MESSAGE has not yet been sent to the network but is being processed on the server side of the SIP stack.
Once the SendRequestL has returned and the sending of a MESSAGE will continue on the shared server, there is no way for the application to cancel the operation. This applies to other kind of operations too. Note that the CSIPClientTransaction::CancelL function is used to send SIP CANCEL request after the application has first sent an INVITE request.
When a the SIP response message is received from the server side, CSIPConnection forms a CSIPResponseElements object to represent the SIP response, attaches it to the CSIPClientTransaction and notifies the application with MSIPConnectionObserver::IncomingResponse. Application can determine what kind of a response was received by accessing the CSIPResponseElements from the CSIPClientTransaction. As the response was a provisional response, application does not delete the CSIPClientTransaction yet. Later a 200 response is received and application deletes the CSIPClientTransaction, which has now completed.
The following sequence diagram illustrates the steps of sending a MESSAGE request and receiving two responses to it.
Figure 3.4: Sending SIP request
The SIP engine provides utility functions for sending requests (e.g. SendInviteL, CancelInviteL, EndSessionL) and responses (e.g. AcceptInviteL, DeclineInviteL). The availability of a certain function depends on the state of the engine. This way, the state machine enforces the protocol.
In this example a stand-alone SIP request is received through an existing CSIPConnection. CSIPConnection creates CSIPRequestElements and CSIPServerTransaction to represent the incoming SIP request, before notifying the application with IncomingRequest event to MSIPConnectionObserver. Application obtains information of the request by getting the CSIPRequestElements of the CSIPServerTransaction. When a response is sent, CSIPResponseElements needs to be instantiated and passed to CSIPServerTransaction with the SendResponseL function. This causes the response to be handed to server side for further processing. When SendResponseL has returned, application has no need for the CSIPServerTransaction any more and deletes it.
The following sequence diagram displays the steps of receiving a MESSAGE and sending a response to it.
Figure 3.5: Receiving a SIP request
SIP stack receives a SIP INVITE request from network acting as UAS and creates an invite server transaction for the received request. The SIP stack sends a 100 SIP response to the remote UA. After comparing the received request with the stored application capabilities the SIP stack routes the received INVITE request to the chosen application. The application creates CSIPInviteDialogAssoc instance and SIP stack creates CSIPDialog instance. The application sends a 200 SIP response to the remote UA. The remote UA acknowledges the 200 SIP response with ACK and a SIP session is created between the local and remote UA.
If an INVITE is received outside of a dialog, the SIP engine first enables the default profile (in case it is not enabled), then creates a new CSIPConnection instance, before continuing with the handling of the request.
Typically, the receipt of a request, or response to a request sent, results in a state change in the SIP engine. Also the SIP engine observer is usually notified of the incoming request or response.
Figure 3.6: Receiving a SIP request and creating a SIP dialog
The SIP method MESSAGE can be used to send instant messages to SIP user agents. A SIP dialog isn't necessary for instant messaging.
This inheritance list is sorted roughly, but not completely, alphabetically:
|
© Nokia 2006 |
|
