You are here: CSP Developer’s Guide: Internet Protocol > 5 Session-Initiation Protocol (SIP) Software > Programmable SIP URI Extensions

Programmable SIP URI Extensions

Overview

This features allows host application developers to use the EXS API to write and access user name extensions in the Contact and Request Uniform Resource Identifiers (URIs) in SIP headers.

Description

These user name extensions can be used to carry application-specific information such as PSTN trunk group information.

The CSP supports the reporting of Contact URIs and Request URIs as follows:

• The Contact URI user name is reported in TLV 0x292D in the Request for Service with Data message.

• The Request URI is reported in TLV 0x2954 in the Request for Service with Data message.

• You must first indicate in the SIP Message Information Mask TLV (0x027F) in the VoIP Protocol Configure message (0x00EE) that you want the CSP to report the Request URI information (Bit 3) and Contact URI information (Bit 5).

Important! The length of username or password or hostname in TO, FROM and CONTACT URIs in the inbound INVITE (coming from the network to CSP) should not exceed 179 bytes. The length of username or hostname in REQUEST URI in the inbound INVITE (coming from the network to CSP) should not exceed 179 bytes. If it exceeds the call is purged with 0xDD and the Invite is responded with 500 Internal Server error.

The following TLVs are also used to implement this feature. Refer to the Tag Length Value Blocks chapter in the API Reference.

• 0x2934 SIP Contact URI User Information Qualifier
Use this TLV to append a user-defined ASCII string to the Contact URI user name in outbound SIP calls from the CSP. Specifically, the ASCII string is populated in the user information of the Contact-URI header in the outbound SIP INVITE message.
When the CSP is in a SIP/PSTN gateway environment, you can use this TLV to report the originating trunk group information in a
PSTN-to-SIP call.

• 0x2935 SIP Contact URI Parameters
Use this TLV to receive and send Contact-URI parameters to and from host applications.
For inbound calls, this TLV carries all of the Contact URI parameters received by the SIP software in the Request for Service with Data message to host applications.
For outbound SIP calls, this TLV allows you to insert Contact URI parameters in SIP INVITE messages.

To report this TLV you must first set Bit 5 in the SIP Message Information Mask TLV (0x027F).

Examples in a Gateway Environment

This section shows calls in a network architecture where the host application controls a SIP/PSTN gateway. Each figure in this section is followed by the steps and message traces to further explain the process.

Figure 5-14 Originating and Destination Trunk Groups Reported by the CSP

The following example involves a PSTN-to-SIP call.

Steps

1. A call comes into the CSP from the PSTN for example, in an SS7 IAM message.

2. The CSP sends the Request for Service with Data message to the host application.

3. The host application sends the Route Control message to the CSP. The message could contain any or all of the following TLVs:

• 0x2934 SIP Contact URI User Name Qualifier *

• 0x2935 SIP Contact URI Parameters *

• 0x2957 SIP Request URI User Name Qualifier
* One or the other is included but usually not both together.

4. The CSP sends the SIP INVITE to the network with the enhanced URIs.

Message Trace

H->X

[00 71 00 e8 00 00 ff 00 01 29 02 ff fe 02 03 00 1e 00

19 00 04 00 13 00 02 00 08 00 08 00 02 00 65 00 0f 00

01 0b 00 65 00 02 00 00 03 00 33 00 42 00 04 27 7e 00

03 08 00 00 27 17 00 05 10 00 04 11 11 29 57 00 13 74

67 72 70 3d 6c 6f 63 61 6c 3d 74 67 35 34 33 32 31 00

29 35 00 15 74 67 72 70 3d 22 6c 6f 63 61 6c 3d 74 67

31 32 33 34 35 22 00]

SIP:

INVITE sip:1111;tgrp=local=tg54321@10.10.1.202:5060 SIP/2.0

Via: SIP/2.0/UDP 10.10.1.31

To: 1111<sip:1111@10.10.1.202:5060>

From: 00000000<sip:00000000@10.10.1.31:5060>;tag=171166949b

Call-ID: EXCEL-CSP1.6af.155.400@10.10.1.31

Contact: 00000000<sip:00000000;tgrp=local=tg12345@10.10.1.31:5060>

User-Agent: Excel_CSP/82.20.99

Supported: timer

Session-Expires: 1800

Min-SE: 300

CSeq: 1 INVITE

Content-Type: application/sdp

Content-Length: 99

v=0

o=sip 0 0 IN IP4 10.10.1.31

s=SIP_Call

c=IN IP4 10.10.1.37

t=0 0

m=audio 14844 RTP/AVP 0

Figure 5-15 TLVs Reported in Request for Service with Data message

The following example involves a SIP-to-PSTN call.

Steps

1. A SIP call comes into the CSP in a SIP I NVITE message.

2. The CSP sends the host application a Request for Service with Data message that could contain any or all of the following TLVs:

• 0x2954 SIP Request URI User Name

• 0x2955 SIP Request URI Host Name

• 0x292D SIP Contact URI User Name

3. The host application sends an Outseize Control message to a span/channel within a given destination trunk group.

4. The CSP sends an SS7 IAM to the PSTN network over the specified destination trunk group.

Message Trace

X->H

[00 ec 00 2d 00 07 01 00 01 0d 03 00 01 09 00 33 01 03 00 33

00 d8 00 13 27 4e 00 02 00 05 27 7e 00 03 08 00 00 29

19 00 05 31 31 31 31 00 29 1b 00 0b 31 30 2e 31 30 2e

31 2e 33 31 00 29 23 00 05 31 31 31 31 00 29 25 00 0b

31 30 2e 31 30 2e 31 2e 33 31 00 29 2d 00 18 31 31 31

31 3b 74 67 72 70 3d 6c 6f 63 61 6c 3d 74 67 35 34 33

32 31 00 29 2f 00 0c 31 30 2e 31 30 2e 31 2e 32 30 32

00 29 30 00 04 00 00 13 c4 29 33 00 01 01 27 18 00 07

02 00 00 00 04 11 11 27 17 00 05 02 00 04 11 11 27 94

00 04 0a 0a 01 ca 27 95 00 04 00 00 70 16 27 b0 00 02

00 02 27 b1 00 02 00 01 29 16 00 01 01 29 54 00 18 31

31 31 31 3b 74 67 72 70 3d 6c 6f 63 61 6c 3d 74 67 31

32 33 34 35 00 29 55 00 0b 31 30 2e 31 30 2e 31 2e 33

31 00]

INVITE sip:1111;tgrp=local=tg12345@10.10.1.31 SIP/2.0

Via: SIP/2.0/UDP 10.10.1.202:5060

From: "rj" <sip:1111@10.10.1.31>;tag=9421080012ceb664b5d730-29784667

To: <sip:1111@10.10.1.31>

Call-ID: 00082194-b6ce08ef-600c8cf5-178f0b21@10.10.1.202

CSeq: 101 INVITE

Expires: 180

User-Agent: Cisco-SIP-IP-Phone/2

Accept: application/sdp

Contact: sip:1111;tgrp=local=tg54321@10.10.1.202:5060

Content-Type: application/sdp

Content-Length: 219

v=0

o=CiscoSystemsSIP-IPPhone-UserAgent 341 9240 IN IP4 10.10.1.202

s=SIP Call

c=IN IP4 10.10.1.202

t=0 0

m=audio 28694 RTP/AVP 0 8 18 101

a=rtpmap:0 pcmu/8000

a=rtpmap:101 telephone-event/8000

a=fmtp:101 0-11

Session-Initiation Protocol. A signaling protocol used for establishing sessions in an IP network. A session could be a simple, two-way telephone call, or it could be a collaborative multi-media conference session.
Public Switched Telephone Network
Tag-Length-Value block. A standardized block that allows data to inserted in a standard way into API messages.
Voice over Internet Protocol. The delivery of voice information in digital form in discrete packets rather than in the traditional circuit-committed protocols of the public-switched telephone network (PSTN).
American Standard Code for Information Interchange
A device that translates calls between an IP network and another network, typically the PSTN.
See Signaling System Number Seven.
Real-Time Transport Protocol. Supports transport of real-time data like interactive voice and video over packet-switched networks.
A computer, attached to the Excel platform through an RS-232 or Ethernet link, from which you run the telecommunications application that controls the Excel platform.
Outgoing call setup during real-time call processing on a specific channel.
Internet Protocol. Part of the TCP/IP family of protocols used to route messages and tracks the addresses of nodes.
In PPL, a condition that, when met, drives a state machine (PPL Component) from one state to another, by invoking an associated Primitive. In PPL files, an Event is marked by an arrow and text.