The SIP High Level API encapsulates the SIP call flows inside the RConnection and RSubConnection APIs. The following SIP functionality is supported using RConnection and RSubConnection APIs:
REGISTER - An application that wants to start a SIP session must register to the SIP server. For more information, see Registration.
INVITE - An invite session is created for activities such as setting up a voice call, and a game session. For more information, see Session initiation.
SUBSCRIBE - SIP supports subscription to events for example, message waiting, notifying the subscriber about the current state of the event and any changes to its state. For more information, see Initiating a session using SUBSCRIBE.
The INVITE and SUBSCRIBE methods must be registered. CSubConSIPInviteParamSet and CSubConSIPSubscribeParamSet classes provide the parameters.
Note: SIP High Level API is included in the Symbian OS v9.2 onwards.
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.
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.
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.
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