src/modules/sipt/README
1eeae386
 sipt Module
 
 Torrey Searle
 
    Voxbone SA
    <torrey@voxbone.com>
 
    Copyright © 2013 Voxbone SA
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
         3. Functions
 
1b264954
               3.1. sipt_destination(destination, hops, nai[,
                       terminator=1])
 
a7f8ee27
               3.2. sipt_set_bci_1(charge_indicator, called_status,
                       called_category, e2e_indicator)
 
               3.3. sipt_set_calling(origin, nai, presentation, screening)
02aa4892
               3.4. sipt_forwarding(origin, nai)
d02ebb25
 
         4. Exported pseudo-variables
 
b0ab6f70
               4.1. $sipt(calling_party_number.presentation) /
                       $sipt_presentation
 
               4.2. $sipt(calling_party_number.screening) / $sipt_screening
               4.3. $sipt(hop_counter) / $sipt_hop_counter
               4.4. $sipt(calling_party_category) / $sipt(cpc) / $sipt_cpc
               4.5. $sipt(calling_party_number.nature_of_address) /
                       $sipt.(calling_party_number.nai) /
                       $sipt_calling_party_nai
 
               4.6. $sipt(called_party_number.nature_of_address) /
                       $sipt(called_party_number.nai) /
                       $sipt_called_party_nai
 
               4.7. $sipt(event_info)
8ef89248
               4.8. $sipt(backward_call_indicator.charge_indicator)
02aa4892
               4.9. $sipt(redirection_info) / $sipt_redirection_info
               4.10. $sipt(redirection_number) / $sipt_redirection_number
               4.11. $sipt(redirection_number.nai) /
                       $sipt_redirection_number_nai
1eeae386
 
53319656
    List of Tables
 
    1.1. Address Presentation Restricted Indicator Values
    1.2. Screening Indicator Values
    1.3. Calling Nature of Address Values
    1.4. Called Nature of Address Values
a4297694
    1.5. Event Info Values
8ef89248
    1.6. Charge Indicator Values
02aa4892
    1.7. Redirecting reason Values
    1.8. Redirecting number NAI Values
53319656
 
1eeae386
    List of Examples
 
    1.1. sipt_destination(destination, hops, nai) usage
a7f8ee27
    1.2. sipt_destination(destination, hops, nai) usage
    1.3. sipt_set_calling(origin, nai, presentation, screening) usage
02aa4892
    1.4. sipt_set_calling(origin, nai) usage
    1.5. sipt_presentation pseudo-variable usage
    1.6. sipt_screening pseudo-variable usage
    1.7. sipt_hop_counter pseudo-variable usage
    1.8. sipt_cpc pseudo-variable usage
    1.9. sipt_calling_party_nai pseudo-variable usage
    1.10. sipt_called_party_nai pseudo-variable usage
    1.11. sipt_redirection_number usage
1eeae386
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
    3. Functions
 
1b264954
         3.1. sipt_destination(destination, hops, nai[, terminator=1])
a7f8ee27
         3.2. sipt_set_bci_1(charge_indicator, called_status,
                 called_category, e2e_indicator)
 
         3.3. sipt_set_calling(origin, nai, presentation, screening)
02aa4892
         3.4. sipt_forwarding(origin, nai)
d02ebb25
 
    4. Exported pseudo-variables
 
b0ab6f70
         4.1. $sipt(calling_party_number.presentation) / $sipt_presentation
         4.2. $sipt(calling_party_number.screening) / $sipt_screening
         4.3. $sipt(hop_counter) / $sipt_hop_counter
         4.4. $sipt(calling_party_category) / $sipt(cpc) / $sipt_cpc
         4.5. $sipt(calling_party_number.nature_of_address) /
                 $sipt.(calling_party_number.nai) / $sipt_calling_party_nai
 
         4.6. $sipt(called_party_number.nature_of_address) /
                 $sipt(called_party_number.nai) / $sipt_called_party_nai
 
         4.7. $sipt(event_info)
8ef89248
         4.8. $sipt(backward_call_indicator.charge_indicator)
02aa4892
         4.9. $sipt(redirection_info) / $sipt_redirection_info
         4.10. $sipt(redirection_number) / $sipt_redirection_number
         4.11. $sipt(redirection_number.nai) / $sipt_redirection_number_nai
1eeae386
 
 1. Overview
 
8868e624
    Module for updating ISUP encapsulated in SIP (SIP-T/SIP-I)
1eeae386
 
    The sipt module can be used to update various ss7 headers contained
edc838f0
    inside a message.
1eeae386
 
 2. Dependencies
 
    The module depends on the following modules (in the other words the
    listed modules must be loaded before this module):
      * none
 
 3. Functions
 
1b264954
    3.1. sipt_destination(destination, hops, nai[, terminator=1])
a7f8ee27
    3.2. sipt_set_bci_1(charge_indicator, called_status, called_category,
           e2e_indicator)
 
    3.3. sipt_set_calling(origin, nai, presentation, screening)
02aa4892
    3.4. sipt_forwarding(origin, nai)
1eeae386
 
1b264954
 3.1. sipt_destination(destination, hops, nai[, terminator=1])
1eeae386
 
    updates the IAM in the body if it exists, setting the called party
    number to “destination” with the nature address specified in “nai” and
    decrementing the hop counter value if present. If the hop counter
1b264954
    header is missing it will be added with the value of “hops”. If
8868e624
    “terminator” is set to 1, then F will be appended to digit string to
1b264954
    indicate the number is complete (default).
1eeae386
 
    Example 1.1. sipt_destination(destination, hops, nai) usage
 ...
 # update the destination number to our current request uri,
 # setting nature of address to international
 $rU = "19495551234";
 sipt_destination($rU, 31, 4);
 ...
 
a7f8ee27
 3.2. sipt_set_bci_1(charge_indicator, called_status, called_category,
 e2e_indicator)
 
    updates the first byte of the backward call indicator in the ACM or COT
    in the body if setting the Charge Indicator to “charge_indicator”, the
    Called party's status indicator in “called_status”, the Called party's
    category indicator in “called_category” and the End to End Method
    Indicator with the value of the value of “e2e_indicator”.
 
    Example 1.2. sipt_destination(destination, hops, nai) usage
 ...
059c9a33
 # set bci for charging, subscriber free, ordinary, no e2e available
 sipt_set_bci_1("2", "1", "1", "0");
a7f8ee27
 ...
 
 3.3. sipt_set_calling(origin, nai, presentation, screening)
717cd63e
 
    updates the IAM in the body if it exists, setting (or adding) the
    calling party number to “origin” with the nature address specified in
    “nai” and setting the presentation and screening values to
    “presentation” and “screening”.
 
a7f8ee27
    Example 1.3. sipt_set_calling(origin, nai, presentation, screening)
717cd63e
    usage
 ...
 # update the calling party to the value in the from header
 sipt_set_calling($fU, 4, 0, 3);
 ...
 
02aa4892
 3.4. sipt_forwarding(origin, nai)
 
    updates the IAM in the body if it exists, setting (or adding) the
    forwarding number to “origin” with the nature address specified in
    “nai”.
 
    Example 1.4. sipt_set_calling(origin, nai) usage
 ...
 # update the forwarding number to the value in the from header
 sipt_forwarfing($avp(s:forwarding_number), 3);
 ...
 
d02ebb25
 4. Exported pseudo-variables
 
b0ab6f70
    4.1. $sipt(calling_party_number.presentation) / $sipt_presentation
    4.2. $sipt(calling_party_number.screening) / $sipt_screening
    4.3. $sipt(hop_counter) / $sipt_hop_counter
    4.4. $sipt(calling_party_category) / $sipt(cpc) / $sipt_cpc
    4.5. $sipt(calling_party_number.nature_of_address) /
           $sipt.(calling_party_number.nai) / $sipt_calling_party_nai
 
    4.6. $sipt(called_party_number.nature_of_address) /
           $sipt(called_party_number.nai) / $sipt_called_party_nai
 
    4.7. $sipt(event_info)
8ef89248
    4.8. $sipt(backward_call_indicator.charge_indicator)
02aa4892
    4.9. $sipt(redirection_info) / $sipt_redirection_info
    4.10. $sipt(redirection_number) / $sipt_redirection_number
    4.11. $sipt(redirection_number.nai) / $sipt_redirection_number_nai
d02ebb25
 
b0ab6f70
 4.1. $sipt(calling_party_number.presentation) / $sipt_presentation
d02ebb25
 
    Returns the value of the Address presentation restricted indicator
    contained in the Calling Party Number header of the IAM message if it
    exists. Returns -1 if there isn't a Calling Party Number header.
 
53319656
    Table 1.1. Address Presentation Restricted Indicator Values
    0 presentation allowed
    1 presentation restricted
    2 address not avail (national use)
    3 spare
 
02aa4892
    Example 1.5. sipt_presentation pseudo-variable usage
d02ebb25
 ...
 # add privacy header if restriction is requested
b0ab6f70
 if($sipt(calling_party_number.presentation) == 1)
d02ebb25
 {
         append_hf("Privacy: id\r\n");
         $fn = "Anonymous";
 }
 
 ...
 
b0ab6f70
 4.2. $sipt(calling_party_number.screening) / $sipt_screening
d02ebb25
 
    Returns the value of the Screening Indicator contained in the Calling
    Party Number header of the IAM message if it exists. Returns -1 if
    there isn't a Calling Party Number header.
 
53319656
    Table 1.2. Screening Indicator Values
    0 Reserved (user provided, not verified)
    1 User Provided, Verified and Passed
    2 Reserved (user provided, verified and failed)
    3 Network provided
 
02aa4892
    Example 1.6. sipt_screening pseudo-variable usage
d02ebb25
 ...
 
 # remove P-Asserted-Identity header if the screening isn't verified
 # or network provided
b0ab6f70
 $avp(s:screening) = $sipt(calling_party_number.screening);
d02ebb25
 if($avp(s:screening) != 1 && $avp(s:screening) != 3)
 {
         remove_hf("P-Asserted-Id");
 }
 
 ...
 
b0ab6f70
 4.3. $sipt(hop_counter) / $sipt_hop_counter
1eeae386
 
    Returns the value of the Hop Counter for the IAM message if it exists.
    Returns -1 if there isn't a hop counter.
 
02aa4892
    Example 1.7. sipt_hop_counter pseudo-variable usage
1eeae386
 ...
 # get the hop counter and update the Max-Forwards header if it exists
b0ab6f70
 $avp(s:hop) = $sipt(hop_counter);
1eeae386
 if($avp(s:hop) > 0)
 {
         remove_hf("Max-Forwards");
         append_hf("Max-Forwards: $avp(s:hop)\r\n");
 }
 
 ...
 
b0ab6f70
 4.4. $sipt(calling_party_category) / $sipt(cpc) / $sipt_cpc
1eeae386
 
    Returns the value of the Calling Party Category for the IAM message.
    Returns -1 if there is a parsing error.
 
02aa4892
    Example 1.8. sipt_cpc pseudo-variable usage
1eeae386
 ...
 # get the Cpc code and set put it in a custom sip header
b0ab6f70
 append_hf("X-CPC: $sipt(cpc)\r\n");
1eeae386
 
 ...
 
b0ab6f70
 4.5. $sipt(calling_party_number.nature_of_address) /
 $sipt.(calling_party_number.nai) / $sipt_calling_party_nai
1eeae386
 
    Returns the value of the Nature of Address Indicator of the Calling
    Party for the IAM message. Returns -1 if there is a parsing error or if
    the Calling Party Number is not present.
 
53319656
    Table 1.3. Calling Nature of Address Values
    0 Spare
    1 Subscriber Number (national use)
    2 Unknown (national use)
    3 National (significant) number (national use)
    4 International use
 
02aa4892
    Example 1.9. sipt_calling_party_nai pseudo-variable usage
1eeae386
 ...
 # get the Calling Nai and add country code if national
b0ab6f70
 if($sipt(calling_party_number.nai) == 3)
1eeae386
 {
         $fU = "32" + "$fU";
 }
 
 ...
 
b0ab6f70
 4.6. $sipt(called_party_number.nature_of_address) /
 $sipt(called_party_number.nai) / $sipt_called_party_nai
1eeae386
 
    Returns the value of the Nature of Address Indicator of the Called
    Party for the IAM message. Returns -1 if there is a parsing error.
 
53319656
    Table 1.4. Called Nature of Address Values
    0 Spare
    1 Subscriber Number (national use)
    2 Unknown (national use)
    3 National (significant) number
    4 International use
    5 Network-specific number (national use)
 
02aa4892
    Example 1.10. sipt_called_party_nai pseudo-variable usage
1eeae386
 ...
 # get the Called Nai and add country code if national
b0ab6f70
 if($sipt(called_party_number.nai) == 3)
1eeae386
 {
         $rU = "32" + "$rU";
 }
 
 ...
a4297694
 
b0ab6f70
 4.7. $sipt(event_info)
a4297694
 
    Returns the value of the Event Info header of the CPG message. Returns
    -1 if there is a parsing error.
 
    Table 1.5. Event Info Values
    0 Spare
    1 ALERTING
    2 PROGRESS
    3 In-band information or an appropriate pattern is now available
    4 Call forward on busy
    5 Call forward on no reply
    6 Call forward unconditional
8ef89248
 
 4.8. $sipt(backward_call_indicator.charge_indicator)
 
    Returns the value of the charge indication of the backward call
    indicator header in the ACM or COT message. Returns -1 if there is a
    parsing error.
 
    Table 1.6. Charge Indicator Values
    0 no indication
    1 no charge
    2 charge
    3 spare
02aa4892
 
 4.9. $sipt(redirection_info) / $sipt_redirection_info
 
    Returns redirection info header from ISUP Returns "Redirecting reason"
    or -1 if no redirection info found.
 
    Table 1.7. Redirecting reason Values
    0 Unknown
    1 User busy
    2 PROGRESS
    3 no reply
    4 deflection during alerting
    5 deflection immediate response
    6 mobile subscriber not reachable
 
 4.10. $sipt(redirection_number) / $sipt_redirection_number
 
    Returns number to which redirection will trigered Returns -1 if there
    is a parsing error.
 
    Example 1.11. sipt_redirection_number usage
 ...
 # get the redirection number
 $avp(s:redir_num) = $sipt(redirection_number);
 
 ...
 
 4.11. $sipt(redirection_number.nai) / $sipt_redirection_number_nai
 
    Returns NAI for redirection number from ISUP Returns NAI for
    redirection number or -1 if no info found.
 
    Table 1.8. Redirecting number NAI Values
    0 Spare
    1 Subscriber Number (national use)
    2 Unknown (national use)
    3 National (significant) number (national use)
    4 International use