Developer Guide for SIP Transparency and Normalization
SIP Pass Through APIs
Downloads: This chapterpdf (PDF - 360.0KB) The complete bookPDF (PDF - 1.92MB) | Feedback

SIP Pass Through APIs

Table Of Contents

SIP Pass Through APIs

addHeader

addHeaderValueParameter

addHeaderUriParameter

addRequestUriParameter

addContentBody


SIP Pass Through APIs


Cisco Unified CM is a Business to Business User Application (B2BUA) with respect to SIP call processing. The pass through object provides a set of APIs that allows information to be passed from one call leg to the other.

The following SIP Pass Through APIs are availabe:

addHeader

addHeaderValueParameter

addHeaderUriParameter

addRequestUriParameter

addContentBody

addHeader

addHeader(header-name, header-value)

Given the string name of a header and value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

Example

Without transparency, Cisco Unified CM ignores the inbound x-nt-corr-id header since it is unknown to it. Effectively, it is stripped off of the inbound INVITE and not included in the outbound INVITE.

To enable pass through of this header, it must be included in the allowHeaders table at the beginning of the script. Then it must be explicitly added to the pass through object during message handling.

Script

M = {}
M.allowHeaders = {"x-nt-corr-id"}
function M.inbound_INVITE(msg)
    local ntcorrid = msg:getHeader("x-nt-corr-id")
    if ntcorrid
    then
        pt = msg:getPassThrough()
        pt:addHeader("x-nt-corr-id", ntcorrid)
    end
end
return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0
.
x-nt-corr-id: 000002bf0f15140a0a@000075447daf-a561119
.

Outbound Message

INVITE sip:1234@10.10.10.2 SIP/2.0
.
x-nt-corr-id: 000002bf0f15140a0a@000075447daf-a561119
.

addHeaderValueParameter

addHeaderValueParameter(header-name, parameter-name [,parameter-value])

Given the name of a header , a parameter name, and a parameter value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The header name and parameter name are required arguments. The parameter-value is optional.


Note By default, Contact header value parameters, are passed through independent of any script logic, except the following, which are considered call-leg specific, and are Cisco Unified CM generated as appropriate:
                   - audio
                   - video


Example

Without transparency, Cisco Unified CM ignorea the inbound x-tag in the From header since it is unknown to it. Effectively, it is stripped off of the inbound INVITE and not included in the outbound INVITE.

To enable pass through of this header parameter, it must be explicitly added to the pass through object during message handling.

Script

M = {}
function M.inbound_INVITE(msg)
    local xtag = msg:getHeaderValueParameter("From", "x-tag")
    if xtag
    then
        pt = msg:getPassThrough()
        pt:addHeaderValueParameter("From", "x-tag", xtag)
    end
end
return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0
. 
From: <sip:1000@10.10.10.58>;tag=0988bf47-df77-4cb4;x-tag=42
.

Outbound Message

INVITE sip:1234@10.10.10.2 SIP/2.0
.
From: <sip:1000@10.10.10.1>;tag=abcd;x-tag=42
.

addHeaderUriParameter

addHeaderUriParameter(header-name, parameter-name [,parameter-value])

Given the name of a header, a URI parameter name, and a parameter value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The header name and parameter name are required arguments. The parameter value is optional.

Example:

Without transparency, Cisco Unified CM ignores the inbound cca-id parameter in the Contact header URI since it is unknown to it. Effectively, it is stripped off of the inbound INVITE and not included in the outbound INVITE.

To enable pass through of this header URI parameter, it is explicitly added to the pass through object during message handling.


Note The parameter, in this example, takes on a different name in the outbound message (i.e. originating cca-id in the outbound message versus cca-id in the inbound message).


Script

M = {}
function M.inbound_INVITE(msg)
    local occaid = msg:getHeaderUriParameter("Contact", "cca-id")
    if occaid
    then
        pt = msg:getPassThrough()
        pt:addHeaderUriParameter("Contact", "originating-cca-id", occaid)
    end
end
return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0
. 
Contact: <sip:1000@10.10.10.58;cca-id=LSC.dsn.mil>
.

Outbound Message

INVITE sip:1234@10.10.10.2 SIP/2.0
.
Contact: <sip:1000@10.10.10.1;originating-cca-id=LSC.dsn.mil>
.

addRequestUriParameter

addRequestUriParameter(parameter-name [,parameter-value])

Given a URI parameter name and a parameter value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The parameter name is a required argument. The parameter value is optional.


Note By default, Request-Uri parameters in an initial INVITE, are passed through independent of any script logic, except the following, which are considered call-leg specific, and are CUCM generated as appropriate:
                  - phone-context
                  - trunk-context
                  - tgrp
                  - user


Example: The inbound leg creates and passes through a parameter to be placed into the outbound Request URI.

Script

M = {}
function M.inbound_INVITE(msg)
    pt = msg:getPassThrough()
    pt:addRequestUriParameter("from-network", "service-provider")
end
return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0

Outbound Message

INVITE sip:1234@10.10.10.2;from-network=service-provider SIP/2.0

addContentBody

addContentBody(content-type, content-body [,content-disposition [,content-encoding 
,[content-language]]])


Given a content-type, content-body, content-disposition, content-encoding, and content-language, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The content-type and content-body are required arguments. The content-disposition, content-encoding, and content-language are optional parameters. If blank or nil is specified for any of these values, the header will not be included as part of the content.

Example:

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.

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