SIP High Level API

Registration

An endpoint, for example a SIP enabled phone, that wants to start a SIP session must use RConnection to register with the SIP registrar. For more information about RConnection, seeConnection Management . ESOCK provides an interface for the user to access the SIP high level API. ESOCK interacts with the SIP high level API through the Connection and SubConnection providers. Connection and SubConnection providers are ESOCK server side components that are loaded and called when RConnection and RSubConnection APIs are used.

The following figure shows the architectural layer where the application interacts with SIP connection providers using SIPPARAMS. The second layer comprising RSocket, RSubConnection, and RConnection constitute the SIPPARAMS.

The SIP high level API models the SIP with Connection and SubConnection providers and makes it stackable against the unified comms-infras architecture. This enables the future connection convergence.

Initial setup

A profile data store is required to get registered with the SIP Registrar. A SIP registration profile is a data store containing the information required for registration such as AOR which is the IP address of registrar. The data profile must contain the following fields:

• data profile type: Internet, IMS, others

• profile name IETF, IMS, others

• IAP name

• profile AOR list (IP address)

• autoregistration

• private ID

• security negotiation

• sigcomp

• server (IP address of registrar, outbound proxy)

• server param (username, realm, pwd)

• default

Manual registration by specifying parameters is not possible. If connection details are not available, the connection is set up using the default profile.flag file.

Creating an RConnection

Create an RConnection to register to the SIP Registrar using the following steps. RConnection must be opened on an existing socket server session, RSocketServ.

RSocketServ    socketServer;        // Create a client interface object to the socket server
RConnection    con;                        // Create an RConnection object
TRequestStatus status = KErrNone;                // object to hold the request completion status

// Establish the connection to the Socket server

User::LeaveIfError(socketServer.Connect());        // Returns KErrorNone if the connection is successful
CleanupClosePushL(socketServer);

TUint KAFSip = 0x10000;             //SIP protocol family id
TInt err = con.Open (socketServer,KAFSip);            //open the connection
TInt err1 = con.Start();                    // Start Rconnection to initiate the registration

When registration to the SIP registrar is successful, RSubConnection is used to establish the SIP Invite or SIP Subscribe session. The RConnection and RSubConnection that is established and opened are used for either inviting a call session or subscribing for the message status.

Session initiation

SIP Params

SIPPARAMS is used to simplify the interaction with the SIP stack by abstracting the SIP functionality using the RConnection and RSubConnection APIs.  It supports the basic SIP functionality. The complete SIP functionality is made available through the SIP stack APIs.

Initiating a session using INVITE

RSubConnection is used to establish a SIP Invite session. A SIP invitation starts when an endpoint such as a VoIP Softphone or VoIP Hardware tries to establish a session with a remote compliant endpoint. A successful SIP invitation consists of an INVITE-OK-ACK triplet message exchange. The calling endpoint tries to start a session with SIP INVITE. This is followed by OK from the called endpoint, and by ACK from the calling endpoint that finally establishes the SIP session.

A SIP session can be terminated by using BYE-200OK message exchange. Either the calling or the called party can initiate the termination.

RSubConnection establishes the SIP session using the three way communication of INVITE-OK-ACK and terminates the call using BYE-200OK.

RSubConnection when used on behalf of the calling endpoint, handles the message exchange independently and provides the status whether the session is established, denied or not reachable. The calling endpoint must fill the necessary SIP session parameters that are used to determine the target.

RSubConnection when used on behalf of the called endpoint alerts the user of an incoming call such as a SIP invitation. The incoming call can be either accepted or rejected using RSubConnection. The application is notified about the outcome. The information about the calling endpoint is provided in a set of specific parameters.

The SIP parameters for an outgoing call is set using CSubConSIPInviteParamSet class. The following code shows how to initiate a call. It is assumed that you have already registered with the SIP registrar by creating an RConnection object and called Open(). For more information, see Creating an RConnection.

RSubConnection    subCon;    // Create an RSubConnection object
err=subCon.Open(socketServer,RSubConnection::ECreateNew,con); // Open subconnection onto the Rconnection

Set the SIP Invite parameters. The following code shows how to set the SIP Invite parameters.

RSubConParameterBundle     sipBundle;            // create parameter bundle

// create SIP parameter set family
CSubConParameterFamily * family = CSubConParameterFamily::NewL(sipBundle,KSubConnCallDescrParamsFamily);

// create invite parameter set object
CSubConSIPInviteParamSet* sip = CSubConSIPInviteParamSet::NewL(*family,CSubConParameterFamily::ERequested);

Set the SIP header values to the parameter set. The following code shows how to set the SIP header values to the parameter set.

_LIT8(KTo,"Sip:[email protected]");        //'To' header, SIP URI of called endpoint
TPtrC8 ptrTo(KTo());
sip->SetToL(ptrTo);         //Set'To', the target SIP URI to the SIP parameter set

_LIT8(KFrom, "Sip:[email protected]");        //'From' header, SIP URI of the calling endPoint
TPtrC8 ptrFrom(KFrom());
sip->SetFromL(ptrFrom);                //Set the 'From' header field to the SIP parameter set

_LIT8(KContact,"Sip:[email protected]");            //'Contact' header, the actual location of the calling endpoint
TPtrC8 ptrContact (KContact());
sip->SetContactL(ptrContact);                //Set the 'Contact' to the SIP parameter set 

_LIT8(KRequestUri, "Sip:[email protected]");    //Request URI, the actual Next hop or the Target
TPtrC8 ptrRequestUri(KRequestUri());
sip->SetRequestUriL(ptrRequestUri);             //Set the 'RequestUri' to the SIP parameter set

TInt err = SubCon.SetParameters(sipBundle);         //Set The SIP parameters in the SubConnection
sipBundle.Close();                    //close the parameter bundle

Establishing the INVITE session

To establish the SIP Invite session, use RSubConnection to start the subconnection. This initiates the Invite request.

//Start the subconnection, effectively sending an Invite
TInt subConRet = subCon.Start(); 
// Session is established

Initiating a session using SUBSCRIBE

An endpoint subscribes to a specific service using a SIP SUBSCRIBE-200OK message exchange. The end point is notified by means of a NOTIFY-200OK message exchange. To send the subscription and receive notifications use RSubConnection. RSubConnection is also used to unsubscribe, which stops any further notifications.

The following code shows how you subscribe to a session and receive notifications. It assumes that you have already registered with the SIP registrar by creating an RConnection object and calling Open() on it as explained in Creating an RConnection section.

RSubConnection    subCon;// Create an RSubConnection object
// Open subconnection onto the Rconnection
err=subCon.Open(socketServer,RSubConnection::ECreateNew,con);

Set the SIP Subscribe parameters using CSubConSIPSubscribeParamSet. This class provides the SIP subscribe parameters that are passed through the subconnection to the SIP stack.

RSubConParameterBundle     sipBundle;                 //    create parameter bundle

//create SIP parameter set family
CSubConParameterFamily * family = CSubConParameterFamily::NewL(sipBundle,KSubConnCallDescrParamsFamily);

// create subscribe parameter set object
CSubConSIPSubscribeParamSet* sip = CSubConSIPSubscribeParamSet::NewL(*family,CSubConParameterFamily::ERequested);

Set the required information that is, to, from, contact, and reqURI header values to the SIP subscribe parameter set as explained in Initiating a session using INVITE section.

// Set the required information
_LIT8(KEventType, "messagewaiting");    // subscription event type
TPtrC8 ptrEventType (KEventType());
sip->SetEventTypeL(ptrEventType);     //Set the subscription event type to 'messagewaiting'

_LIT8(KAcceptType,  "application");    //accept type
TPtrC8 ptrAcceptType(KAcceptType());
sip->SetAcceptTypeL(ptrAcceptType); //set the accept type field to 'application'

_LIT8(KAcceptSubType,   "indication"); //accept subtype
TPtrC8 ptrAcceptSubType(KAcceptSubType());
sip->SetAcceptSubTypeL(ptrAcceptSubType);    //set the accept subtype

sip->SetExpires(3600);    // set the subscription Refresh timings

sip->SetAutoRefresh(ETrue); // set Auto Refresh to 'on' 

// pass SIP subscribe parameters through the subconnection
Tint err = subCon.SetParameters(sipBundle);
sipBundle.Close(); //close the parameter bundle

subCon.Start();    // Start the subscription

To receive notifications to the subscribed events, CSubConSIPNotificationEvent class is used.

// Wait and receive notifications to events
while(ETrue)
{
TNotificationEventBuf evtBuf;         // Sub-connection event notification object

    TRequestStatus reqStatus;             // request status object

    User::WaitForRequest(reqStatus);
    TInt eventId = evtBuf.Id();                     // get sub-type id
    TInt groupId = evtBuf.GroupId();         // get group id of the event

if (eventId == KSubConSIPNotificationEventType && groupId == KSubConSIPEventsUid)
        {
                CSubConSIPNotificationEvent * evtRes = (CSubConSIPNotificationEvent*)CSubConNotificationEvent::NewL(evtBuf);
                CleanupStack::PushL(evtRes);    
                ....................
                ....................
                CleanupStack::PopAndDestroy(evtRes);    

            // Since We do not want to receive more notifications in this stage, break from the loop.

                break;
        }

// we can wait again for another notification
subCon.EventNotification( evtBuf,EFalse, reqStatus);  //request for notification
}

Unsubscribe to events and unregister, refer to steps in the Terminating the session section.

Setting authentication parameters

A remote party or a server may require authentication before it allows an endpoint to establish a session with another endpoint. RSubConnection provides an authentication mechanism where the authentication information such as realm, username and password must be provided while initiating the call. If a challenge is received then RSubConnection provides the realm and initiates a new session with authentication parameters.

Authentication parameters are set in a subconnection parameter bundle as shown in the following code fragment. Set the SIP authenticate parameter set using CSubConSIPAuthenticateParamSet. This class provides the SIP authenticate parameter values that are passed through the subconnection to the SIP stack.

RSubConParameterBundle     sipBundle;                         //    create parameter bundle
// Add authorisation parameters as new family
CSubConParameterFamily * family1 = CSubConParameterFamily::NewL(sipBundle,KSubConAuthorisationFamily );

// create authenticate parameter set object
CSubConSIPAuthenticateParamSet * authParam = CSubConSIPAuthenticateParamSet::NewL(*family1,CSubConParameterFamily::ERequested);

Set the required information that is, to, from, contact, reqURI header field values to the SIP authenticate parameter set, similar to that in Initiating a session using INVITE section.

_LIT8(KRealm, "SFTF");
_LIT8(KUserName, "MyUserName");
_LIT8(KPwd, "pass123");

authParam->SetRealmL(KRealm);    //set the Realm parameter
authParam->SetUserNameL(KUserName);    // set the username
authParam->SetPasswordL(KPwd);                    //set the password

TInt err = subCon.SetParameters(sipBundle); //set the Authenticate parameters to the subconnection
sipBundle.Close();                    //close the parameter bundle

To terminate the call session or unsubscribe to events and unregister, follow the steps in Terminating the session section.

Terminating the session

To terminate the SIP INVITE or SUBSCRIBE session:

• send BYE message by closing the RSubConnection session

• unregister with the SIP registrar by closing the RConnection session.

Int ret = subCon.Stop();    // Terminate the session, send BYE message

subCon.Close();        // close the subconnection

con.Stop();      // Terminate the connection

con.Close();        // Close the connection 

See also

Socket Server Protocols Overview

Sockets Client Overview

Connection Management