SIP -High Level API

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.

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.

- Interface of Connection and Sub Connection. - - -

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:user@10.112.165.91"); //'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:user@10.112.165.62"); //'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:user@10.112.165.62"); //'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:user@10.112.165.91"); //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

+ + + + + +SIP +High Level API +

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.

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.

+ Interface of Connection and Sub Connection. + + +

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:user@10.112.165.91"); //'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:user@10.112.165.62"); //'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:user@10.112.165.62"); //'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:user@10.112.165.91"); //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