Building SIP-Based Applications¶

XTML SIP Data Types¶

The SCE provides XTML data types that are strongly-typed objects, which differ from other XTML data types because they have a well-defined set of properties.

The SCE JavaScript Editor window displays these properties, as shown in the following image.

In addition to properties, strongly-typed objects also have methods (code) associated with them.

Strongly-typed objects make it easier to work with complex, well-structured sets of data that are commonly used across many applications, such as SIP messages, SIP dialogs, media server endpoints, and conferences. Application maintenance is easier when using these strongly-typed objects because all developers are storing and accessing information in similar, well-understood patterns.

The following XTML strongly-typed objects are discussed:

• SipMessage represents all information related to a specific SIP message that is either sent or received by the application server. All SIP headers are available as the properties of this object.

• SipDialog represents all of the information associated with a SIP dialog.

• SipDialogArray is an array of one or more SipDialog objects.

Many of the PACs listed under Session/Call Control on the Actions tab in the workspace pane operate on a SipMessage or SipDialog object or return one of these objects as a result of their action. Grouping all of the information associated with either a SIP dialog or message makes it easier for an application to construct and manage SIP dialogs.

To create a SIP dialog, for example, an uninitialized SipDialog object is passed to the Generate a SIP Dialog Request PAC or the Respond to SIP Dialog Request PAC. That PAC generates all of the SIP signaling necessary to properly construct the SIP dialog in accordance with the preferences indicated in the properties for that PAC. Upon exit from the PAC, the SipDialog object is fully populated with all of the dialog information. When it is time to destroy the dialog, that same SipDialog object can be passed to the Terminate SIP Dialog PAC that generates all of the SIP signaling messages necessary to properly terminate the dialog.

The properties and methods associated with the SipMessage and SipDialog objects are described in the following tables. The SipDialogArray object is a simple JavaScript array and does not have any new properties or methods.

XTML SIP Dialog Events¶

XTML SIP dialog events are listed under Session/Call Control Events on the Events tab in the workspace pane.

SipDialogRequested (SipMessage)

This event is triggered when a new SIP INVITE message requesting a dialog is received by the application server. It contains one parameter, which is a SipMessage corresponding to the INVITE message requesting the dialog that was received by the application server.

SipDialogTerminated (SipMessage, int)

This event is triggered when a SIP dialog has been terminated, usually by the remote party. It contains a SipMessage corresponding to the BYE message that was received and an int value specifying the reason for termination.

SipMsgOutsideDialog (SipMessage)

This event is triggered when a SIP message is received that is not targeted for an existing SIP dialog.

SipMsgWithinDialog (SipMessage)

This event is triggered when a SIP message is received that is targeted for an existing SIP dialog in which the application is participating.

XTML SIP Dialog PACs¶

This section defines the unique tabs included in the Properties window and the standard results available for each PAC listed under Session/Call Control on the Actions tab in the workspace pane.

For more information about the common Description tab and Custom tab, see Build Functions and Custom Results.

Generate a SIP Dialog Request¶

The Generate a SIP Dialog Request PAC creates an outbound SIP INVITE to initiate the SIP session.

Properties¶

The Generate a SIP Dialog Request PAC includes the SIP Dialog Configuration, Session Timers, SIP Message Details, and SIP Message Details - Related Dialog tabs.

SIP Dialog Configuration¶

SIP Dialog Configuration Fields¶

Field Name	Type	Description
Sip dialog to create	String	Creates the SipDialog variable that will hold the dialog object created from this request.
Destination sip address	String	SIP address that the request will be sent to.
Specify source and destination phone numbers	Radio Button	Creates this dialog as a call between two phone numbers.
Calling number	Integer	Phone number of the line creating the call.
Called number	Integer	Phone number receiving the call.
Specify source and destination URLs	Radio Button	Creates this dialog as a call between two SIP URLs.
From URL	String	URL of the SIP endpoint creating the call.
To URL	String	URL of the SIP endpoint receiving the call.
Action	Drop-down List	Creates the session to have the XTML server act as a back-to-back user agent (B2BUA), connect the far end to a local media endpoint, or connect the far end to a conference. This selection determines the additional configurable fields.

Connect Dialog to a Local Media Endpoint Fields¶

Field Name	Type	Description
Cancel if not complete	Checkbox	Cancels the session if not connected in the specified number of seconds.
Exit if no response	Checkbox	Exits the action if the far end does not respond in the specified number of seconds.
Media endpoint to connect to	String	Media endpoint object that is connected to the far end’s media stream.
Media server return status	String	Response from external media server.
Media server	String	External media server.
Allocate new endpoint	Check Box	Initializes the media server using the options selected in the remaining fields.
Media server type	Drop-down List	Type of media server. Select PCS for local media servers or another protocol for external media servers.
Media requirements	Drop-down List	Select ivr or conference.
Codec	Drop-down List	Select a codec from the list. Allow the media server to choose by selecting no preference.
Request DTMF Events	Checkbox	Requests that the DTMF be removed from the actual audio but still transported as part of the media stream.

Act as a B2BUA Fields¶

Field Name	Type	Description
Cancel if not complete	Checkbox	Cancels the session if not connected in the specified number of seconds.
Exit if no response	Checkbox	Exits the action if the far end does not respond in the specified number of seconds.
Existing dialog to connect with	String	Back-to-back user agent connects two different endpoints with the XTML server acting as an intermediary between the two endpoints. This is a dialog to the other endpoint.
Final response message	String	The final response in either establishing or rejecting dialogs.

Connect Dialog to a Conference Fields¶

Field Name	Type	Description
Cancel if not complete	Checkbox	Cancels the session if not connected in the specified number of seconds.
Exit if no response	Checkbox	Exits the action if the far end does not respond in the specified number of seconds.
Allocate new conference	Checkbox	Creates a new conference.
Use RFC 2833 for DTMF	Checkbox	Requests that the DTMF be removed from the actual audio but still transported as part of the media stream.
Clamp DTMF	Checkbox	Media attempts to remove the DTMF tones from the conference audio.
Wideband	Checkbox	Higher quality audio.
Persistent conference	Checkbox	When selected, the conference continues after all sessions associated with it are terminated.
Conference to connect to	String	Conference object that this session is connected to.
Media endpoint object	String	Media endpoint associated with the conference.
Media server return status	String	Response from external media server.
Media server	String	External media server.
Media server type	Drop-down List	Type of media server. Select PCS for local media servers or another protocol for external media servers.
Codec	Drop-down List	Select a codec from the list. Allow the media server to choose by selecting no preference.
Participant mode	Drop-down List	Selects the capabilities of the participant to hear and speak. A coach participant hears the conference, but their speech is only heard by one other participant.
Coachee endpoint	String	Endpoint of the participant who hears the speech of the selected coach participant.
Maximum parties	String	Maximum number of participants in the conference.
Maximum talkers	String	Maximum number of participants who can talk in the conference.
Hysteresis	String	Numeric factor to be applied to smooth the audio stream.
Time constant	String	Time (in milliseconds) between recalculating which participant is the loudest.
Number of active speakers to report	String	Number of speakers (talkers) active during the conference.
Reporting interval (sec)	String	Interval (in seconds) between reports to the conference server of the number of active speakers (talkers).
Active speaker threshold (dB)	String	Minimum amount of energy from an endpoint for it to be considered an active speaker (talker).

Session Timers¶

Session Timers Fields¶

Field Name	Type	Description
Use session timers if the remote side supports them	Checkbox	Establishes a timer that periodically queries the far end as a method of determining if this session is still active.
Preferred refresher	Drop-down List	Preferred protocol for querying the far end.
Preferred interval	Integer	Preferred interval between queries.
Minimum acceptable interval	Integer	Smallest acceptable period of time between queries.

SIP Message Details - Related Dialog¶

The SIP Message Details - Related Details tab allows you to add or modify SIP headers for the request message to the existing session.

Add SIP Headers

1. Click Add.

2. In the Header field, select the header that you want to add.

3. Type the Value for the header.

Note

Click Insert to add a header below the header currently selected. Click Delete to remove a header from the message.

Exit Paths¶

In addition to the default result exit path, the Generate a SIP Dialog Request PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
No response from far end	Points to the next PAC to be executed if the far end has not responded.
Not completed in time	Points to the next PAC to be executed if the session is not established in the defined interval.
Canceled by requestor	Points to the next PAC to be executed if this request operation was canceled by the XTML server.
Session not established	Points to the next PAC to be executed if a session was not established.
Media Resource Failure	Points to the next PAC to be executed when a requested media endpoint could not be created.
Error	Points to the next PAC to be executed in the event that the operation returned an error.

Modify SIP Dialog¶

The Modify SIP Dialog PAC alters the parameters of a SIP dialog.

Properties¶

The Modify SIP Dialog PAC includes the SIP Dialog Modification and SIP Message Details tabs.

SIP Dialog Modification¶

SIP Dialog Modification Fields¶

Field Name	Type	Description
SIP dialog to modify	String	The dialog to be modified by this PAC.
Action	Drop-down List	The action to take to modify the selected dialog. Available actions include putting the far end on hold, connecting the far end to a local media server endpoint or to another media endpoint, and connecting the dialog to a conference. This selection determines the additional configurable fields.

Additional Fields¶

Field Name	Type	Description
Media endpoint object	String	Media endpoint associated with the session.
Media server return status	String	Response from external media server.
Media server	String	External media server.
Allocate new endpoint	Checkbox	Initializes the media endpoint with the options listed below it.
Media server type	Drop-down List	Type of media server. Select PCS for local media servers or another protocol for external media servers.
Media requirements	Drop-down List	Select ivr or conference.
Codec	Drop-down List	Select a codec from the list. Allow the media server to choose by selecting no preference.
Request DTMF Events (RFC 2833)	Checkbox	Requests that the DTMF be removed from the actual audio but still transported as part of the media stream.
DTMF clamp setting	Checkbox	Media attempts to remove the DTMF tones from the conference audio.
Media sdp		The media endpoint to which this session will now be attached. Media from this SDP connection will now be delivered to this endpoint.
Allocate new conference	Checkbox	Creates a new conference.
Persistent conference	Checkbox	When selected, the conference continues after all sessions associated with it are terminated.
Wideband	Checkbox	Higher quality audio.
Conference to connect to	String	Conference object that this session is connected to.
Participant mode	Drop-down List	Selects the capabilities of the participant to hear and speak. A coach participant hears the conference, but their speech is only heard by one other participant.
Maximum parties	String	Maximum number of participants in the conference.
Coachee endpoint	String	Endpoint of the participant who hears the speech of the selected coach participant.
Maximum talkers	String	Maximum number of participants who can talk in the conference.
Hysteresis	String	Numeric factor to be applied to smooth the audio stream.
Time constant	String	Time (in milliseconds) between recalculating which participant is the loudest.
Number of active speakers to report	String	Number of speakers (talkers) active during the conference.
Reporting interval	String	Interval (in seconds) between reports to the conference server of the number of active speakers (talkers).
Active speaker threshold (dB)	String	Minimum amount of energy from an endpoint for it to be considered an active speaker (talker).

SIP Message Details¶

The SIP Message Details tab allows you to add or modify SIP headers for the message.

Add SIP Headers

1. Click Add.

2. In the Header field, select the header that you want to add.

3. Type the Value for the header.

Note

Click Insert to add a header below the header currently selected. Click Delete to remove a header from the message.

Exit Paths¶

In addition to the default result exit path, the Modify SIP Dialog PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
No response	Points to the next PAC to be executed in the event that one of the endpoints did not respond to the modification.
Not completed in time	Points to the next PAC to be executed in the event that the modification has timed out.
Caller hung up	Points to the next PAC to be executed in the event that the SIP endpoint that is pointed to in the SIP dialog is being modified.
Media resource failure	Cannot connect session to the media server.
Error	Points to the next PAC to be executed in the event that the operation returned an error.

Respond to SIP Dialog Request¶

The Respond to SIP Dialog Request PAC responds to a SIP Invite and creates a SIPDialog.

Properties¶

The Respond to SIP Dialog Request PAC includes the SIP Dialog Configuration, Session Timers, SIP Message Details, Session Timers - Related Dialog, and SIP Message Details - Related Dialog tabs.

SIP Dialog Configuration¶

SIP Dialog Configuration Fields¶

Field Name	Type	Description
Action	Drop-down List	Creates the session to have the XTML server act as a back-to-back user agent (B2BUA), connect the far end to a local media endpoint, or connect the far end to a conference. This selection determines the additional configurable fields.
Incoming SIP invite msg	String	The SIP invite message that is being responded to. The information in this invite message is used to establish a SIP dialog.
SIP dialog to create	String	An empty SIP Dialog object to store the state of this call/dialog.
Media endpoint object	String	The media endpoint that is associated with this session.
Media server return status	String	Response from external media server.
Media server	String	External media server.
Allocate new endpoint	Checkbox	Creates a new endpoint instead of using an existing connection.
Media server type	Drop-down List	Type of media server. Select PCS for local media servers or another protocol for external media servers.
Media requirements	Drop-down List	Select ivr or conference.
Codec	Drop-down List	Select a codec from the list. Allow the media server to choose by selecting no preference.
Request DTMF Events	Checkbox	Requests that the DTMF be removed from the actual audio but still transported as part of the media stream.
Send early media	Checkbox	Sends media before establishing a session. The number that appears with the field indicates the kind of SIP message.
Send ringing	Checkbox	Send a 180 ringing response in addition to a 100 trying.
Continue Without Sending 200 OK	Checkbox	This will continue without fully establishing a dialog. This is useful when sending early media.

Session Timers¶

Session Timers Fields¶

Field Name	Type	Description
Use session timers if the remote side supports them	Checkbox	Establishes a timer that periodically queries the far end as a method of determining if this session is still active.
Preferred refresher	Drop-down List	Preferred protocol for querying the far end.
Preferred interval	Integer	Preferred interval between queries.
Minimum acceptable interval	Integer	Smallest acceptable period of time between queries.

SIP Message Details¶

The SIP Message Details tab allows you to add or modify SIP headers for the response message.

Add SIP Headers

1. Click Add.

2. In the Header field, select the header that you want to add.

3. Type the Value for the header.

Note

Click Insert to add a header below the header currently selected. Click Delete to remove a header from the message.

Session Timers - Related Dialog¶

The Session Timers - Related Dialog tab is used to specify session timer preferences for the outbound session request when acting as a B2BUA.

Session Timers - Related Dialog Fields¶

Field Name	Type	Description
Use session timers if the remote side supports them	Checkbox	Establishes a timer that periodically queries the far end as a method of determining if this session is still active.
Preferred refresher	Drop-down List	Preferred protocol for querying the far end.
Preferred interval	Integer	Preferred interval between queries.
Minimum acceptable interval	Integer	Smallest acceptable period of time between queries.

SIP Message Details - Related Dialog¶

The SIP Message Details - Related Dialog tab is used to add or modify SIP headers for the request message to the existing session.

Add SIP Headers

1. Click Add.

2. In the Header field, select the header that you want to add.

3. Type the Value for the header.

Note

Click Insert to add a header below the header currently selected. Click Delete to remove a header from the message.

Exit Paths¶

In addition to the default result exit path, the Respond to SIP Dialog Request PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Send SIP Message¶

The Send SIP Message PAC manually sends the SIP message specified.

Properties¶

The Send SIP Message PAC includes the General and SIP Message Details tabs.

General¶

General Fields¶

Field Name	Type	Description
Request Message/Response Message	Radio Button	Selects the type of message to send.
Enter the request message object you are responding to	String	Message object that the SIP message is responding to.
Status	Drop-down List	Selects the SIP message code to be sent.

SIP Message Details¶

The SIP Message Deatils tab is used to add or modify SIP headers for the message.

Add SIP Headers

1. Click Add.

2. In the Header field, select the header that you want to add.

3. Type the Value for the header.

Note

Click Insert to add a header below the header currently selected. Click Delete to remove a header from the message.

Exit Paths¶

In addition to the default result exit path, the Send SIP Message PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.
Timeout	Points to the next PAC to be executed in the event that the operation times out.

Terminate SIP Dialog¶

The Terminate SIP Dialog PAC terminates the specified SipDialog.

Properties¶

The Terminate SIP Dialog PAC includes the SIP Dialog Termination tab.

SIP Dialog Termination¶

Enter the SipDialog variable associated with the SIP dialog that will be terminated.

Exit Paths¶

In addition to the default result exit path, the Terminate SIP Dialog PAC includes the result exit paths listed in the following table.

Exit Path	Description
Success	Points to the next PAC to be executed in the event that the connection is successful.
Error	Points to the next PAC to be executed in the event that the operation returned an error.

Application Development Guidelines¶

The combination of XTML object types, events, and PACs facilitate the building of SIP-based multimedia applications. The following are guidelines to follow when developing applications:

• If an application is to be triggered by an incoming SIP dialog request, include a public event handler for the SipDialogRequested event and a non-public handler for the SipDialogTerminated event.

  The SipDialogTerminated event does not need to be a public event handler because once an application session receives a SIP dialog request, the application server routes all other SIP messages for that dialog directly to that same session. There is no need for the application to publish information to the internal event routing mechanism within the application server about these events that it wishes to receive.

  The SipDialogRequested event must be designated as a public event handler so that the internal event routing mechanism is aware that this application has an interest in receiving SIP dialog requests. The initial SIP dialog request received by the application server is not associated with any application session, so it is directed to the internal event routing mechanism that will choose an available application session from those that have registered an interest in receiving this event type.

• In the OnSipDialogRequested event handler, use the Respond to SIP Dialog Request PAC to indicate how to respond to the dialog request. You may first want to access a database or perform other service logic to determine what action to take, but eventually you must use the Respond to SIP Dialog Request PAC to answer the incoming request.

• In the Respond to SIP Dialog Request PAC, indicate how to respond to the request and whether to have a session timer active for this call. You do not need to handle any processing of session timers in your application because all session timer handling is performed for you by the application server.

• To terminate a SIP dialog use the Terminate SIP Dialog PAC. If an application session still has active SIP dialogs associated with it when it ends, these dialogs will be properly terminated by the application server. While a properly-written application should terminate any dialogs it creates before exiting, the application server provides another layer of protection, ensuring that proper signaling is generated to the other network elements.