Developer Guide for SIP Transparency and Normalization
SIP Transparency
Downloads: This chapterpdf (PDF - 429.0KB) The complete bookPDF (PDF - 1.86MB) | Feedback

SIP Transparency

Table Of Contents

SIP Transparency

Supported Features

Example for 181 Transparency

Example for INFO Transparrency


SIP Transparency


Cisco Unified CM is a Business to Business User Application (B2BUA). Therefore, any SIP to SIP call consists of 2 SIP dialogs. It is often useful to pass information from one dialog to the other during the life of the dialogs. This includes call setup, mid call, and end of call messaging. Using the pass through object described earlier, it is possible to trigger transparent pass through of information on from one SIP dialog (representing 1 of the call legs) to the other.

Currently, transparency is limited to INVITE dialogs between 2 SIP Trunks. If SIP Line is involved, transparency is not supported. SUBSCRIBE dialogs, PUBLISH, out-of-dialog REFER, out-of-dialog unsolicited NOTIFY are not supported, and MESSAGE are not supported.

Supported Features

The following messages support transparency:

Initial INVITE and associated responses

INVITE response

180 response

183 response

200 response

4XX, 5XX, 6XX responses

reINVITE and associated responses

UPDATE message (transparency for responses to UPDATE is not supported)

INFO message (transparency for responses to INFO is not supported)

BYE message (transparency for response to BYE is not supported)

The following messages do not support Transparency:

ACK

PRACK and associated responses

INVITE with replaces and associated responses

REFER and associated responses

Typically Cisco Unified CM processes the following information (i.e. parameters, headers, and content bodies) locally. That is relative to a particular call leg. Hence, the SIP information that is understood is consumed and not passed across to the other call leg (which may not even be SIP anyway). This allows Cisco Unified CM to support various protocol inter-workings such as SIP to H.323, SIP to MGCP, etc. SIP information which is not understood by Cisco Unified CM is typically ignored.

In the following section, information which is understood and consumed by Cisco Unified CM is said to be known and the information not understood and consumed by Cisco Unifiecd CM is said to unknown.

The following information can be passed through transparently:

Parameters

Unknown headers

Unknown content-bodies

Known headers

The following is the list of known headers:

Accept

Accept-Contact

Accept-Resource-Priority

Alert-Info

Allow

Allow-Events

Also

Authorization

Bridge-Participant-ID

Call-ID

Call-Info

CC-Diversion

CC-Redirect

Contact

Content-Disposition

Content-ID

Content-Length

Content-Type

CSeq

Date

Diversion

Event

Expires

From

Geolocation

Geolocation-Error

Join

Max-Forwards

Min-Expires

Min-SE

MIME-Version

P-Asserted-Identity

P-Preferred-Identity

Privacy

Proxy-Authenticate

Proxy-Authorization

Proxy-Require

RAck

Reason

Recv-Info

Refer-To

Referred-By

Reject-Contact

Remote-Party-ID

Replaces

Request-Disposition

Requested-By

Require

Resource-Priority

Retry-After

RSeq

RTP-RxStat

RTP-TxStat

Server

Session

Session-Expires

SIP-ETag

SIP-If-Match

Subject

Subscription-State

Supported

Target-Dialog

To

Unsupported

User-Agent

Via

Warning

WWW-Authenticate

X-Cisco-EMCCInfo

X-Cisco-FallbackID

X-Cisco-ViPR-Ticket

Known Content-bodies

application/sdp

If the script attempts to pass through a known header or content-body, it will trigger an execution error.

A script writer will quickly figure out that there is a way to pass known data through without it being consumed by or interfering with Cisco Unified CM processing. Effectively, the script can get the value for a known header and place into an unknown header. The same can be done with content bodies. The 181 Transparency example below does just that with the Reason header. It gets the Reason header value and passes it through as an X-Reason header. Of course, if there is no script on the other side to consume the X-Reason header and remove it, the header will be sent to the network.

Example for 181 Transparency

Without transparency, if Cisco Unified CM receives a 181 on the outbound trunk leg, Cisco Unified CM's native behavior is to send a 180 back on the inbound trunk leg. To achieve 181 transparency, a script is required for both the inbound 181 (received on the B side) and for the would-be outbound 180 (sent on the A side).

Since the 181 is received from the PBX-B first, consider doing the following first:

Get the Reason header value

Pass through the Reason header value— Since the Reason header is a known header, the script will bypass the known header check by passing through the value using the header name X-Reason.

Cisco Unified CM will automatically merge the pass through data with the outbound message it would have sent. As mentioned previously, it would natively send a 180. The auto merge functionality therefore, places the X-Reason header into an outbound 180.

Next, one must consider what the A side needs to do:

Get the X-Reason header value and see if contains something about 181

Add a Reason header with the X-Reason header value

Remove the X-Reason header

Convert the response code and phrase to 181 Call is Being Forwarded.

These steps are depicted in the following callflow diagram:

The B-side and A-side scripts are shown below:

B-Side Script

B = {}
function B.inbound_181_INVITE(msg)
    local pt = msg:getPassThrough()
    local reason = msg:getHeader("Reason")
    if pt and reason
    then
        pt:addHeader("X-Reason", reason)
    end
end
return B

A-Side Script

A = {}
function A.outbound_180_INVITE(msg)
    local reason = msg:getHeader("X-Reason")
    if reason
    then
        if string.find(reason, "cause=181")
        then
            msg:setResponseCode(181,"Call is being forwarded")
            msg:addHeader("Reason", reason)
        end

        msg:removeHeader("X-Reason")
    end
end
return A

Example for INFO Transparrency

Without transparency, Cisco Unified CM ignores the inbound INFO message and content body. Using transparency, Cisco Unified CM extracts the proprietary content body sent by a Nortel PBX, extract the DTMF digits from that content body, create a new dtmf-relay content body and pass that through to the other call leg.

Script

M = {}
function M.inbound_INFO(msg)
    local body = msg:getContentBody("application/vnd.nortelnetworks.digits")
    if body
    then
        local digits = string.match(body, "d=(%d+)")
        if digits
        then
            pt = msg:getPassThrough()
            body = string.format("Signal=%d\r\nDuration=100\r\n", digits)
            pt:addContentBody("application/dtmf-relay", body)
        end
    end
end
return M

Inbound Message

INFO sip: 1000@10.10.10.1 SIP/2.0
Via: SIP/2.0/UDP 10.10.10.57:5060
From: <sip:1234@10.10.10.57>;tag=d3f423d 
To: <sip:1000@10.10.10.1>;tag=8942 
Call-ID: 312352@10.10.10.57 
CSeq: 5 INFO 
Content-Type: application/vnd.nortelnetworks.digits
Content-Length: 72

p=Digit-Collection
y=Digits
s=success
u=12345678
i=87654321
d=4

Outbound Message

INFO sip: 1000@10.10.10.58 SIP/2.0 
Via: SIP/2.0/UDP 10.10.10.1:5060 
From: <sip:1234@10.10.10.1>;tag=ef45ad 
To: <sip:1000@10.10.10.58>;tag=1234567
Call-ID: 475623@10.10.10.1 
CSeq: 5 INFO 
Content-Type: application/dtmf-relay
Content-Length: 26

Signal=4
Duration=100