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

              3.1. sipt_destination(destination, hops, nai[,
                      terminator=1])

              3.2. sipt_set_bci_1(charge_indicator, called_status,
                      called_category, e2e_indicator)

              3.3. sipt_set_calling(origin, nai, presentation, screening)
              3.4. sipt_forwarding(origin, nai)
              3.5. sipt_has_isup_body()

        4. Exported pseudo-variables

              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(calling_party_number)
              4.7. $sipt(called_party_number.nature_of_address) /
                      $sipt(called_party_number.nai) /
                      $sipt_called_party_nai

              4.8. $sipt(called_party_number)
              4.9. $sipt(event_info)
              4.10. $sipt(backward_call_indicator.charge_indicator)
              4.11. $sipt(redirection_info) / $sipt_redirection_info
              4.12. $sipt(redirection_number) / $sipt_redirection_number
              4.13. $sipt(redirection_number.nai) /
                      $sipt_redirection_number_nai

              4.14. $sipt(redirection_information.reason)
              4.15. $sipt(redirection_information.original_reason)
              4.16. $sipt(redirecting_number.nai)
              4.17. $sipt(redirecting_number)
              4.18. $sipt(original_called_number.nai)
              4.19. $sipt(original_called_number)
              4.20. $sipt(generic_number.nai)
              4.21. $sipt(generic_number)

   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
   1.5. Event Info Values
   1.6. Charge Indicator Values
   1.7. Redirecting reason Values
   1.8. Redirecting number NAI Values

   List of Examples

   1.1. sipt_destination(destination, hops, nai) usage
   1.2. sipt_destination(destination, hops, nai) usage
   1.3. sipt_set_calling(origin, nai, presentation, screening) usage
   1.4. sipt_set_calling(origin, nai) usage
   1.5. sipt_has_isup_body() usage
   1.6. sipt_presentation pseudo-variable usage
   1.7. sipt_screening pseudo-variable usage
   1.8. sipt_hop_counter pseudo-variable usage
   1.9. sipt_cpc pseudo-variable usage
   1.10. sipt_calling_party_nai pseudo-variable usage
   1.11. sipt_called_party_nai pseudo-variable usage
   1.12. sipt_redirection_number usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies
   3. Functions

        3.1. sipt_destination(destination, hops, nai[, terminator=1])
        3.2. sipt_set_bci_1(charge_indicator, called_status,
                called_category, e2e_indicator)

        3.3. sipt_set_calling(origin, nai, presentation, screening)
        3.4. sipt_forwarding(origin, nai)
        3.5. sipt_has_isup_body()

   4. Exported pseudo-variables

        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(calling_party_number)
        4.7. $sipt(called_party_number.nature_of_address) /
                $sipt(called_party_number.nai) / $sipt_called_party_nai

        4.8. $sipt(called_party_number)
        4.9. $sipt(event_info)
        4.10. $sipt(backward_call_indicator.charge_indicator)
        4.11. $sipt(redirection_info) / $sipt_redirection_info
        4.12. $sipt(redirection_number) / $sipt_redirection_number
        4.13. $sipt(redirection_number.nai) / $sipt_redirection_number_nai
        4.14. $sipt(redirection_information.reason)
        4.15. $sipt(redirection_information.original_reason)
        4.16. $sipt(redirecting_number.nai)
        4.17. $sipt(redirecting_number)
        4.18. $sipt(original_called_number.nai)
        4.19. $sipt(original_called_number)
        4.20. $sipt(generic_number.nai)
        4.21. $sipt(generic_number)

1. Overview

   Module for updating ISUP encapsulated in SIP (SIP-T/SIP-I)

   The sipt module can be used to update various ss7 headers contained
   inside a message.

2. Dependencies

   The module depends on the following modules (in other words the listed
   modules must be loaded before this module):
     * none

3. Functions

   3.1. sipt_destination(destination, hops, nai[, terminator=1])
   3.2. sipt_set_bci_1(charge_indicator, called_status, called_category,
          e2e_indicator)

   3.3. sipt_set_calling(origin, nai, presentation, screening)
   3.4. sipt_forwarding(origin, nai)
   3.5. sipt_has_isup_body()

3.1. sipt_destination(destination, hops, nai[, terminator=1])

   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
   header is missing it will be added with the value of “hops”. If
   “terminator” is set to 1, then F will be appended to digit string to
   indicate the number is complete (default).

   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);
...

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
...
# set bci for charging, subscriber free, ordinary, no e2e available
sipt_set_bci_1("2", "1", "1", "0");
...

3.3. sipt_set_calling(origin, nai, presentation, screening)

   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”.

   Example 1.3. sipt_set_calling(origin, nai, presentation, screening)
   usage
...
# update the calling party to the value in the from header
sipt_set_calling($fU, 4, 0, 3);
...

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_forwarding($avp(s:forwarding_number), 3);
...

3.5. sipt_has_isup_body()

   The function returns true if the SIP message has an ISUP body attached.

   Example 1.5. sipt_has_isup_body() usage
...
if(sipt_has_isup_body())
{
    # do interesting stuff here
}
...

4. Exported pseudo-variables

   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(calling_party_number)
   4.7. $sipt(called_party_number.nature_of_address) /
          $sipt(called_party_number.nai) / $sipt_called_party_nai

   4.8. $sipt(called_party_number)
   4.9. $sipt(event_info)
   4.10. $sipt(backward_call_indicator.charge_indicator)
   4.11. $sipt(redirection_info) / $sipt_redirection_info
   4.12. $sipt(redirection_number) / $sipt_redirection_number
   4.13. $sipt(redirection_number.nai) / $sipt_redirection_number_nai
   4.14. $sipt(redirection_information.reason)
   4.15. $sipt(redirection_information.original_reason)
   4.16. $sipt(redirecting_number.nai)
   4.17. $sipt(redirecting_number)
   4.18. $sipt(original_called_number.nai)
   4.19. $sipt(original_called_number)
   4.20. $sipt(generic_number.nai)
   4.21. $sipt(generic_number)

4.1. $sipt(calling_party_number.presentation) / $sipt_presentation

   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.

   Table 1.1. Address Presentation Restricted Indicator Values
   0 presentation allowed
   1 presentation restricted
   2 address not avail (national use)
   3 spare

   Example 1.6. sipt_presentation pseudo-variable usage
...
# add privacy header if restriction is requested
if($sipt(calling_party_number.presentation) == 1)
{
        append_hf("Privacy: id\r\n");
        $fn = "Anonymous";
}

...

4.2. $sipt(calling_party_number.screening) / $sipt_screening

   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.

   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

   Example 1.7. sipt_screening pseudo-variable usage
...

# remove P-Asserted-Identity header if the screening isn't verified
# or network provided
$avp(s:screening) = $sipt(calling_party_number.screening);
if($avp(s:screening) != 1 && $avp(s:screening) != 3)
{
        remove_hf("P-Asserted-Id");
}

...

4.3. $sipt(hop_counter) / $sipt_hop_counter

   Returns the value of the Hop Counter for the IAM message if it exists.
   Returns -1 if there isn't a hop counter.

   Example 1.8. sipt_hop_counter pseudo-variable usage
...
# get the hop counter and update the Max-Forwards header if it exists
$avp(s:hop) = $sipt(hop_counter);
if($avp(s:hop) > 0)
{
        remove_hf("Max-Forwards");
        append_hf("Max-Forwards: $avp(s:hop)\r\n");
}

...

4.4. $sipt(calling_party_category) / $sipt(cpc) / $sipt_cpc

   Returns the value of the Calling Party Category for the IAM message.
   Returns -1 if there is a parsing error.

   Example 1.9. sipt_cpc pseudo-variable usage
...
# get the Cpc code and set put it in a custom sip header
append_hf("X-CPC: $sipt(cpc)\r\n");

...

4.5. $sipt(calling_party_number.nature_of_address) /
$sipt.(calling_party_number.nai) / $sipt_calling_party_nai

   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.

   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

   Example 1.10. sipt_calling_party_nai pseudo-variable usage
...
# get the Calling Nai and add country code if national
if($sipt(calling_party_number.nai) == 3)
{
        $fU = "32" + "$fU";
}

...

4.6. $sipt(calling_party_number)

   Returns the value (Address signal) 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.

4.7. $sipt(called_party_number.nature_of_address) /
$sipt(called_party_number.nai) / $sipt_called_party_nai

   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.

   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)

   Example 1.11. sipt_called_party_nai pseudo-variable usage
...
# get the Called Nai and add country code if national
if($sipt(called_party_number.nai) == 3)
{
        $rU = "32" + "$rU";
}

...

4.8. $sipt(called_party_number)

   Returns the value (Address signal) of the Called Party for the IAM
   message. Returns -1 if there is a parsing error or if the Called Party
   Number is not present.

4.9. $sipt(event_info)

   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

4.10. $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

4.11. $sipt(redirection_info) / $sipt_redirection_info

   Returns call diversion information header from ISUP Returns
   "Redirecting reason" or -1 if no call diversion information 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.12. $sipt(redirection_number) / $sipt_redirection_number

   Returns number to which redirection will triggered Returns -1 if there
   is a parsing error.

   Example 1.12. sipt_redirection_number usage
...
# get the redirection number
$avp(s:redir_num) = $sipt(redirection_number);

...

4.13. $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

4.14. $sipt(redirection_information.reason)

   Returns redirection reason from Redirection information from ISUP or -1
   if no Redirection information found.

4.15. $sipt(redirection_information.original_reason)

   Returns original redirection reason from Redirection information from
   ISUP or -1 if no Redirection information found.

4.16. $sipt(redirecting_number.nai)

   Returns NAI for redirecting number from ISUP or -1 if no redirecting
   number found.

4.17. $sipt(redirecting_number)

   Returns redirecting number from ISUP or -1 if no redirecting number
   found.

4.18. $sipt(original_called_number.nai)

   Returns NAI for original called number from ISUP or -1 if no original
   called number found.

4.19. $sipt(original_called_number)

   Returns original called number from ISUP or -1 if no original called
   number found.

4.20. $sipt(generic_number.nai)

   Returns NAI for generic number from ISUP or -1 if no generic number
   found.

4.21. $sipt(generic_number)

   Returns generic number from ISUP or -1 if no generic number found.
