modules/sipt: add ability to check charging indicator

modules/sipt/doc/sipt.txt

@@ -0,0 +1,323 @@
+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)
+              3.2. sipt_set_bci_1(charge_indicator, called_status,
+                      called_category, e2e_indicator)
+
+              3.3. sipt_set_calling(origin, nai, presentation, screening)
+
+        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(called_party_number.nature_of_address) /
+                      $sipt(called_party_number.nai) /
+                      $sipt_called_party_nai
+
+              4.7. $sipt(event_info)
+              4.8. $sipt(backward_call_indicator.charge_indicator)
+
+   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
+
+   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_presentation pseudo-variable usage
+   1.5. sipt_screening pseudo-variable usage
+   1.6. sipt_hop_counter pseudo-variable usage
+   1.7. sipt_cpc pseudo-variable usage
+   1.8. sipt_calling_party_nai pseudo-variable usage
+   1.9. sipt_called_party_nai pseudo-variable usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+   3. Functions
+
+        3.1. sipt_destination(destination, hops, nai)
+        3.2. sipt_set_bci_1(charge_indicator, called_status,
+                called_category, e2e_indicator)
+
+        3.3. sipt_set_calling(origin, nai, presentation, screening)
+
+   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(called_party_number.nature_of_address) /
+                $sipt(called_party_number.nai) / $sipt_called_party_nai
+
+        4.7. $sipt(event_info)
+        4.8. $sipt(backward_call_indicator.charge_indicator)
+
+1. Overview
+
+   Module for updating ISUP encapuslated 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 the other words the
+   listed modules must be loaded before this module):
+     * none
+
+3. Functions
+
+   3.1. sipt_destination(destination, hops, nai)
+   3.2. sipt_set_bci_1(charge_indicator, called_status, called_category,
+          e2e_indicator)
+
+   3.3. sipt_set_calling(origin, nai, presentation, screening)
+
+3.1. sipt_destination(destination, hops, nai)
+
+   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”.
+
+   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);
+...
+
+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(called_party_number.nature_of_address) /
+          $sipt(called_party_number.nai) / $sipt_called_party_nai
+
+   4.7. $sipt(event_info)
+   4.8. $sipt(backward_call_indicator.charge_indicator)
+
+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.4. 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.5. 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.6. 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.7. 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.8. 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(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.9. 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.7. $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.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