|
Nokia N97 SDK Example Applications Guide |
1. About this Example
2. Prerequisites
3. Design and Implementation
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:
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:
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.
The SIPEx application consists of following modules, which should be built in the following order:
Resolver plug-in
The definition for the whole application can be found in the bld.inf file in the group subdirectory of the applications main directory.
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.
When the profile has been defined, set it to be default by Options -> Default profile and select the profile.
The application attempts to verify and enable the default profile. If the operation is successful, the following info appears on the Log-screen:
The Instant message dialog is displayed. Write the recipients SIP address and your message to the dialog, and select OK:
Your message text is sent to the recipient using the SIP MESSAGE method. The recipient sees the message on Log-screen:
Invitees address dialog is displayed. Write the invitee's SIP address and select OK:
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.
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.
If the application was already running, select Yes to 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.
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.
Alternatively, player can end the game from the menu in the middle of the game.
After the game is ended a new one can be started by inviting a remote party again.
The application is implemented as one executable and three dynamic link libraries (dll).
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.
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 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:
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 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:
The SIP engine implements the MSIPProfileRegistryObserver and is thus notified of changes in the profile registration status.
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.
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.
The following sequence diagram displays the steps of receiving a MESSAGE and sending a response to it.
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.
|
© Nokia 2009 |