TBwiki - User contributions [en]

Routing script tutorial:Mini Development Guide

2016-10-13T21:01:40Z

Jasmin Letendre: Minor edit.

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call params from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", gateway will try them one by one in the same order they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example

called_number = call[:called]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Called party number' IE - address signals 
| SIP:RequestURI - rn 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| (read-only) 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| (read-only) 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at input of routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== request_uri_forward_enabled values ===

Controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The value for this parameter at input of routing script is always false. 

=== sip_header values ===
Contains a hash table of custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}

p_access_network_info = call[ :sip_header ][ 'P-Access-Network-Info' ] = "3GPP-E-UTRAN-FDD; utran-cell-id-3gpp=XYZ"
</pre>

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== sip uri parameters ===
Access to parameters of several SIP headers (To, From, P-Asserted-Identity, Remote-Party-ID, Contact).

<pre>
call[ :calling_parameters ]
call[ :called_parameters ]
call[ :private_address_parameters ] (for P-Asserted-Identity or Remote-Party-ID)
call[ :contact_parameters ]
</pre>

These parameters (if present) contains a hash with 3 keys: user_param, uri_param and header_param.
If a param has already a specific field (oli, isub, cpc, transport), it won't be present in the new generic structure.
By default, all parameters will be forwarded in a SIP to SIP call flow.

Using this code in routing script:
<pre>
puts "calling_param = #{ call[ :calling_parameters].inspect}"
</pre>

Example, From header versus the call[ :calling_parameters] value:
<pre>
From:"test"<sip:4440000;user_param1=1;user_param2@10.3.10.217;uri_param3=3>;header_param4=4;tag=6F97303034343030002A2484
calling_param = {"user_param"=>"user_param1=1;user_param2", "uri_param"=>"uri_param3=3", "header_param"=>"header_param4=4"}
</pre>

<pre>
From:"test"<sip:4440000@10.3.10.217;user=phone>;tag=6F97303034343030002A2484
calling_param = {"uri_param"=>"user=phone"}
</pre>

Example to insert outgoing parameters and overwrite received values.
<pre>
call [:calling_parameters] = {"user_param"=>"user_param7=7;user_param8", "uri_param"=>"uri_param9=9", "header_param"=>"header_paramA=A"}
</pre>

Example to add user=phone and keep all other uri parameters.
<pre>
if call [:calling_parameters]
if call [:calling_parameters]["uri_param"]
call[:calling_parameters]["uri_param"] << ";user=phone"
else
call [:calling_parameters]["uri_param"] = "user=phone"
end
else
call [:calling_parameters] = {"uri_param"=>"user=phone"}
end
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

The following sections show how to access those different parameters from '''inside''' a filter. The 'params' hash is the sole argument passed to a filter function and contains call, nap, route and bridge parameters. This hash is created by the base_routing.rb scripts to regroup all relevant information just before calling the filter functions.

=== Tone string format ===

All tone strings (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters are using this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows to enable tone detection during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raises RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded or not to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = []
bridge[ :diversion_reason ] << :busy
bridge[ :diversion_reason ] << :unconditional
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number_reason_values|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows to relay [[Call transfer]] requests from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These field are 'read-only'. They won't be included in the outgoing call, as they represent the content of the call transfer request, not the outgoing call to make.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128",
:raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129",
:raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150",
:raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"asr_statistics_struct" Detailed Answer-Seizure Rate Statistics.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"availability_detection_struct" Detailed availibility detection Statistics
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"registration_struct" Detailed registration Statistics
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered

 If the nap status is part of a substructure, it's name in the routing scripts must be composed of the structure name appended by an underscore and the field name.

For example the name to use for the global [[ASR]] percentage is:

asr_statistics_struct_global_asr_percent

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

[[category:Needs revising]]

Routing script tutorial:Mini Development Guide

2016-08-09T16:30:45Z

Jasmin Letendre: Added value "video" for "information_transfer_capability"

== Call object ==

=== Get ===

This function is used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call params from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", gateway will try them one by one in the same order they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object. For example

called_number = call[:called]

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763
ITU97: 'Display information' IE - display information
ANSI95: 'Generic name' IE - display information
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Called party number' IE - address signals 
| SIP:RequestURI - rn 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| (read-only) 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| (read-only) 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|-
| reverse_charging_indication 
| Incoming leg Reverse charging indication IE present 
| N/A 
| N/A 
| N/A 
| If set in routing script, will add Reverse charging indication IE in outgoing leg (also use reverse_charging_indication_forward_enabled) 
| 2.8.12 
|-
| reverse_charging_indication_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Enable forwarding of reverse charging indication from incoming to outgoing leg 
| 2.8.12 
|-
| sip_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SIP UDP port 
| (read-only) 
| 2.8.13 
|-
| sip_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP IP address 
| (read-only) 
| 2.8.13 
|-
| sip_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SIP UDP port 
| (read-only) 
| 2.8.13 
|}

 

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>
*<tt>video</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
*0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg
*1/true: Redirecting number (and original called number) is forwarded to outgoing call leg

The value for this parameter at input of routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

Note: To "insert" a new redirecting number value on the outgoing leg, redirecting_number_forward_enabled must also be set to true.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== request_uri_forward_enabled values ===

Controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

* 0/false: Request uri is not forwarded to outgoing call leg 

* 1/true: Request uri is forwarded to outgoing call leg 

The value for this parameter at input of routing script is always false. 

=== sip_header values ===
Contains a hash table of custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}

p_access_network_info = call[ :sip_header ][ 'P-Access-Network-Info' ] = "3GPP-E-UTRAN-FDD; utran-cell-id-3gpp=XYZ"
</pre>

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

=== Network Identification Plan ===

network_identification_plan:

*<tt>Unknown</tt> (value 0)
*<tt>cic</tt> (3 digits carrier identification code plus circuit code, value 1, SS7 or ISDN)
*<tt>user</tt> (User, value 2, ISDN only)
*<tt>cic4</tt> (4 digits carrier identification code plus circuit code, value 2, SS7 only)
*<tt>dnic</tt> (public Data Network ID, value 3, SS7 only)
*<tt>mnic</tt> (public land mobile network, value 6, SS7 only)

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_destination_leg_profile (called remapped_profile prior to Toolpack 2.9)
*remapped_source_leg_profile (called remapped_incoming_profile prior to Toolpack 2.9)

Example:

route[:remapped_nap]

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts (audio files) in different states of the call flow.

*'''announcement_tone''' (played before outgoing call is routed)
*'''ring_tone''' (played after when waiting for outgoing call to answer)
*'''busy_tone''' (played if outgoing call failed)
*'''disconnect_tone''' (played after the call has reached it's maximum duration)

The following sections show how to access those different parameters from '''inside''' a filter. The 'params' hash is the sole argument passed to a filter function and contains call, nap, route and bridge parameters. This hash is created by the base_routing.rb scripts to regroup all relevant information just before calling the filter functions.

=== Tone string format ===

All tone strings (:announcement_tone, :busy_tone, :ring_tone, :disconnect_tone) inside bridge parameters are using this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
Optional parameters:
* repeat: number of times to play the file (0 and 1 have the same result)
* start_off: Start offset in milliseconds
* end_off: End offset in milliseconds

Http and other path formats are described here: [[Customer_application_framework:play_audio_files#Play_path_format|Path format]]

==== Example 1 ====
The following example will play file1.wav once, and then play file2.wav in loop:
"file1.wav,file2.wav:-1"

==== Example 2 ====
The following example will play file1.wav from start offset of 1 second to end offset of 3 seconds, then twice file2.wav from second 5 to second 10.
"file1.wav:0:1000:3000,file2.wav:2:5000:10000"

==== Example 3 ====
The following example will play file1.wav once, ending at offset of 30 seconds.
"file1.wav:0:0:30000"

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Audio file played on the incoming call before any outgoing call is placed. The outgoing call occurs when the file finished playing.

==== announcement_tone options ====
===== announcement_tone_answer =====
params[:bridge][:announcement_tone_answer] = "yes"

Forces an answer of the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

===== announcement_code_detect =====
This option allows to enable tone detection during the announcement play.

Collected digits can be inserted into the CDR logs (radius attribute "Telcob-CollectedDigits", or text CDR variable @{CollectedDigits}).

Collected digits can also be sent back to routing script, which is called again with the same call attributes, except that the called number is replaced by the collected digits.

Code detect has multiple options, as shown in the following code:
code_detect = {
:type => :DTMF, # :DTMF or :MFR1 tone detection.
# Default is MFR1.
:prefix => "", # Prefix (digits) that is removed from collected digits.
# Default is empty.
:suffix => "", # Suffix (digits) that is removed from collected digits
# and causes routing script to be immediately called.
# Default is empty.
:suffix_removal => false, # Controls the removal of the suffix from the collected digit string that's reported to routing script.
# Default is false
:timeout => 0, # Inter-digit timeout (ms) after which collected digits are passed to the routing script.
# Use 0 for "no timeout".
# Default is 1000ms
:barge_in_interruption => true, # When enabled, playing announcement is stopped as soon as first digit is collected.
# Default is true.
:proceed_on_play_done => false, # When true: Outgoing call is made after announcement finishes playing.
# Routing script is not called again.
# When false: Outgoing call is never made.
# Digits are collected until timeout or suffix match,
# then routing script is called again.
# Default is false.
:cas_on_hook => false, # Specific for CAS-R1 calls. Makes CAS bits switch to "on-hook" when announcement finished playing
# (but the call is not "terminated" from Toolpack point of view)
# Default is false.
:cas_on_hook_delay => 0, # Duration of cas bits "on-hook" state.
# Only effective if cas_on_hook is set to true.
# Value of 0 stands for "infinite delay".
# Default is 0.
:repeat_delay => 0, # Delay between repetition of the announcement. The announcement will repeat
# itself every "repeat_delay" until a code is detected (suffix match or timetout).
# Value of 0 stands for "infinite delay" (no repeating).
# Default is 0.
}
'''Example 1''': Collect DTMF digits, and call routing script again with collected digits upon timeout or suffix match.
code_detect = { :type => :DTMF, :suffix => "#", :timeout => 5000 }
params[:bridge][:announcement_code_detect] = code_detect

'''Example 2''': Collect digits during the announcement (for CDR logs), then proceed (make outgoing call) after announcement finishes playing
code_detect = { :type => :DTMF, :timeout => 0, :barge_in_interruption => false, :proceed_on_play_done => true }
params[:bridge][:announcement_code_detect] = code_detect

==== Controlling what happens after announcement ====
The routing script can control what happens with the call after the announcement finishes playing:
* An outgoing call is made
* Incoming call is hung-up
* Do nothing (wait for the incoming call to hang-up)
===== An outgoing call is made =====
This happens when the script has returned matching routes (and did not raise RoutingException)

===== Incoming call is hung-up =====
This happens when the script returns no routes (in which case base_routing will raises RoutingException with cause :no_route).

It also happens when the script explicitly raises RoutingException.

The incoming call will be terminated with the specified cause.
For example
raise RoutingException, :temporary_failure
(See "Reason values" section in this page for list of available causes)

===== Do nothing (wait for the incoming call to hang-up) =====
If a filter raises RoutingException with code :ok, then the incoming call will not be terminated at the end of the announcement play.
Announcement digit collection will remain active if appropriate.
For example:
raise RoutingException, :ok

=== ring_tone ===
params[:bridge][:ring_tone] = "ringing.wav"

Audio file played on the incoming call while waiting for the outgoing call to be answered.

Ring tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:ring_tone] will override the profile's ring tone behavior).

==== ring_tone options ====
===== ring_tone_state =====
params[:bridge][:ring_tone_state] = :alerted

Call state from which ring tone is being played. Available values are:
* '''immediately''': Ring tone starts playing immediately on the incoming leg
* '''accepted''': Ring tone starts playing as soon as outgoing call is accepted
* '''callprogress''': Ring tone starts playing as soon as "call progress" is received on the outgoing call
* '''alerted''' (default): Ring tone starts playing only once outgoing call is alerted (but won't play if alert indicates early media from outgoing call)

This option also apply when params[:bridge][:ring_tone] is not used, because it also apply to ring tone playback configured in the Web Portal, from the incoming call's profile.

=== busy_tone ===
Toolpack 2.8 and above:
params[:bridge][:busy_tone] = "no_route.wav"

Note: Obsolete name (toolpack 2.7.153 and earlier, but still supported in recent releases):
params[:bridge][:call_progress_tone] = "no_route.wav"

Audio file played on the incoming call when outgoing call fails (never answered).

Note that announcement_tone, if used, is played before the outgoing call attempt is made, and thus before the busy_tone.

Busy tone playback can also be configured in the Web Portal, from the incoming call's profile (under "Tones and Call Progress Options").

Routing script has precedence over profile (a routing script that fills params[:bridge][:busy_tone] will override the profile's busy tone behavior).

Special value '''"none"''' can be used by routing script to force playing nothing (as empty string would default to profile's behavior)

==== busy_tone options ====
===== busy_tone_answer =====
params[:bridge][:busy_tone_answer] = "yes"

Forces an answer of the call before playing the busy tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== disconnect_tone ===
params[:bridge][:disconnect_tone] = "max_duration.wav"

Audio file played on the incoming call when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone options ====
===== max_call_duration =====
params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond. This timer is started when entering answer state.

===== call_duration_reason =====
params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

==== The default (replicated) prompts folder ====
By default, when playing a prompt, Toolpack will look in the default prompts folder:
/lib/tb/toolpack/pkg/prompts
The root of this "prompts" directory is automatically replicated to secondary unit of redundant setups (1+1, N+1, redundant hosts). Sub-folders won't be replicated.

Any prompt play request without explicit file path will map to this folder. For example:
params[:bridge][:busy_tone] = "no_route.wav"
This will correspond to file /lib/tb/toolpack/pkg/prompts/no_route.wav

==== Relative file paths ====
Any file path that begins with "file://" is considered relative to the tbstreamserver application's working directory:
/lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/
(Where "2.8" may be replaced by the current major version of your system)

For example:
params[:bridge][:busy_tone] = "file://my_folder/no_route.wav"
This will correspond to file /lib/tb/toolpack/setup/12358/2.8/apps/tbstreamserver/my_folder/no_route.wav

==== Absolute file paths ====
Absolute paths can also be provided.
For example:
params[:bridge][:busy_tone] = "file:///root/my_folder/no_route.wav"
This will correspond to file /root/my_folder/no_route.wav

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{CURRENT_PKG}: Version of current package
*** Example: 2.6.45
** @{DATE format}: Prints the date, where 'format' is expressed as described for the 'strftime' function
*** Example: @{DATE %Y-%m-%d} => 2013-01-28
** @{DefaultName}: Replaced by the default file name for recording, which contains:
*** LinkId: Id common between all legs of this call bridge
*** LegId: Unique Id for this leg
*** Nap: Current NAP name this call leg is from
*** Direction: "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
*** Calling: Calling number
*** Called: Called number
*** Protocol: Protocol type of this call (SS7, ISDN, CASR2, SIP)
*** Media info: Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Default recording folder and file name: "@{RECORD_PATH}/@{DATE %Y-%m-%d}/@{DefaultName}"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{Direction}: Direction of current leg (IN our OUT)
*** Example: IN
** @{LegId}: Current LegId (Unique Id for this leg)
*** Example: F3D67B4B
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: 73EBA698
** @{PKG_HOME}: Path where packages are stored.
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg
** @{PROMPT_PATH}: Default path where audio prompts are stored
*** Note: It's not recomended to use that path on redundant systems, package file replication may cause confusion in recorded files.
*** Example: /lib/tb/toolpack/pkg/prompts
** @{Protocol}: Protocol of current leg
*** Example: SS7
** @{RECORD_PATH}: Default recording folder: "@{TB_SETUP_HOME}/recorded_calls/"
** @{TBX_GW_PORT}: Current "System Id" (also called "Gateway Port")
*** Example: 12358
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Controlling UUI (user-to-user information) relay ==
UUI (user-to-user information) can be present in different messages received by either call leg during a call. For example, information can be carried during the initial invite, other information can be carried when the call is alerted, answered, or terminated.

Routing scripts can control if the UUI received from one leg through the call will be forwarded or not to the other call leg:
*uui_forward_enabled

Routing scripts can also read and modify the UUI received with the incoming call leg, before it gets forwarded upon creation of the outgoing call leg:
*uui

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true.
* 0/false: UUI is not forwarded between call legs
* 1/true: UUI is forwarded between call legs

The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = []
bridge[ :diversion_reason ] << :busy
bridge[ :diversion_reason ] << :unconditional
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number_reason_values|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows to relay [[Call transfer]] requests from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These field are 'read-only'. They won't be included in the outgoing call, as they represent the content of the call transfer request, not the outgoing call to make.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Redirection ==
In release 2.8 and above, redirection contacts are obtained from the routing engine in the following format:

contacts = params[ :contacts ]
contacts = {
:index=>"3",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
{:called_number=>"6662", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6662@192.168.215.128",
:raw_data=>"<sip:6662@192.168.215.128>", :expiration=>"3600"},
{:called_number=>"6663", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6663@192.168.215.129",
:raw_data=>"<sip:6663@192.168.215.129>", :expiration=>"3600"},
{:called_number=>"6664", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6664@192.168.215.150",
:raw_data=>"<sip:6664@192.168.215.150>", :expiration=>"3600"}
],
:source_indexes=>"nil,0,0,0,2"
}

* <code>params[:contacts][:list]</code> contains the contact log. Each contact within the list has the following fields:
** <code>:called_number</code> - the called number
** <code>:is_number_ported</code> - if the called number has been ported (for SIP: if the npdi parameter is present)
** <code>:ported_number</code> - the called number that was ported (for SIP: the rn parameter value, if available)
** <code>:sip_uri</code> - the SIP URI of the contact, without the contact-params section (without the expires and q contact parameters)
** <code>:raw_data</code> - the raw data representing the contact in the signaling protocol. For SIP, this is the full SIP URI (including the expires and q contact parameters).
** <code>:priority</code> - the priority of the contact [0-1000]
** <code>:expiration</code> - the expiration time in seconds of the contact
* <code>params[:contacts][:index]</code> contains the index of the contact that is currently being routed.
* <code>params[:contacts][:source_indexes]</code> contains a comma-separated list of indexes from <code>params[:contacts][:list]</code>. Each index represents the contact from which the contact in the list was obtained from.

To get more information, see:
*[[Routing_script_tutorial:SIP_Redirection_Contacts|SIP Redirection Contacts Parameters in a Call Flow]]

== Terminating calls ==
In release 2.8, it is now possible to terminate a call through the routing scripts. The [[#Reason values|reason code]] must be specified in <code>params[:bridge][:reason]</code>. The <code>:terminate</code> hash must be created and copied into <code>params</code>:
terminate = {}
params[:terminate] = terminate
The following fields can then be set in <code>:terminate</code>:
* <code>:sip_header</code>
* <code>:contacts</code> # list of contacts as described in the [[#Redirection|redirection]] section
* <code>:isup_raw</code>
* <code>:isup_raw_variant</code>
* <code>:redirecting_number</code>
* <code>:redirecting_number_noa</code>
* <code>:redirecting_number_npi</code>
* <code>:redirecting_number_presentation</code>
* <code>:redirecting_number_reason</code>
* <code>:redirecting_number_counter</code>
* <code>:redirecting_number_indicator</code>
* <code>:original_called_number</code>
* <code>:original_called_number_noa</code>
* <code>:original_called_number_npi</code>
* <code>:original_called_number_presentation</code>
* <code>:original_called_number_reason</code>
* <code>:original_called_number_counter</code>

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:qor_ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_cug
:incoming_calls_barred
:incoming_calls_barred_within_cug
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_cug
:incompatible_destination
:non_existant_cug
:invalid_transit_network
:invalid_message_unspecified
:mandatory_ie_missing
:message_type_non_existent
:message_not_compatible_with_call_state
:ie_non_existent
:invalid_ie_content
:msg_not_compatible_with_call_state
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:message_with_non_recognized_parameters_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_ie or :missing_or_invalid_ie
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes: 
Reason causes starting with a digit must use the following syntax (can't use : as prefix).

'300_multiple_choices'
'301_moved_permanently'
'302_moved_temporarily'
'305_use_proxy'
'380_alternative_service'
'400_bad_request'
'401_unauthorized'
'402_payment_required'
'403_forbidden'
'404_not_found'
'405_method_not_allowed'
'406_not_acceptable'
'407_proxy_authentication_required'
'408_request_timeout'
'409_conflict'
'410_gone'
'413_request_entity_too_large'
'414_request_URI_too_long'
'415_unsupported_media'
'416_unsupported_URI_scheme'
'420_bad_extension'
'421_extension_required'
'422_session_timer_too_small'
'423_interval_too_brief'
'429_referrer_identity_error'
'480_temporary_unavailable'
'481_call_or_transaction_does_not_exist'
'482_loop_detected'
'483_too_many_hops'
'484_address_incomplete'
'485_ambiguous'
'486_busy_here'
'487_request_terminated'
'488_not_acceptable_here'
'489_bad_event'
'491_retry_after'
'500_server_internal_error'
'501_not_implemented'
'502_bad_gateway'
'503_service_unavailable'
'504_server_timeout'
'505_version_unsupported'
'513_message_too_large'
'600_busy_everywhere'
'603_decline'
'604_not_exist_anywhere'
'606_not_acceptable'

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"signaling_type" Signaling type (SS7, ISDN, CASR2, SIP)
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"asr_statistics_struct" Detailed Answer-Seizure Rate Statistics.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"availability_detection_struct" Detailed availibility detection Statistics
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"registration_struct" Detailed registration Statistics
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered

 If the nap status is part of a substructure, it's name in the routing scripts must be composed of the structure name appended by an underscore and the field name.

For example the name to use for the global [[ASR]] percentage is:

asr_statistics_struct_global_asr_percent

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

@params = {
:bridge => {:announcement_tone, "announcement.wav"},
:contacts => {
:index=>"1",
:list=>[
{:called_number=>"6660", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"",
:raw_data=>"", :expiration=>"3600"},
{:called_number=>"6661", :priority=>"1000", :is_number_ported=>"0", :sip_uri=>"sip:6661@192.168.215.127",
:raw_data=>"<sip:6661@192.168.215.127>", :expiration=>"3600"}
],
:source_indexes=>"nil,0"
}
}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

[[category:Needs revising]]

Toolpack monitoring

2016-04-22T13:28:18Z

Jasmin Letendre: /* Built-in monitoring analyzers */

The [[Tmonitor]] and [[Tmedia]] products both support [[Network_monitoring]].

Monitoring features can be controlled with the [[Toolpack API]].

Using these APIs, the Toolpack Gateway application supports built-in protocol analyzers that allow to monitor a TDM network, generate CDR logs and notify external applications of monitored TDM calls.

=== The Toolpack Monitoring API ===
[[Image:Monitoring_API_overview.png|thumb|300px]]
The Toolpack monitoring API consists of function calls on the call leg class:
* StartMonitoring
* StopMonitoring
Corresponding events notify the call flow of monitoring state
* OnMonitoringStarted
* OnMonitoringDataReceived

An application that need to do monitoring will first allocate media legs on the appropriate Line Service and Timeslot, then use the StartMonitoring function call to configure the monitoring parameters.
Among parameters, will be chosen:
* Mode (HDLC, SS7, CAS, RAW)
* Rate (64Kbps, 56Kbps, 48Kbps, 32Kbps, 16Kbps or 8Kbps)
* Timeslot sub-index (for rates of 32Kbps or less)

Once monitoring is started, the application (call flow) will be notified of captured data through OnMonitoringDataReceived.

For more information on this API, please refer to the following article, which covers the monitoring APIs:
[[CAF:_Working_With_Cmc_Call_Legs|Working with CMC Call Legs]]

For more general information about using call legs in your application, please refer to this article:
[[CAF:_Working_With_Call_Legs|Working with Call Legs]]

=== Built-in monitoring analyzers ===
[[Image:Monitoring_analyzer_overview.png|thumb|300px]]
The Toolpack framework includes "analyzer" classes that use the monitoring API to capture signaling messages on TDM links.

The [[Toolpack_monitoring_isdn_analyzer|ISDN Analyzer]] will capture HDLC messages on the IDSN D-Channel, and analyze them to rebuild the call state of monitored ISDN calls.

The user application can then be notified of a detected ISDN calls, and of any state change of this call (accepted, alerting, answered, terminating, terminated...).

For more information about the analyzer API, refer to appropriate header files in Toolpack source code.

=== Integration of monitoring analyzers in Toolpack Gateway ===
The analyzers are integrated into Toolpack's own Gateway application.
The Gateway application can be configured to monitor ISDN calls on the specified Line Services.

Upon detection of ISDN calls, the Gateway application can generate CDR logs, and also forward the information to "generators" that will generate message toward an external application that needs to be notified of monitored ISDN calls.

For information about the configuration of ISDN analyzers in Toolpack, please refer to the following article:
[[Toolpack_monitoring_isdn_analyzer|Toolpack ISDN Analyzer]]

=== Toolpack monitoring generators ===
[[Image:Monitoring_generator_overview.png|thumb|300px]]
The Gateway application can attach "generators" to analyzers. A "generator" is receiving the analyzer's detected calls state changes, and generates corresponding events toward an external application.

==== Toolpack SIP simulator ====
One of the "generators" provided with Toolpack is the "SIP Simulator".

This monitoring generator is
* simulating SIP messages that correspond to the ISDN state changes
* Forwarding captured TDM audio through RTP streams

Using this SIP simulator with a monitoring analyzer allows any SIP monitoring software to be able to monitor a TDM link (ISDN for example).

For information about the configuration of "SIP Simulators" in Toolpack, please refer to the following article:
[[Toolpack_monitoring_sip_simulator|Toolpack SIP Simulator]]

Routing script tutorial:Mini Development Guide

2014-11-05T12:28:29Z

Jasmin Letendre: Fixed erroneous reason "circuit_not_available". The right value is "requested_circuit_not_available".

== Call object ==

=== Get ===

Those function are used to get the call parameters. The possible parameters are described in the section "Call parameters"

called_number = caf_call.get :called

=== List_params ===

This function is used to retrieve the list of supported call parameters. For example to extract all the possible call params from the the call object and put it in hash.

caf_call.list_params.each {|param| call[param] = caf_call.get param }

=== Accept ===

This function is used to accept a call. It actually creates one outgoing route that gateway application will use to bridge the incoming call leg. If more than one outgoing route is "accepted", gateway will try them one by one in the same order they were accepted. If an outgoing call leg fails (according to 'route retry' parameters), the next route in line will be used.

This method takes 2 arguments, the call parameters (hash) and the route parameters (hash). Note that calling this method does NOT stop the flow of the script.

Apply route remapping rules

caf_call.accept out_call, route

=== Refuse ===

This function is used to set the reason code for the incoming call leg refusal. However, this function does NOT stop the flow of the script.

caf_call.refuse :reason => :temporary_failure

To immediately refuse the incoming call leg and stop processing the script, the script must raise an exception. Exiting the script by raising the exception overwrites any reason cause previously stored using refuse().

raise RoutingException, :no_route

The supported refusal cause values for both refuse() and raise() are described in the section "[[Routing_script_tutorial:Mini_Development_Guide#Reason_values|Reason values]]".

=== Script parameters protocol mapping ===

The following call parameters are available in the call object:

{| cellspacing="1" cellpadding="1" border="1" style="width: 921px; height: 805px;"
|-
! scope="col" | '''Script parameter name'''
! scope="col" | '''ISDN '''
! scope="col" | '''R2 CAS''' 
! scope="col" | '''SS7 '''
! scope="col" | '''SIP '''
! scope="col" | '''Comment '''
! scope="col" | '''Toolpack version '''
|-
| leg_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Leg ID 
| 
|-
| session_id 
| N/A 
| N/A 
| N/A 
| N/A 
| Session ID 
| 
|-
| calling 
| Q931: 'Calling party number' IE - Number digits 
| ANI (Group B) 
| Q763: 'Calling party number' IE - address signals (*) 
| SIP:From - user-info 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead. 
| 
|-
| calling_noa 
| Q931: 'Calling party number' IE - Type of number 
| N/A 
| Q763: 'Calling party number' IE - nature of address indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_npi 
| Q931: 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Calling party number' IE - numbering plan indicator (*) 
| N/A 
| * In ANSI SS7 LNP networks, the IE 'generic address parameter' is used (when present) instead 
| 
|-
| calling_display 
| Q931: 'Display' IE - Display information 
Q931: 'Facility CNAM' IE when presentation is allowed for DMS/NI2 variants 
| N/A 
| Q763: 'Display information' IE - display information 
| SIP:From - display-name 
| 
| 
|-
| calling_display_type 
| Q931: 'Display' IE - Display information (present and/or first byte) 
| N/A 
| Q763: 'Display information' IE - present or not 
| N/A 
| 
| 
|-
| calling_presentation 
| Q931: 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: 'Calling party number' IE - address presentation restricted indicator 
|
SIP:From - display-name (displays 'anonymous' or not)

SIP:Remote-party-id - privacy 

| 
| 
|-
| calling_screening 
| Q931: 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: 'Calling party number' IE - screening 
| SIP:Remote-party-id - screen 
| 
| 
|-
| calling_category 
| N/A 
| Call party category (Group A) 
| Q763: 'Calling party's category' IE - calling party's category 
|
SIP:From - cpc

SIP:P-asserted-identity - cpc 

| 
| 
|-
| calling_subscriber
(Generic Number / NDS) 
| Q931: 2nd 'Calling party number' IE - Number digits 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - Number digits 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| Requires option 'support 2 calling number IE' in the profile. This variable has priority over 'private_address' in the outgoing direction. 
| 
|-
| calling_subscriber_noa 
| Q931: 2nd 'Calling party number' IE - Type of number 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - nature of address indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_npi 
| Q931: 2nd 'Calling party number' IE - Numbering plan identification 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - numbering plan indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
 
| 
|-
| calling_subscriber_presentation 
| Q931: 2nd 'Calling party number' IE - Presentation indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - presentation restricted indicator 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| calling_subscriber_screening 
| Q931: 2nd 'Calling party number' IE - Screening indicator 
| N/A 
| Q763: Generic number IE with type 'additional calling party number' - screening 
| SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 
| 
| 
|-
| private_display 
| Q931: 'Facility CNAM' IE when presentation is restricted for DMS/NI2 variants 
| N/A 
| N/A 
|
SIP:P-asserted-identity - display-name 

SIP:Remote-party-id - display-name 

| 
| 
|-
| private_display_type 
| N/A 
| N/A 
| N/A 
| N/A 
| Indicate presence or not of the private calling information 
| 
|-
| private_address 
| N/A 
| N/A 
| N/A 
|
SIP:P-asserted-identity - userinfo

SIP:Remote-party-id - user-info 

| 
| 
|-
| called 
| Q931: 'Called party number' IE - Number digits 
| DNIS (Group A) 
| Q763: 'Called party number' IE - address signals 
| SIP:To - user-info and host 
| 
| 
|-
| called_noa 
| Q931: 'Called party number' IE - Type of number 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| called_npi 
| Q931: 'Called party number' IE - Numbering plan identification 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| charge_number 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - address signals 
| N/A 
| 
| 
|-
| charge_number_noa 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| charge_number_npi 
| N/A 
| N/A 
| ANSI: 'Charge number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default redirecting number and original called number forwarding behavior from incoming to outgoing leg 
| 
|-
| redirecting_number 
| Q931: 'Redirecting number' 1st IE - Number digits 
| N/A 
| Q763: 'Redirecting number' IE - address signals 
| SIP:Diversion (2nd header) - display-name 
| 
| 
|-
| redirecting_number_noa 
| Q931: 'Redirecting number' 1st IE - Type of number 
| N/A 
| Q763: 'Redirecting number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| redirecting_number_npi 
| Q931: 'Redirecting number' 1st IE - Numbering plan identification 
| N/A 
| Q763: 'Redirecting number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| redirecting_number_presentation 
| Q931: 'Redirecting number' 1st IE - Presentation indicator 
| N/A 
| Q763: 'Redirecting number' IE - address presentation restricted indicator 
| SIP:Diversion (2nd header) - diversion-privacy 
| 
| 
|-
| redirecting_number_indicator 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirecting indicator 
| N/A 
| 
| 
|-
| redirecting_number_reason 
| Q931: 'Redirecting number' 1st IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - redirecting reason 
| SIP:Diversion (2nd header) - diversion-reason 
| 
| 
|-
| redirecting_number_counter 
| N/A 
| N/A 
| Q763: 'Redirection information' IE - redirection counter 
| SIP:Diversion (2nd header) - diversion-counter 
| 
| 
|-
| original_called_number
(OCN) 
| Q931: 'Redirecting number' 2nd IE - Number digits 
| N/A 
| Q763: 'Redirection number' IE - address signals 
| SIP:Diversion  (1st header) - display-name 
| 
| 
|-
| original_called_number_noa 
| Q931: 'Redirecting number' 2nd IE - Type of number 
| N/A 
| Q763: 'Redirection number' IE - nature of address indicator 
| N/A 
| 
| 
|-
| original_called_number_npi 
| Q931: 'Redirecting number' 2nd IE - Numbering plan identification 
| N/A 
| Q763: 'Redirection number' IE - numbering plan indicator 
| N/A 
| 
| 
|-
| original_called_number_presentation 
| Q931: 'Redirecting number' 2nd IE - Presentation indicator 
| N/A 
| Q763: 'Redirection number' IE - address presentation restricted indicator 
| SIP:Diversion (1st header) - diversion-privacy 
| 
| 
|-
| original_called_number_reason 
| Q931: 'Redirecting number' 2nd IE - Reason for redirection 
| N/A 
| Q763: 'Redirection information' IE - original redirection reason 
| SIP:Diversion (1st header) - diversion-reason 
| 
| 
|-
| original_called_number_counter 
| N/A 
| N/A 
| N/A 
| SIP:Diversion (1st header) - diversion-counter 
| 
| 
|-
| ported_number 
| N/A 
| N/A 
| Q763: 'Called party number' IE - address signals 
| SIP:RequestURI - rn 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_noa 
| N/A 
| N/A 
| Q763: 'Called party number' IE - nature of address indicator 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| ported_number_npi 
| N/A 
| N/A 
| Q763: 'Called party number' IE - numbering plan indicator 
| N/A 
| Only valid if SIP/SS7 supports LNP 
| 
|-
| oli
(Originating line information) 
| 5ESS Codeset 6 OLI - Value 
| N/A 
| ANSI: 'Originating line information' IE - OLI 
|
SIP:From - oli

SIP:P-asserted-identity - oli 

| 
| 
|-
| request_uri 
| N/A 
| N/A 
| N/A 
| Complete Request URI string 
| 
| 
|-
| request_uri_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default URI forwarding behavior from incoming to outgoing leg 
| 
|-
| sip_header 
| N/A 
| N/A 
| N/A 
| Any header 
| Requires option 'Forward custom headers' in Profiles->SIP 
| 2.7.63 
|-
| nap
(Network Access Point) 
| N/A 
| N/A 
| N/A 
| N/A 
| Incoming leg NAP name (read-only) 
| 
|-
| type_of_network_identification 
| Q931: 'Transit network selection' IE - Type of network identification 
| N/A 
| Q763: 'Transit network selection' IE - Type of network identification 
| N/A 
| 
| 2.7 
|-
| network_identification 
| Q931: 'Transit network selection' IE - Network identification 
| N/A 
| Q763: 'Transit network selection' IE - Network identification 
| SIP: Request-Line - cic 
| 
| 2.7 
|-
| network_identification_plan 
| Q931: 'Transit network selection' IE - Network identification plan 
| N/A 
| Q763: 'Transit network selection' IE - Network identification plan 
| N/A 
| 
| 2.7 
|-
| location_number_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| Overwrite default location number forwarding behavior from incoming to outgoing leg 
| 2.7 
|-
| location_number 
| N/A 
| N/A 
| Q763: 'Location number' IE - address signals 
| N/A 
| 
| 2.7 
|-
| location_number_noa 
| N/A 
| N/A 
| Q763: 'Location number' IE - nature of address indicator 
| N/A 
| 
| 2.7 
|-
| location_number_npi 
| N/A 
| N/A 
| Q763: 'Location number' IE - numbering plan indicator 
| N/A 
| 
| 2.7 
|-
| location_number_presentation 
| N/A 
| N/A 
| Q763: 'Location number' IE - presentation restricted indicator 
| N/A 
| 
| 2.7 
|-
| location_number_screening 
| N/A 
| N/A 
| Q763: 'Location number' IE - screening 
| N/A 
| 
| 2.7 
|-
| mlpp_forward_enabled 
| N/A 
| N/A 
| N/A 
| N/A 
| A script needs to set this to true if it wants to overwrite MLPP information in the outgoing leg. Otherwise, profile relay 'outgoing mode' applies automatically. 
| 2.7 
|-
| mlpp_look_for_busy 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - look ahead for busy 
| N/A 
| 
| 2.7 
|-
| mlpp_precedence_level 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - precedence level 
| SIP:Resource-Priority - q735 
| 
| 2.7 
|-
| mlpp_network_identity 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - network identity 
| N/A 
| 
| 2.7 
|-
| mlpp_service_domain 
| N/A 
| N/A 
| Q763: 'MLPP precedence' IE - MLPP service domain 
| N/A 
| 
| 2.7 
|-
| called_isub 
| Q931: 'Called party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE - Q931: 'Called party subaddress' IE - subaddress information 
| SIP:To - isub parameter 
| 
| 2.7 
|-
| called_isub_type 
| Q931: 'Called party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE - Q931: 'Called party subaddress' IE - type of subaddress 
| SIP:To - isub-encoding parameter 
| 
| 2.7 
|-
| calling_isub 
| Q931: 'Calling party subaddress' IE - subaddress information 
| N/A 
| Q763: 'Access transport' IE - Q931: 'Calling party subaddress' IE - subaddress information 
| SIP:From - isub 
| 
| 2.7 
|-
| calling_isub_type 
| Q931: 'Callinf party subaddress' IE - type of subaddress 
| N/A 
| Q763: 'Access transport' IE - Q931: 'Calling party subaddress' IE - type of subaddress 
| SIP:From - isub-encoding 
| 
| 2.7 
|-
| ss7_fci_default 
| N/A 
| N/A 
| Default forward call indicator (FCI) value. 
| N/A 
| Toolpack will overwrite FCI bits A, D, F, I and M with appropriate values according to call conditions 
| 2.7 
|-
| ss7_fci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_fci_default that must be forced. 
| N/A 
| Bits from ss7_fci_default which corresponding bit in ss7_fci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| ss7_bci_default 
| N/A 
| N/A 
| Default backward call indicator (BCI) value. 
| N/A 
| Toolpack will overwrite BCI bits AB, I, K, M and N with appropriate values according to call conditions 
| 2.7 
|-
| ss7_bci_force_mask 
| N/A 
| N/A 
| Mask to select bits from ss7_bci_default that must be forced. 
| N/A 
| Bits from ss7_bci_default which corresponding bit in ss7_bci_force_mask is set will be forced, and no more controlled by Toolpack 
| 2.7 
|-
| tdm_ls_name
(Line Service or T1/E1 trunk) 
| Incoming leg line service name 
| Incoming leg line service name 
| Incoming leg line service name 
| N/A 
| (read-only) 
| 2.7 
|-
| tdm_timeslot_nb 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| Incoming leg timeslot number 
| N/A 
| (read-only) 
| 2.7 
|-
| rtp_local_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_local_port 
| N/A 
| N/A 
| N/A 
| Incoming leg local SDP IP port 
| (read-only) 
| 2.7 
|-
| rtp_remote_addr 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP address 
| (read-only) 
| 2.7 
|-
| rtp_remote_port 
| N/A 
| N/A 
| N/A 
| Incoming leg remote SDP IP port 
| (read-only) 
| 2.7 
|-
| ss7_cot_enabled 
| N/A 
| N/A 
| Requests SS7 in-call continuity test for this outgoing SS7 call 
| N/A 
| Toolpack will request continuity test on the timeslot before making the outgoing call. If COT fails, the call will be dropped (then another route may be attempted) 
| 2.8 
|}

 

'''Notice:''' All values are documented in the '''noa_npi_remap.rb''' script and may change between major release.

=== Noa values ===

*<tt>unknown_number (0x2)</tt>
*<tt>international_number (0x4)</tt>
*<tt>national_number (0x3)</tt>
*<tt>subscriber_number (0x1)</tt>
*<tt>network_specific (0x5)</tt>
*<tt>network_routing_national_format (0x7)</tt>
*<tt>network_routing_international_format (0x8)</tt>
*<tt>abbreviated_number (0x6)</tt>
*<tt>subscriber_number_operator_requested (0x71)</tt>
*<tt>national_number_operator_requested (0x72)</tt>
*<tt>international_number_operator_requested (0x73)</tt>
*<tt>no_number_present_operator_requested (0x74)</tt>
*<tt>no_number_present_cut_through_call_to_carrier (0x75)</tt>
*<tt>test_line_test_code (0x77)</tt>
*<tt>non_unique_subscriber_number (0x71)</tt>
*<tt>non_unique_national_number (0x73)</tt>
*<tt>non_unique_international_number (0x74)</tt>
*<tt>call_950_numbe (0x76)</tt>
*<tt>special_number (0x73)</tt>
*<tt>national_number_with_transit_network_selection (0x74)</tt>
*<tt>international_number_with_transit_network_selection (0x75)</tt>

Those values will be remapped to the protocol specific NOA value. To provide protocol specific value:

*<tt>call_params[:called_noa] = 0x70</tt>

or

*<tt>call_params[:called_noa] = 112</tt>

=== Npi values ===

*<tt>unknown_number</tt>
*<tt>isdn</tt>
*<tt>telephony</tt>
*<tt>private</tt>
*<tt>data</tt>
*<tt>telex</tt>
*<tt>national</tt>

=== Calling Display Type values ===

*<tt>unspecified</tt> => Type is unspecified.
*<tt>calling_party_name</tt> => Type is 0xB1.

Those values will be remapped to the protocol specific Display Information Type value. To provide protocol specific value:

*<tt>call_params[:calling_display_type] = 0xB1</tt>

or

*<tt>call_params[:calling_display_type] = 177</tt>

=== Calling Display value ===

*<tt>call_params[:calling_display] = "Roger Fluffy"</tt>

=== Presentation values for Calling number, Calling Subscriber (Generic Number), Redirecting Number, Original Called Number (OCN) and Location Number ===

*<tt>unspecified</tt>
*<tt>not_available (0x2)</tt>
*<tt>allowed (0x0)</tt>
*<tt>restricted (0x1)</tt>
*<tt>addr_restricted</tt>
*<tt>name_restricted</tt>

=== Calling Party Category ===
values for calling_category
*<tt>unspecified</tt> <tt>(0xa)</tt>
*<tt>unknown</tt> <tt>(0x0)</tt>
*<tt>operator_french</tt> <tt>(0x1)</tt>
*<tt>operator_english</tt> <tt>(0x2)</tt>
*<tt>operator_german</tt> <tt>(0x3)</tt>
*<tt>operator_russian</tt> <tt>(0x4)</tt>
*<tt>operator_spanish</tt> <tt>(0x5)</tt>
*<tt>subscriber</tt> <tt>(0xa)</tt>
*<tt>subscriber_with_priority</tt> <tt>(0xb)</tt>
*<tt>data</tt> <tt>(0xc)</tt>
*<tt>test</tt> <tt>(0xd)</tt>
*<tt>payphone</tt> <tt>(0xf)</tt>

=== Screening values for Calling number, Calling Subscriber (Generic Number), and Location Number ===

*<tt>unspecified</tt>
*<tt>no (0x0)</tt>
*<tt>pass (0x1)</tt>
*<tt>fail (0x2)</tt>
*<tt>network_provided (0x3)</tt>

=== Redirecting indicator values ===

SS7:

*<tt>no_redirection</tt>
*<tt>call_rerouted</tt>
*<tt>call_rerouted_all_restricted</tt>
*<tt>call_diverted</tt>
*<tt>call_diverted_all_restricted</tt>
*<tt>call_rerouted_restricted</tt>
*<tt>call_diverted_restricted</tt>
*<tt>spare</tt>

=== Redirecting number, Original Called Number and Diversion Reason ===

ISDN:

*<tt>unknown</tt>
*<tt>busy</tt>
*<tt>no_reply</tt>
*<tt>deflection</tt>
*<tt>dte_out_of_order</tt>
*<tt>forwarding_by_called_dte</tt>
*<tt>unconditional</tt>

SS7:

*<tt>unknown</tt>
*<tt>busy (SIP: user-busy)</tt>
*<tt>no_reply (SIP: no-answer)</tt>
*<tt>unconditional</tt>
*<tt>deflection</tt>
*<tt>deflection_immediate</tt>
*<tt>mobile_not_reachable</tt>

=== OLI (originating line information) values ===

The OLI parameter is a string that represents an integer value from 0 to 255.

=== Information Transfer Capability values ===

information_transfer_capability:

*<tt>digital</tt>
*<tt>restricted_digital</tt>
*<tt>digital_with_tones</tt>
*<tt>speech</tt>
*<tt>3_1_khz_audio</tt>

=== redirecting_number_forward_enabled values ===

Controls forwarding or discarding of redirecting number (SIP: diversion header) to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true. 0/false: Redirecting number (and original called number) is not forwarded to outgoing call leg 1/true: Redirecting number (and original called number) is forwarded to outgoing call leg The value for this parameter at input of routing script depends on the "Forward redirecting number" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

=== request_uri ===

Enables access to the Request-Line URI. 

For example, if the Request-Line is:
<pre>Request-Line: INVITE sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0</pre>
Then the retrieved request_uri will be "sip:4175162082@172.22.45.13:5060;user=phone;transport=udp SIP/2.0". 

In the routing scripts, to retrieve only the called number, this script can be used: 
<pre> if call_params[:request_uri] && call_params[:request_uri] =~ /sip:(.*)@.*/
call_params[:called] = $1
end
</pre>
=== request_uri_forward_enabled values ===

Controls forwarding or discarding of request uri to outgoing call leg.The request uri is the information in the "Request-Line:" of the SIP INVITE message. 

Values for this parameter are "0", "1", "false" or "true. 

0/false: Request uri is not forwarded to outgoing call leg 

1/true: Request uri is forwarded to outgoing call leg 

The value for this parameter at input of routing script is always false. 

=== sip_header values ===
Contains a hash table of custom sip headers from the inbound call leg. Any custom sip header can be added to an outgoing call leg: 

<pre>call[ :sip_header ] = {"P-my-custom-header"=>"value1", "P-my-custom-header2"=>"value2", "P-my-custom-header3"=>"value3"}</pre>

* PCAP sample: [[File:TB_Custom_SIP_Headers.pcap]]

List of sip headers that will not appear in call[:sip_header] since they are already processed by the SIP stack:
<pre>
Accept Error-Info Remote-Party-ID
Accept-Contact Event Replaces
Accept-Encoding Expires Reply-To
Accept-Language From Request-Disposition
Alert-Info In-Reply-To Subject
Allow Max-Forwards Subscription-State
Allow-Events MIME-version Supported
Also Min-Expires Timestamp
Anonymity Min-SE To
Authorization Organization Unsupported
Authentication-Info Path User-Agent
Call-ID Priority Via
Call-Info Privacy Warning
Contact Proxy-Authenticate WWW-Authenticate
Content-Disposition Proxy-Authorization Require
Content-Encoding Proxy-Require Response-Key
Content-Language P-Media-Authorization Retry-After
Content-Length P-Preferred-Identity RPID-Privacy
Content-Type P-Asserted-Identity Route
CSeq RAck RSeq
RAck Reason Security-Client
Reason Record-Route Security-Server
Date Refer-To Security-Verify
Diversion Referred-By Server
Encryption Reject-Contact Service-Route
Session-Expires
</pre>

=== MLPP Precedence values ===

mlpp_look_for_busy:

*<tt>allowed</tt>
*<tt>path_reserved</tt>
*<tt>not_allowed</tt>

mlpp_precedence_level:

*<tt>flash_override</tt>
*<tt>flash</tt>
*<tt>immediate</tt>
*<tt>priority</tt>
*<tt>routine</tt>

mlpp_network_identity:

3 digits value from 0 to 999

mlpp_service_domain:

24 bits value from 0 to 16777215

=== ISUB subaddress information values ===

called_isub_type:
calling_isub_type:

*<tt>nsap</tt>
*<tt>nsap_ia5</tt>
*<tt>nsap_bcd</tt>
*<tt>user</tt>

called_isub:
calling_isub:

Digits for the subaddress information.

== Route parameters ==

All route may have these parameters:

*calling
*called
*nap
*remapped_calling
*remapped_called
*remapped_nap
*remapped_profile
*remapped_incoming_profile

Additionally it is possible to add dynamic route attributes in the web portal. These can be referenced by their name.

== Playing prompts announcements or tones ==

New feature in release 2.6, all bridges may have these parameters. These can be used to play IVR prompts or wav files in different states of the call flow, like playing an announcement when the caller dials in. You can also manage the User to User information element.

*announcement_tone
*call_progress_tone
*ring_tone
*max_call_duration
*call_duration_reason
*disconnect_tone
*uui
*uui_forward_enabled

The following sections show how to access those different parameters from '''inside''' a filter. The 'params' hash is the sole argument passed to a filter function and contains call, nap, route and bridge parameters. This hash is created by the base_routing.rb scripts to regroup all relevant information just before calling the filter functions.

=== Tone string format ===

All tone strings (:announcement_tone, :call_progress_tone, :ring_tone, :disconnect_tone) inside bridge parameters are using this format.
<pre>"file1.wav:repeat:start_off:end_off,file2.wav:repeat:start_off:end_off,file3.wav:repeat:start_off:end_off"
</pre>
optional repeat parameter: number of times to play the file (0 and 1 have the same result) optional start_off parameter : Start offset in milliseconds optional end_off parameter: End offset in milliseconds Example: "file1.wav,file2.wav:-1" will play file1.wav one time and then play file2.wav in loop. Example: "file1.wav:0:1000:3000,file2.wav:2:5000:10000" will play file1.wav from second 1 to second 3 then file2.wav from second 5 to second 10 two times. Example: "file1.wav:0:0:30000" will play file1.wav one time for a max duration of 30 seconds.

=== announcement_tone ===

params[:bridge][:announcement_tone] = "announcement.wav"

Prompt played on the incoming leg with the stream_server before any outgoing call is placed. The outgoing call occurs when the wav file is completed or when the "profile:Busy Tone max duration" is reached.

Options:
==== announcement_tone_answer ====
params[:bridge][:announcement_tone_answer] = "yes"

Answer the call before playing the announcement. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== call_progress_tone ===

params[:bridge][:call_progress_tone] = "no_route.wav"

Prompt played after "announcement_tone" when reason is not "ok" or when outgoing call disconnect before answer state. "none" value is used to bypass "profile:Generate Busy (Congestion) Tone" and to play no audio prompt.

==== call_progress_tone_answer ====
params[:bridge][:call_progress_tone_answer] = "yes"

Answer the call before playing the call progress tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== ring_tone ===

params[:bridge][:ring_tone] = "ringing.wav"

Prompt played between alerting state and answer state. Bypass any other ring back tone (RBT) configured in profile.

=== max_call_duration ===

params[:bridge][:max_call_duration] = "60000"

Maximum call duration in millisecond for the current bridge. This timer is started when entering answer state.

=== call_duration_reason ===

params[:bridge][:call_duration_reason] = :resource_unavailable

Drop both legs with this reason when call duration (:max_call_duration) is reached.

=== disconnect_tone ===

params[:bridge][:disconnect_tone] = "max_duration.wav"

Prompt played (on the incoming leg only) when call duration (:max_call_duration) is reached. Then the leg will be terminated with specified reason (:call_duration_reason).

==== disconnect_tone_answer ====
params[:bridge][:disconnect_tone_answer] = "yes"

Answer the call before playing the disconnect tone. Default if argument not provided is "no", in which case call is only alerted with in-band media.

=== UUI (user-to-user indication) values ===

Byte array represented as ruby String. Use ''bridge=params[:bridge]'', then ''bridge[:uui]'' to access the data.

To access the bytes in Ruby, use ruby String operator []. For example: bridge[:uui][0] will return the binary value of the first UUI byte.

Function each_byte can also be useful to iterate through all bytes of the UUI.

=== uui_forward_enabled values ===

Controls forwarding or discarding of UUI to outgoing call leg.

Values for this parameter are "0", "1", "false" or "true. 0/false: UUI is not forwarded to outgoing call leg 1/true: UUI is forwarded to outgoing call leg The value for this parameter at input of routing script depends on the "Forward UUI" parameter in the "Advanced" section of the Gateway configuration page of the Web Portal. The script may change this value to override the Gateway configuration.

=== Managing audio prompts through Web Portal ===
Audio prompts can be uploaded or deleted from the TMedia unit through the Web Portal:
[[Toolpack:Configuring_Audio_Prompts_A|Managing audio prompts]]

Prompts management must be done using the Web Portal of the primary server (in systems with redundant TMedia units or redundant host servers).
The file will automatically get replicated to the secondary server.

=== Managing audio prompts manually ===
Any file on the TMedia host file system can be played. This means it's possible to manage prompts through ssh/scp.

Provided paths are always relative to the "current working directory" of the tbstreamserver application:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/
(Where "2.7" may be replaced by the current major version of your system)

Absolute paths can also be provided.

== Recording call legs ==
Introduced in release 2.6.44, it's now possible to use routing scripts to ask for recording incoming and/or outgoing call legs.

See example filter script "call_recording" (created by default in Web Portal routing scripts starting with 2.6.44) for an example.

=== Recording the incoming call leg ===
To record the incoming call leg, the routing script (in a "after filter" for example) has to set the following parameter:

bridge[ :record_incoming ] = ""

=== Recording the outgoing call leg ===
To record the outgoing call leg, the routing script (in a "after filter" for example) has to set the following parameter, per route (the decision to record or not, or the file name to record to, can be set per matching route):

# Need to clone the routes in order to have the right to modify them
routes = clone_routes params[:routes]
routes.each do |route|
route[ :record_outgoing ] = ""
end
# Store modified routes back to the parameters for this outgoing call
params[:routes] = routes

=== Record the outgoing call leg within incoming leg's recorded file (mixing) ===
[...]
route[ :record_outgoing ] = "@{MixWithIncoming}"
[...]

=== Choosing file path to record to ===
The value assigned to ":record_incoming" or ":record_outgoing" is the path to record the file to.

The paths can be absolute, or relative. When relative, they are relative to the "tbstreamserver" application working directory, for example:
/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

* Empty file name will default to a name that contains various information about the call:
** ''LinkId'': Id common between all legs of this call bridge
** ''LegId'': Unique Id for this leg
** ''Nap'': Current NAP name this call leg is from
** ''Direction'': "IN" or "OUT" (depends if call leg is incoming or outgoing leg)
** ''Calling'': The calling number of this call leg
** ''Called'': The called number of this call leg
** ''Protocol'': The signaling protocol of this call leg (SS7, ISDN, CAS, SIP)
** ''Media info'': Codec + IP/Port for SIP calls, Trunk/Timeslot for TDM calls
* To record outgoing call leg in the same audio file as incoming call leg (mixing), use the following:
** @{MixWithIncoming}: Record outgoing legs in same file as incoming legs
* Variables can be used to insert in the recording path information that's not already available from routing scripts:
** @{DefaultName}: Same file name (without parent folder path) as the one used when empty string is provided
*** Example: "73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{DefaultPath}: Same path as the one used when empty string is provided
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-F3D67B4B-NAP_SS7-IN-5550000-5550001-SS7-TRUNK_BELL_11-24.wav"
*** Example: "/lib/tb/toolpack/setup/12358/recorded_calls/73EBA698-73EBA698-NAP_SIP-OUT-5550000-5550001-SIP-G723-10.3.10.101-1050.wav"
** @{LinkId}: Current LinkId (Id common between all legs of this call bridge)
*** Example: "73EBA698"
** And all variables listed here: [[Customer_application_framework:play_audio_files#Helpful_variables_to_build_play_or_record_file_paths|Building play or record file path]]

== Authorization ==
Starting with release 2.7, it is possible to issue RADIUS authorization requests from routing scripts. To do so, the params[:authorization] object must be filled with the required RADIUS attributes and [[#Refuse|an exception must be raised]] with reason :authorization_required.

When the authorization is completed, the routing script is called again with the result. The params[:authorization] object will be filled with the RADIUS attributes from the response. The params[:authorization][:result] field will also contain a string indicating the result of the authorization:

* ''accept'': The authorization was successful.
* ''reject'': The authorization was refused.
* ''challenge'': The authorization was challenged.
* ''timeout'': The authorization was not answered.

== Call diversion options ==
It's possible to control the call flow when a call diversion information is received in the alerting state.

Two fields are available: bridge[ :diversion ] and bridge[ :diversion_reason ]

The internal release cause TOOLPACK_DIVERT_NOT_ALLOWED is used by gateway application to terminate both legs.

bridge[ :diversion ] = :allowed
The alert message will not be analyzed and the call will be progressed. Default behavior.
bridge[ :diversion ] = :not_allowed
If the alert message indicates that the call is diverted, the call will be released no matter the In-band information to allow
early media.
bridge[ :diversion ] = :not_allowed_w_early_media
The call will be released If the alert message indicates that the call is diverted with in-band information to allow early media.
bridge[ :diversion_reason ] = "*"
If the diversion is not allowed, the gateway will drop the call for any redirecting reason.
bridge[ :diversion_reason ] = []
bridge[ :diversion_reason ] << :busy
bridge[ :diversion_reason ] << :unconditional
If the diversion is not allowed, the redirecting reason will be analyzed and the call will only be dropped for the configured cases.

See section [[Routing_script_tutorial:Mini_Development_Guide#Redirecting_number_reason_values|Redirecting number reason values]].

== Call transfer requests ==
Toolpack allows to relay [[Call transfer]] requests from one leg to the other, or to process them locally (making another outgoing call to replace the call that requested the call transfer).

If the chosen [[Call transfer]] mode is to process requests locally, upon reception of a call transfer request (SIP REFER or ISDN Facility), routing script will be called once again, to select the routes for the new outgoing call (call transfer target).

=== How to route call transfer request ===
Routing of a call transfer request is done exactly like routing of a normal incoming call.
The routing script generally does not need any modification to support that.

In some cases, the routing script may want to use information related to the transfer request to perform routing, or to insert information in the outgoing call leg.
Additional information is provided to the routing script, allowing routing decisions using information from the call transfer request (SIP REFER or ISDN Facility).
See below...

=== params[ :call ] content during transfer request ===
When processing a call transfer request, the params[ :call ] hash contains the information from the inbound call (same as was passed to the routing script upon arrival of the inbound call)
call = params[ :call ] -> Information from original inbound call, with exception of call[ :called ]

One exception (convenient because it allows a unmodified routing script to process call transfer request the same way as any other routing request):
call[ :called ] -> Replaced by the called number from the call transfer request (also called "redirection number")
Complementary information:
call[ :original_called_number ] -> Contains the called number that was initially received from the incoming call, prior to call transfer request
call[ :redirecting_number ] -> Number of the call from which the call transfer request was received (generally equals to original_called_number)

These fields will also be included in the outgoing call made after routing:
* original called number and redirecting number are existing fields on SS7 and ISDN calls
* SIP "diversion" header is used for SIP calls

=== params[ :transfer ] content ===
(this if valid only for release 2.7.102 and above) 
When processing a call transfer request, information from the call transfer request message (SIP REFER, ISDN Facility) is provided in params[ :transfer ]:
transfer = params[ :transfer ]
The following field is always present:
transfer[ :original_nap ] -> Contains the NAP of the first call from which a call transfer request was received
transfer[ :redirecting_nap ] -> Contains the NAP of the call from which the current call transfer request was received
(same as :original_nap for the first call transfer, different for subsequent transfers)
Examples of other fields that may be present, when appropriate:
transfer[ :uui ] -> The UUI (user-to-user information) found in the call transfer request
transfer[ :sip_header ] -> Contains custom SIP headers from the call transfer request
transfer[ :request_uri ] -> Contains the SIP Request URI

These field are 'read-only'. They won't be included in the outgoing call, as they represent the content of the call transfer request, not the outgoing call to make.

To insert/modify attributes of the outgoing call, the parameters from params[ :call ] must be edited instead.

== Reason values ==

Check here for Termination Reason Cause codes: 

[[Termination_cause_codes|Termination Reason Cause codes]]
 

Example to refuse an incoming call leg.
raise RoutingException, :no_route

Reason cause strings available inside routing scripts:

List of Q.850 reason causes:
:unallocated_number
:no_route_to_network
:no_route_to_destination
:send_special_tone
:misdialled_trunk_prefix
:channel_unacceptable
:call_awarded_in_established_channel
:preemption
:reattempt
:ported_number
:normal_call_clearing
:user_busy
:no_user_responding
:no_answer_from_user
:subscriber_absent
:call_rejected
:number_changed
:redirection
:exchange_routing_error
:non_selected_user_clearing
:destination_out_of_order
:address_incomplete
:facility_rejected
:response_to_status_enquiry
:normal_unspecified
:no_circuit_available
:network_out_of_order
:frame_mode_out_of_service
:frame_mode_connection_operational
:temporary_failure
:switching_equipment_congestion
:access_information_discarded
:requested_circuit_not_available
:precedence_call_blocked
:resource_unavailable
:quality_of_service_not_available
:requested_facility_not_subscribed
:outgoing_calls_barred
:outgoing_calls_barred_within_CUG
:incoming_calls_barred
:incoming_calls_barred_within_CUG
:bearer_cap_not_authorized
:bearer_cap_not_available
:inconsistency_access_info
:service_not_available
:bearer_cap_not_implemented
:channel_type_not_implemented
:requested_facility_not_implemented
:only_restricted_digital_info
:service_not_implemented
:invalid_call_reference
:channel_does_not_exist
:call_identity_does_not_exist
:call_identity_in_use
:no_call_suspended
:call_has_been_cleared
:user_not_member_of_CUG
:incompatible_destination
:non_existant_CUG
:invalid_transit_network
:invalid_message_unspecified
:mandatory_IE_missing
:message_type_non_existent
:not_compatible_with_call_state
:IE_non_existent
:invalid_IE_content
:message_not_compatible
:recovery_on_timer_expiry
:parameter_non_existent_passed_on
:msg_with_non_recognized_param_discarded
:protocol_error
:interworking_unspecified

List of toolpack reason causes:

:toolpack_normal or :normal
:toolpack_resource_error or :resource_error
:toolpack_timeout or :timeout
:toolpack_no_route or :no_route
:toolpack_call_collision or :call_collision
:toolpack_sync_drop or :sync_drop
:toolpack_signaling_error or :signaling_error
:toolpack_locally_rejected or :locally_rejected
:toolpack_interface_not_available or :interface_not_available
:toolpack_reset_in_progress or :reset_in_progress
:toolpack_adapter_reject or :adapter_reject
:toolpack_missing_or_invalid_IE or :missing_or_invalid_IE
:toolpack_incoming_only or :incoming_only
:toolpack_system_configuration_changed or :system_configuration_changed
:toolpack_resource_no_more_available or :resource_no_more_available
:toolpack_incompatible_media or :incompatible_media
:toolpack_resource_allocation_failed or :resource_allocation_failed
:toolpack_data_path_not_available or :data_path_not_available
:toolpack_local_congestion or :local_congestion
:toolpack_authorization_required or :authorization_required
:toolpack_call_divert_is_not_allowed or :call_divert_is_not_allowed

List of SIP reason causes:

:400_bad_request
:401_unauthorized
:402_payment_required
:403_forbidden
:404_not_found
:405_method_not_allowed
:406_not_acceptable
:407_proxy_authentication_required
:408_request_timeout
:409_conflict
:410_gone
:413_request_entity_too_large
:414_request_URI_too_long
:415_unsupported_media
:416_unsupported_URI_scheme
:420_bad_extension
:421_extension_required
:422_session_timer_too_small
:423_interval_too_brief
:429_referrer_identity_error
:480_temporary_unavailable
:481_call_or_transaction_does_not_exist
:482_loop_detected
:483_too_many_hops
:484_address_incomplete
:485_ambiguous
:486_busy_here
:487_request_terminated
:488_not_acceptable_here
:489_bad_event
:491_retry_after
:500_server_internal_error
:501_not_implemented
:502_bad_gateway
:503_service_unavailable
:504_server_timeout
:505_version_unsupported
:513_message_too_large
:600_busy_everywhere
:603_decline
:604_not_exist_anywhere
:606_not_acceptable

== Nap status ==

All the status fields of the NAPs are provided for use by the routing scripts. See the nap status provider for more details on which fields are available in the CEngineStatTransNap.hpp file.

'''Notice:''' These values may change between major release.

Routing script call attribute name Description
--------------------------------------------------------------------------------------------
"signaling_type" Signaling type.
"inst_incoming_call_cnt" Instantaneous Count of incoming calls.
"inst_outgoing_call_cnt" Instantaneous Count of outgoing calls.
"available_cnt" Number of available circuits or channels.
"unavailable_cnt" Number of unavailable circuits or channels.
"availability_percent" Percentage of available circuits or channels.
"usage_percent" Percentage of used circuits or channels.
"unused_shared_percent" Percentage of used circuits or channels of this NAP available to make new calls with (taking into account shared with other NAPs)
"total_incoming_call_cnt" Total Count of incoming calls.
"asr_statistics_struct" Detailed Answer-Seizure Rate Statistics.
"global_asr_percent" Global calculated ASR percentage.
"total_outgoing_call_cnt" Total Count of outgoing calls.
"last_24h_asr_percent" Last 24 hours calculated ASR percentage.
"last_24h_outgoing_call_cnt" Last 24 hours outgoing calls.
"current_hour_asr_percent" Current hour calculated ASR percentage.
"current_hour_outgoing_call_cnt" Current hour outgoing calls.
"last_hour_asr_percent" Last hour calculated ASR percentage.
"last_hour_outgoing_call_cnt" Last hour outgoing calls.
"availability_detection_struct" Detailed availibility detection Statistics
"poll_remote_proxy" Remote proxy polling enabled
"is_available" Remote proxy actually available or not
"time_since_polling" Time since the last availibility polling
"time_available_seconds" Number of seconds since the NAP is available
"time_unavailable_seconds" Number of seconds since the NAP is unavailable
"registration_struct" Detailed registration Statistics
"register_to_proxy" Register to proxy enabled
"registered" Actually registered or not
"time_since_refresh" Time since the last refresh
"time_registered_seconds" Number of seconds since the NAP is registered
"time_not_registered_seconds" Number of seconds since the NAP is not registered

 If the nap status is part of a substructure, it's name in the routing scripts must be composed of the structure name appended by an underscore and the field name.

For example the name to use for the global [[ASR]] percentage is:

asr_statistics_struct_global_asr_percent

 It is also possible to add dynamic nap attributes in the web portal. These can be referenced by their name.

== Routing Script Tests ==
The Web portal features a tool for Testing Scripts. The user must enter parameters to simulate the incoming call and after pressing the Test button, will output selected routes and numbers. You do not need to activate the new routes, or the new scripts to use this test tool: It can be used to test the routing scripts and routing table before activating it.
This is available in the Routing Scripts section of the Web portal.

=== Test parameters ===
==== @call_params ====

That variable should contain a hash of call parameters that will passed to the routing script. This is equivalent to the incoming call parameters.

 

==== @nap_list ====

A list of hash containing the nap statuses. This is equivalent to the nap statuses at the time the call is to be routed.

'''The nap list is hashed by the nap names in UPPERCASE.''' It is important to consider this when creating new dynamic route or nap attributes that may nap names that will be used to fetch a status.

 

==== @params ====

A hash of hashes containing parameters. This hash contains bridge parameters and other kind of parameter groups may be added in the future.

Example: @params = {:bridge => {:announcement_tone, "announcement.wav"}}

 

----

 Back to [[Routing script tutorial|Routing Script Tutorial]].

[[category:Needs revising]]

H.248

2014-06-09T14:47:51Z

Jasmin Letendre: Added H.248.16 packages support

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

 

== TelcoBridges and H.248 ==

[[Toolpack]] now supports the H.248 protocol.

As indicated in the diagram below, the H.248 stack is a module in the media gateway application residing on the application server. It communicates with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF: Working With Call Legs|Media Leg API]]. In turn, the media gateway application communicates with the softswitch / media gateway controller via the H.248 protocol.

 [[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

 

=== H.248 package support ===

[[Toolpack]] supports the following packages.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

 

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Call Progress Tones Generator (Ringing, Busy, Congestion and Warning tones supported)
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package (only echo-cancellation)

 

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)
**IP Fax (Event: Fax Connection Change - end of fax session, call terminating)

 

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''
** Partial support
 

*'''H.248.7 Generic announcement package'''
**Generic announcement package (Fix Announcement play only)

 

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

 

*'''H.248.11 Media gateway overload control package'''
**Overload control package

 

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

 

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

 

*'''H.248.16 Enhanced digit collection packages and procedures'''
**Extended DTMF detection package
**Enhanced DTMF detection package

 

*'''H.248.25 Basic CAS packages'''
**Basic CAS package
**Basic CAS addressing
 

*'''H.248.27 Supplemental tones packages'''
**Carrier tones generation package
 

*'''H.248.28 International CAS packages'''
**International CAS
**CAS blocking

 

*'''H.248.29 International CAS compelled register signalling packages'''
** Annex A.1 only in 'enbloc' compelled mode (International CAS Compelled package - No digitmap control: Digitmaps are preconfigured on MG)

== Additional details ==

*Support for text mode only
*Not supported on Solaris builds

== References ==
*[[Web_Portal_Tutorial_Guide_v2.7#H.248|Web Portal v2.7: H.248 Configuration]]
*[[Toolpack_v2.5:Creating_an_H.248_Configuration|Configuring H.248 on TMG devices (v2.6 and before)]]
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[Category:Glossary]]
[[Category:Tmedia_Features|H.248/Megaco]]
[[Category:Revise on Major]]

User talk:Albert Huynh

2014-04-28T14:14:14Z

Jasmin Letendre: Welcome!

'''Welcome to ''TBwiki''!'''
We hope you will contribute much and well.
You will probably want to read the [[Help:Contents|help pages]].
Again, welcome and have fun! [[User:Jasmin Letendre|Jasmin Letendre]] 10:14, 28 April 2014 (EDT)

User:Albert Huynh

2014-04-28T14:14:14Z

Jasmin Letendre: Creating user page with biography of new user.

Ce fut un grand Vaisseau taillé dans l'or massif:
Ses mâts touchaient l'azur, sur des mers inconnues;
La Cyprine d'amour, cheveux épars, chairs nues,
S'étalait à sa proue, au soleil excessif.

Mais il vint une nuit frapper le grand écueil
Dans l'Océan trompeur où chantait la Sirène,
Et le naufrage horrible inclina sa carène
Aux profondeurs du Gouffre, immuable cercueil.

Ce fut un Vaisseau d'Or, dont les flancs diaphanes
Révélaient des trésors que les marins profanes,
Dégoût, Haine et Névrose, entre eux ont disputés.

Que reste-t-il de lui dans la tempête brève ?
Qu'est devenu mon coeur, navire déserté?
Hélas! Il a sombré dans l'abîme du Rêve!

User talk:Benjamin Lavigne

2014-04-16T18:58:57Z

Jasmin Letendre: Welcome!

User:Benjamin Lavigne

2014-04-16T18:58:57Z

Jasmin Letendre: Creating user page with biography of new user.

Eugenie
juin 2013 à Aujourd'hui
Membres de l'équipe : Benjamin Lavigne, Li Alin
Lʼeugénisme peut être défini comme lʼensemble des méthodes et pratiques visant à transformer le patrimoine génétique de lʼespèce humaine, dans le but de le faire tendre vers un idéal déterminé. Il peut être le fruit dʼune politique délibérément menée par un État. Il peut aussi être le résultat collectif dʼune somme de décisions individuelles convergentes prises par les futurs parents, dans une société où primerait la recherche de lʼ« enfant parfait », ou du moins indemne de nombreuses affections graves.

Parameter: Filter by Local Port

2014-01-31T18:48:33Z

Jasmin Letendre: /* When this parameter is disabled */

The '''Filter by local port''' parameter is used to determine if the [[NAP]] will accept only incoming calls arriving on one of it's assigned [[SIP Transport Server]].
(This option has no effect on outgoing calls on this [[NAP]])

=== When this parameter is enabled ===
When this parameter is enabled (which we highly recommend), only incoming calls received on a [[SIP Transport Server]] assigned to a [[NAP]] will be considered as coming from that [[NAP]].

=== When this parameter is disabled ===
When this parameter is disabled (not recommended), an incoming call received from this [[NAP]]'s proxy will be considered as coming from this [[NAP]] no matter which local [[SIP Transport Server]] the call was received on (including from a [[SIP Transport Server]] that is not assigned to the [[NAP]]).

[[Category:Parameters]]

Parameter: Filter by Local Port

2014-01-31T18:47:53Z

Jasmin Letendre: /* When this parameter is enabled */

The '''Filter by local port''' parameter is used to determine if the [[NAP]] will accept only incoming calls arriving on one of it's assigned [[SIP Transport Server]].
(This option has no effect on outgoing calls on this [[NAP]])

=== When this parameter is enabled ===
When this parameter is enabled (which we highly recommend), only incoming calls received on a [[SIP Transport Server]] assigned to a [[NAP]] will be considered as coming from that [[NAP]].

=== When this parameter is disabled ===
When this parameter is disabled (not recommended), a incoming call received from this [[NAP]]'s proxy will be considered as coming from this [[NAP]] no matter which local [[SIP Transport Server]] the call was received on (including from a [[SIP Transport Server]] that is not assigned to the [[NAP]]).

[[Category:Parameters]]

Parameter: Filter by proxy address

2014-01-31T18:46:51Z

Jasmin Letendre: /* When this parameter is enabled */

The '''Filter by proxy address''' parameter is used to control if the source IP of incoming SIP invites are compared with the '''Proxy address''' field of the [[NAP]] in order to determine if the call is coming from this [[NAP]].

(This function has no effect on outgoing SIP calls on this [[NAP]])

=== When this parameter is enabled ===
When this parameter is enabled (which we highly recommend), only incoming calls from a source IP address that matches the '''Proxy address''' of this [[NAP]] will be considered as coming from this [[NAP]].

=== When this parameter is disabled ===
When this parameter is disabled (not recommended), any incoming call received on the local [[SIP Transport Server]] of this [[NAP]] will be considered as coming from this [[NAP]].

This may cause multiple [[NAP]] to "match" the incoming call, in which case one of the matching [[NAP]] will be associated with the call (it's undefined which will be chosen).

Note that this can be used to create a "default" [[NAP]] that accepts any incoming call.

[[Category:Parameters]]

H.248

2013-11-26T17:29:51Z

Jasmin Letendre: /* H.248 package support */

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

 

== TelcoBridges and H.248 ==

[[Toolpack]] now supports the H.248 protocol.

As indicated in the diagram below, the H.248 stack is a module in the media gateway application residing on the application server. It communicates with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF: Working With Call Legs|Media Leg API]]. In turn, the media gateway application communicates with the softswitch / media gateway controller via the H.248 protocol.

 [[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

 

=== H.248 package support ===

[[Toolpack]] supports the following packages.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

 

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Call Progress Tones Generator (Ringing, Busy, Congestion and Warning tones supported)
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package (only echo-cancellation)

 

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)
**IP Fax (Event: Fax Connection Change - end of fax session, call terminating)

 

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''
** Partial support
 

*'''H.248.7 Generic announcement package'''
**Generic announcement package (Fix Announcement play only)

 

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

 

*'''H.248.11 Media gateway overload control package'''
**Overload control package

 

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

 

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

 

*'''H.248.25 Basic CAS packages'''
**Basic CAS package
**Basic CAS addressing
 

*'''H.248.28 International CAS packages'''
**International CAS
**CAS blocking

 

*'''H.248.29 International CAS compelled register signalling packages'''
** Annex A.1 only in 'enbloc' compelled mode (International CAS Compelled package - No digitmap control: Digitmaps are preconfigured on MG)

== Additional details ==

*Support for text mode only
*Not supported on Solaris builds

== References ==

*[[Toolpack_v2.5:Creating_an_H.248_Configuration|Configuring H.248 on TMG devices]] 
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[Category:Glossary]]
[[Category:Tmedia_Features|H.248/Megaco]]
[[Category:Revise on Major]]

H.248

2013-11-26T17:29:15Z

Jasmin Letendre: Updated H.248 package support

Also known as Megaco, H.248 is a protocol for controlling media gateways via a [[Softswitch|softswitch]] or a [[Media gateway controller|media gateway controller]].

 

== TelcoBridges and H.248 ==

[[Toolpack]] now supports the H.248 protocol.

As indicated in the diagram below, the H.248 stack is a module in the media gateway application residing on the application server. It communicates with the various Toolpack classes (CAFClass, [[CMC library|CMC Library]], CMC Class) as required via a new [[CAF: Working With Call Legs|Media Leg API]]. In turn, the media gateway application communicates with the softswitch / media gateway controller via the H.248 protocol.

 [[Image:H.248 schematic.jpg|H.248 schematic.jpg]]

 

=== H.248 package support ===

[[Toolpack]] supports the following packages.

*'''H.248.1'''
**Protocol v2
**IPSec connection support
**Support UDP (2944 or user-defined)

 

*'''H.248.1 - Basic packages'''
**Generic
**Base Root
**Tone generator (for extension purposes only)
**Tone detection (for extension purposes only)
**Basic DTMF generation
**DTMF detection
**Call Progress Tones Generator (Ringing, Busy, Congestion and Warning tones supported)
**Basic continuity package
**Network package
**RTP package
**TDM Circuit package (only echo-cancellation)

 

*'''H.248.2 Facsimile, text conversation and call discrimination packages'''
**Fax/TextPhone/Modem tones detection (fax and data only)
**Call type discrimination package (fax and data only)
**IP Fax (Event: Fax Connection Change - end of fax session, call terminating)

 

*'''H.248.4 Transport over Stream Control Transmission Protocol (SCTP)'''
** Partial support
 

*'''H.248.7 Generic announcement package'''
**Generic announcement package (Fix Announcement play only)

 

*'''H.248.10 Media gateway resource congestion handling package'''
**Congestion handling package

 

*'''H.248.11 Media gateway overload control package'''
**Overload control package

 

*'''H.248.13 Quality alert ceasing package'''
**Quality alert ceasing package

 

*'''H.248.14 Inactivity timer package'''
**Inactivity timer package

 

*'''H.248.25 Basic CAS packages'''
**Basic CAS package
**Basic CAS addressing
 

*'''H.248.28 International CAS packages'''
**International CAS
**CAS blocking

 

*'''H.248.29 International CAS compelled register signalling packages'''
** Annex A.1 only in 'enbloc' compelled mode (International CAS Compelled package - No digitmap control: Digitmaps are preconfigured on MG)
**

== Additional details ==

*Support for text mode only
*Not supported on Solaris builds

== References ==

*[[Toolpack_v2.5:Creating_an_H.248_Configuration|Configuring H.248 on TMG devices]] 
*[http://en.wikipedia.org/wiki/Megaco Wikipedia article]

[[Category:Glossary]]
[[Category:Tmedia_Features|H.248/Megaco]]
[[Category:Revise on Major]]

System Statistics

2013-05-27T15:38:29Z

Jasmin Letendre: /* Statistics Collection */

System Statistics is a tool that allows the monitoring of the evolution of the system status.
It gathers statistics at a fixed interval and stores them.
Those statistics can then be used to generate graphs.

== Statistics Collection ==
The gathered statistics are determined by the Global Polling Level.
By default, this value is set to Level 3.
This means that only statistics level 3 or higher are queried.
A list of all the available statistics for your system can be found
on the [[Statistics Dictionary|statistics dictionary]] page.

Statistics are queried at a fixed interval.
By default, this is set so statistics are queried once every 10 minutes.
Once queried, the statistics are saved on disk for future use.
If the statistics grow over a configurable size,
statistics will be deleted starting by the oldest ones.
This will, at most, delete a single day's statistics at a time.

== Loggable Statistics ==

*[[Toolpack:Loggable_Statistics_A|ToolpackToolpack v2.7:Loggable Statistics]]

== Configuration ==
*[[Web_Portal_Tutorial_Guide_v2.7#Statistics|Toolpack v2.7: System Statistics]]

User talk:Yves St-Arnaud

2012-10-22T13:25:55Z

Jasmin Letendre: Welcome!

User:Yves St-Arnaud

2012-10-22T13:25:55Z

Jasmin Letendre: Creating user page with biography of new user.

I used to think that I could not go on
and life was nothing but an awful song
But now I know the meaning of true Love
I'm leaning on the Everlasting Arms.

If I can see it
then I can do it
If I just believe it
there's nothing to it

I believe I can fly
I believe I can touch the sky
I think about it every night and day
Spread my wings and fly away
I believe I can soar
I see me runnin' through that open door
I believe I can fly
I believe I can fly
I believe I can fly

See, I was on the verge of breaking down
Sometimes silence can seem so loud
There are miracles in life I must achieve
But first I know it starts inside of me
Oh, if I can see it (whoo!)
then I can be it
If I just believe it
there's nothin' to it

I believe I can fly
I believe I can touch the sky
I think about it every night and day
Spread my wings and fly away
I believe I can soar
I see me runnin' through that open door
I believe I can fly
I believe I can fly....whoo!
Oh, I believe I can fly

Hey, 'cuz I believe in You
Ohhhhhh
If I can see it
then I can do it
If I just believe it
there's nothin' to it.

I believe I can fly....whoo!
I believe I can touch the sky
I think about it every night and day
Spread my wings and fly away
I believe I can soar
See me runnin' through that open door
I believe I can fly (I can fly!)
I believe I can fly (I can fly!)
I believe I can fly
If I just spread my wings (I can fly!)
I can fly (I can fly!)
I can fly (I can fly!)
I can fly (I can fly!)
Hey, if I just spread my wings
I can fly .....(I can fly!) whoo!!
(I can fly!)
fly............

Toolpack prerequisite Windows XP 2-5

2012-10-03T15:22:51Z

Jasmin Letendre: Fixed typo.

This page shows the Toolpack 2-5 prerequisites for Windows XP.

== Toolpack Prerequisite ==

=== Toolpack Basic packages ===

The software listed below is required by the host machines.

1) Go to TelcoBridges download site and get:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/iconv-1.9.2.win32.zip
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/libxml2-2.7.3.win32.zip
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/zlib-1.2.3.win32.zip
2) Decompress and copy the DLL files to C:\Windows\System32
iconv.dll
libxml2.dll
zlib1.dll

==== MSVC8 Redistributable ====
If you plan on using TBToolPack-x.y.zz-msvc8-Setup.exe, then you need to apply all windows updates from MicroSoft AND install the following:

[http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/vcredist_x86.exe Microsoft MSVC8 Redistributables 8.0.50727.4053 after kb973923 automatic update]

[http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/vcredist_msdev2005_x86_KB2467175.exe Microsoft MSVC8 Redistributables 8.0.50727.5592 after kb2467175 automatic update]

=== Toolpack System Database ===

The Toolpack system database is used by the main host and requires mySQL database server version 5.1 or later. It can be downloaded from the following location:

1) Go to TelcoBridges download site and get:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/mysql-5.1.56-win32.msi

2) Install MySQL 5.1

*Choose complete installation
*Run MySQL Server Instance Configuration Wizard. (You should be prompted to do so after selecting complete installation.)
*Choose standard configuration
*Install as a Windows service and check, Launch Automatically.
*Choose Include Bin Directory in Windows PATH.
*Enter a User Name and Password, and note them down on paper as you will need them later in the installation process.
*Enable access from remote machines if you plan to run Tmedia Toolpack on more than one host machine.

3) Create new database user (tbdb) with all privilege access
*Log in mysql and create a new user with priviledge

mysql -u root
CREATE USER '[DatabaseUsername]'@'%' IDENTIFIED BY '[DatabasePassword]';
GRANT ALL privileges ON *.* TO '[DatabaseUsername]'@'%' IDENTIFIED BY '[DatabasePassword]';
exit

Example

mysql -u root
CREATE USER 'tbdb'@'%' IDENTIFIED BY 'tbdbpw';
GRANT ALL privileges ON *.* TO 'tbdb'@'%' IDENTIFIED BY 'tbdbpw';
exit

4) Install Mysql ODBC driver
*Get and install Mysql ODBC connector at:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/mysql-connector-odbc-3.51.27-win32.zip
*Install Mysql ODBC connector

5) Enable mysql database replication
*Open configuration file at location similar to c:\Program Files\MySQL\MySQL Server 5.1\my.ini
*Add 2 new variable in the mysql config file, and make sure it is in the [mysqld] section:
log-bin
server-id=[UniqueId] <--- [UniqueId] must be a non-zero value, and must be unique when used one each host of an HA system

Add max_allowed_packet to increase the maximum size of binary blobs in the database.
Make sure it is in the [mysqld] section AND [mysqldump] section (create the [mysqldump] section if it doesn't exist)
max_allowed_packet = 200MB

Example:
[mysqld]
port=3306
basedir="C:/Program Files/MySQL/MySQL Server 5.1/"
datadir="C:/Documents and Settings/All Users/Application Data/MySQL/MySQL Server 5.1/Data/"
default-character-set=latin1
default-storage-engine=INNODB
# Enable mysql database replication
log-bin
server-id=132
max_allowed_packet = 200MB
#
sql-mode="STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"
max_connections=100

# section [mysqld_safe]
table_cache=256
tmp_table_size=18M
thread_cache_size=8

[mysqldump]
max_allowed_packet = 200MB

6) Disable virus scanning

It is '''mandatory''' to disable the anti-virus software’s on access scan on the MYSQL database directory (generally C:\Program Files\MySQL\MySQL Server 5.0\data) and the Windows temporary directory(typically identified by the TEMP environmental variable), as this will prevent database backup operation to complete properly upon Toolpack System Update.

7) Restart the mysql service
net stop MySQL
net start MySQL
*Warning: You may have a different service name in your system (ex. MySQL51, MySQL50, etc.). To open the service control panel, run:
services.msc

=== Toolpack System Web Portal ===

1) Install Ruby
*Go to TelcoBridges download site and get:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/ruby186-27_rc2.exe
*Install Ruby 1.8.6, check the option "Enable RubyGems", make sure the ''Add Ruby Executable to your path'' option is checked
2) Install Mongrel using the following commands.
*gem install mongrel --include-dependencies
*choose option 4. mongrel 1.1.5 (x86-mswin32-60)

=== Toolpack Stream Server ===

The Tmedia Toolpack Stream Server requires WinPCAP 4.0 or later. It can be downloaded from the following location:

1) Go to http://www.winpcap.org/ and download WinPcap_4_0_2.exe

2) Install WinPCAP 4.0

=== Toolpack Development Prerequisite ===

==== Cygwin ====
Telcobridges source package is compiled using unix Make application. For this you need to install Cygwin (Linux API layer for Windows).

1) install the latest release of cygwin.
http://www.cygwin.com/

2) The "make" package must be manually selected, it is not part of the standard cygwin installation.
*In the installer view, change to the "Full" view, search for the "make" package, click to install the latest version.

==== MSDEV ====
The Makefiles uses Visual Studio C++ compiler and linker. '''The result compiled code has no dependency on the cygwin.dll library.'''

The following Microsoft Visual Studio product could be be installed:
* Visual Studio 6.0 (1998) - MSVC6
* Visual Studio 2005 - MSVC8

==== Folder "BashPrompt" Menu item ====
This small registry entry will add a folder command to the Explorer application. This helper command can be used by right-clicking on a folder where you want to launch a compilation, it will open a console window and setup the proper compiling environment.

For Visual Studio 6.0 user, create a file named "BashPrompt1998.reg" with the following content:

<pre>
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt1998]
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt1998\command]
@="cmd.exe /k pushd \"%L\" && \"C:\\Program Files\\Microsoft Visual Studio\\VC98\\Bin\\VCVARS32.BAT\" && bash"
</pre>

*Make sure the path is the same as your installation path.
*Double click on the file to install in the registry.

For Visual Studio 2005 user, create a file named "BashPrompt2005.reg" with the following content:

<pre>
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt2005]
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt2005\command]
@="cmd.exe /k pushd \"%L\" && \"C:\\Program Files\\Microsoft Visual Studio 8\\VC\\Bin\\VCVARS32.BAT\" && bash"
</pre>

*Make sure the path is the same as your installation path.
*Double click on the file to install in the registry.

==== Environment variable ====
To finalize the compiling environment, you must set the following system variable environment ('''Start->Settings->Control Panel->System->Advanced Tab->Environment variables'''):

1) add the following path to the "PATH" environment variable, each is separated by a semi-column (;)
* C:\cygwin\bin;
* C:\Ruby\bin;

2) add the following variable:
{| cellpadding="5" border="1" class="wikitable"
|-
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | Name
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | Value
|-
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | MAKE_MODE
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | unix
|}

== Validation Guide (Optional) ==
If you would like to verify your installation go to the [[Toolpack_Installation:Validate_Toolpack_Installation_2-5|Toolpack Validation Guide]]

== Toolpack System installation ==

Now that the prerequisite are installed, now it is time to install the [[toolpack_installer_2-5|Toolpack system]]

Toolpack prerequisite Windows XP 2-5

2012-10-03T15:22:31Z

Jasmin Letendre: Fixed typo.

This page shows the Toolpack 2-5 prerequisites for Windows XP.

== Toolpack Prerequisite ==

=== Toolpack Basic packages ===

The software listed below is required by the host machines.

1) Go to TelcoBridges download site and get:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/iconv-1.9.2.win32.zip
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/libxml2-2.7.3.win32.zip
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/zlib-1.2.3.win32.zip
2) Decompress and copy the DLL files to C:\Windows\System32
iconv.dll
libxml2.dll
zlib1.dll

==== MSVC8 Redistributable ====
If you plan on using TBToolPack-x.y.zz-msvc8-Setup.exe, then you need to apply all windows updates from MicroSoft AND install the following:

[http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/vcredist_x86.exe Microsoft MSVC8 Redistributables 8.0.50727.4053 after kb973923 automatic update]

[http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/vcredist_msdev2005_x86_KB2467175.exe Microsoft MSVC8 Redistributables 8.0.50727.5592 after kb2467175 automatic update]

=== Toolpack System Database ===

The Toolpack system database is used by the main host and requires mySQL database server version 5.1 or later. It can be downloaded from the following location:

1) Go to TelcoBridges download site and get:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/mysql-5.1.56-win32.msi

2) Install MySQL 5.1

*Choose complete installation
*Run MySQL Server Instance Configuration Wizard. (You should be prompted to do so after selecting complete installation.)
*Choose standard configuration
*Install as a Windows service and check, Launch Automatically.
*Choose Include Bin Directory in Windows PATH.
*Enter a User Name and Password, and note them down on paper as you will need them later in the installation process.
*Enable access from remote machines if you plan to run Tmedia Toolpack on more than one host machine.

3) Create new database user (tbdb) with all privilege access
*Log in mysql and create a new user with priviledge

mysql -u root
CREATE USER '[DatabaseUsername]'@'%' IDENTIFIED BY '[DatabasePassword]';
GRANT ALL privileges ON *.* TO '[DatabaseUsername]'@'%' IDENTIFIED BY '[DatabasePassword]';
exit

Example

mysql -u root
CREATE USER 'tbdb'@'%' IDENTIFIED BY 'tbdbpw';
GRANT ALL privileges ON *.* TO 'tbdb'@'%' IDENTIFIED BY 'tbdbpw';
exit

4) Install Mysql ODBC driver
*Get and install Mysql ODBC connector at:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/mysql-connector-odbc-3.51.27-win32.zip
*Install Mysql ODBC connector

5) Enable mysql database replication
*Open configuration file at location similar to c:\Program Files\MySQL\MySQL Server 5.1\my.ini
*Add 2 new variable in the mysql config file, and make sure it is in the [mysqld] section:
log-bin
server-id=[UniqueId] <--- [UniqueId] must be a non-zero value, and must be unique when used one each host of an HA system

Add max_allowed_packet to increase the maximum size of binary blobs in the database.
Make sure it is in the [mysqld] section AND [mysqldump] section (create the [mysqldump] section if it doesn't exist)
max_allowed_packet = 200MB

Example:
[mysqld]
port=3306
basedir="C:/Program Files/MySQL/MySQL Server 5.1/"
datadir="C:/Documents and Settings/All Users/Application Data/MySQL/MySQL Server 5.1/Data/"
default-character-set=latin1
default-storage-engine=INNODB
# Enable mysql database replication
log-bin
server-id=132
max_allowed_packet = 200MB
#
sql-mode="STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"
max_connections=100

# section [mysqld_safe]
table_cache=256
tmp_table_size=18M
thread_cache_size=8

[mysqldump]
max_allowed_packet = 200MB

6) Disable virus scanning

It is '''mandatory''' to disable the anti-virus software’s on access scan on the MYSQL database directory (generally C:\Program Files\MySQL\MySQL Server 5.0\data) and the Windows temporary directory(typically identified by the TEMP environmental variable), as this will prevent database backup operation to complete properly upon Toolpack System Update.

7) Restart the mysql service
net stop MySQL
net start MySQL
*Warning: You may have a different service name in your system (ex. MySQL51, MySQL50, etc.). To open the service control panel, run:
services.msc

=== Toolpack System Web Portal ===

1) Install Ruby
*Go to TelcoBridges download site and get:
http://download.distribution.telcobridges.com/3rdparty/prerequisite/bin/windows/ruby186-27_rc2.exe
*Install Ruby 1.8.6, check the option "Enable RubyGems", make sure the ''Add Ruby Executable to your path'' option is checked
2) Install Mongrel using the following commands.
*gem install mongrel --include-dependencies
*choose option 4. mongrel 1.1.5 (x86-mswin32-60)

=== Toolpack Stream Server ===

The Tmedia Toolpack Stream Server requires WinPCAP 4.0 or later. It can be downloaded from the following location:

1) Go to http://www.winpcap.org/ and download WinPcap_4_0_2.exe

2) Install WinPCAP 4.0

=== Toolpack Development Prerequisite ===

==== Cygwin ====
Telcobridges source package is compiled using unix Make application. For this you need to install Cygwin (Linux API layer for Windows).

1) install the latest release of cygwin.
http://www.cygwin.com/

2) The "make" package must be manually selected, it is not part of the standard cygwin installation.
*In the installer view, change to the "Full" view, search for the "make" package, click to install the latest version.

==== MSDEV ====
The Makefiles uses Visual Studio C++ compiler and linker. '''The result compiled code as no dependency on the cygwin.dll library.'''

The following Microsoft Visual Studio product could be be installed:
* Visual Studio 6.0 (1998) - MSVC6
* Visual Studio 2005 - MSVC8

==== Folder "BashPrompt" Menu item ====
This small registry entry will add a folder command to the Explorer application. This helper command can be used by right-clicking on a folder where you want to launch a compilation, it will open a console window and setup the proper compiling environment.

For Visual Studio 6.0 user, create a file named "BashPrompt1998.reg" with the following content:

<pre>
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt1998]
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt1998\command]
@="cmd.exe /k pushd \"%L\" && \"C:\\Program Files\\Microsoft Visual Studio\\VC98\\Bin\\VCVARS32.BAT\" && bash"
</pre>

*Make sure the path is the same as your installation path.
*Double click on the file to install in the registry.

For Visual Studio 2005 user, create a file named "BashPrompt2005.reg" with the following content:

<pre>
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt2005]
[HKEY_CLASSES_ROOT\Folder\shell\BashPrompt2005\command]
@="cmd.exe /k pushd \"%L\" && \"C:\\Program Files\\Microsoft Visual Studio 8\\VC\\Bin\\VCVARS32.BAT\" && bash"
</pre>

*Make sure the path is the same as your installation path.
*Double click on the file to install in the registry.

==== Environment variable ====
To finalize the compiling environment, you must set the following system variable environment ('''Start->Settings->Control Panel->System->Advanced Tab->Environment variables'''):

1) add the following path to the "PATH" environment variable, each is separated by a semi-column (;)
* C:\cygwin\bin;
* C:\Ruby\bin;

2) add the following variable:
{| cellpadding="5" border="1" class="wikitable"
|-
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | Name
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | Value
|-
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | MAKE_MODE
! width="80" style="background: none repeat scroll 0% 0% rgb(255, 255, 255);" | unix
|}

== Validation Guide (Optional) ==
If you would like to verify your installation go to the [[Toolpack_Installation:Validate_Toolpack_Installation_2-5|Toolpack Validation Guide]]

== Toolpack System installation ==

Now that the prerequisite are installed, now it is time to install the [[toolpack_installer_2-5|Toolpack system]]

Configure Fax Relay C

2012-07-13T12:44:04Z

Jasmin Letendre: /* Applies to version(s): v2.7. */

=== '''''Applies to version(s): v2.7.''''' ===
{{DISPLAYTITLE:Configure Fax Relay}}

This is the list of fax Options.
To see that list, you have to go in a Profile, then in section Fax/Modem Relay.

'''Fax Relay'''
{| cellpadding="5" border="1" class="wikitable"
|-
! width="210" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Options
! width="610" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Description
|-
| Enable Fax Relay
| This option is the global option telling if faxes (Passthrough or T38) will be relayed or not.
|-
| Detection Mode
| This option contains one of the following mode: Standard, Use relay mode on any tone or Always Relay. 
Standard: Fax tones and T.38 re-invites will trigger fax relay mode. Modem tones and passthrough re-invites will trigger passthrough mode, though fax detection will still continue. 
Use relay mode on any tone: Both fax and modem tones will immediately cause switch to the chosen relay mode (without going to passthrough first for modem tones). 
Always relay: Calls are directly invited using the specified relay mode, without waiting for any fax/modem tone. This improves performance when the calls are known to always be fax or modem (e.g. when connecting with a fax server).
|-
| Relay Mode
| This option is to choose which mode of fax will be used. This option contains one of the following mode: T.38 or Passthrough. 
T.38: This relay mode is used for faxes modulated in IP. 
Passthrough: Fax passthrough encodes fax traffic with in a G.711 (ulaw or alaw) voice codec and sends it across the VoIP network as a voice call. In this mode, echo cancellers are disabled, there's a fixed jitter buffer and there's no Voice Activity Detection.
|-
| Modem vs. Fax distinction timeout
| This option is the time we wait after we got the CED, to get V21 flags.
This is to avoid to send a SIP re-invite in passthrough and few ms after, when we realize it's a faxes, send another SIP
re-invite in T38.
Since CED is both for modem and faxes, we have the choice to wait a few ms before taking the "final" decision.
The best choice depends on the setup. In general, 0ms will work fine. If the endpoint is T.38, then the option "Always Relay" will override the "Modem vs. Fax distinction timeout". Otherwise, 500ms will save a re-invite, but takes
longer to switch to passthrough if the final result is modem.
|-
| Fax tones detection duration
| This option is the maximum time (in seconds) to listen for FAX tones. After that delay, FAX tones are ignored. This avoids false FAX detection later in the call when a sound in an audio conversation has frequencies very similar to a FAX tone. Default time is 30 seconds. Can be set to 0 to keep fax detection enabled throughout the entire call.
|-
| Enable early Fax/Modem tone detection
| This option is used to detect longer fax tones (CED and CNG) faster. Fax tones will be reported at the beginning of the detection instead of waiting to validate the tone duration before reporting. The drawback is that it increases the chance of detecting false positive, since these fax tones are single frequency tone and can appear frequently in an audio conversation. We suggest to keep this option turned off to avoid these false positives. 
|-
| Enable switching to fax relay upon CNG tone
| This option indicates if the detection of a CNG tone will trigger a switch to fax relay mode. We recommend to leave this option enabled for faster switch to fax in most setup. 
Note: this option works only if the sender Fax is on TDM (this option will do nothing if the sender fax is on SIP).
|}

'''T.38 Params'''
{| cellpadding="5" border="1" class="wikitable"
|-
! width="210" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Options
! width="610" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Description
|-
| Use V.34
| This option activates support for V.34 faxes. By using that option, faxes can be transferred at speed up to 33.6 Kbps. 
If disabled, only V.17 faxes will be supported (transfer speed up to 14.4 Kbps). 
Before using this option, you also need to enable V.34 Globally on each Telecom unit:
Hardware -> TB00xxxx [Edit] -> Advanced Parameters -> Enable V.34 fax
After this has been done, a restart of the Telecom unit is required:
Status Tab -> Reboot adapter -> Yes [Apply States]
|-
| Max bitrate
| This option is used to limit the maximum bitrate of faxes. By default, faxes will try to train at maximum bitrate. If a Failure to Train (FTT) happens, the bitrate will be reduced again and again. This option is used when you want to specify the maximum bitrate.
By using that option, faxes transmission can complete in less time since unnecessary training sequences will be skipped.
|-
| Fill bit removal
| This option is used to remove inserted fill bits in Phase C for non-ECM data. 
We suggest to leave this option unchecked.
|-
| TCF transfer mode
| Transfer training in T.38 or generate locally the Training Confirmation. 
We suggest to leave this option at Transferred (default option).
|-
| Redundancy Count
| This option indicates how many times each fax control frame will be sent. Note that this only applies to fax control frame. It does not apply to fax page data.
|-
| Transmission level (-1dBm unit)
| This option is to adjust the transmission level to the TDM network. Valid values are between 0 and -15dBm, inclusive.
|}

'''Modem/Fax Passthrough Params'''
{| cellpadding="5" border="1" class="wikitable"
|-
! width="210" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Options
! width="610" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Description
|-
| Detection type
| This option is used to detect if a call will be in passthrough mode. Possible values are: None, Silence Suppression Off and G711 Only. 
*"None" means no Passthrough will be triggered whatever the SPD is. 
*"G711 only" means if there's only G711 codecs (ulaw and/or alaw), this call will be treated as a passthrough call. This is true when sending or receiving SDP. 
*"Silence Suppression Off" means when receiving an SIP invite, if the SDP contains the attribute "a=silenceSupp:off - - - -", it will be treated as a Passthrough call. When sending SIP invite for a passthrough call, the same attribute will be used. This option works if there's only G711 codecs in the list of supported media. So this option is a bit less resrictive than "G711 only"
|-
| Codec
| This option specifies which codec will be used for fax passthrough. By nature, fax passthrough MUST be a non-compressed codec so you can choose between PCMU or PCMA. Note that when a switch to passthrough is initiated by the remote endpoint, our gateway will always use the same codec as the peer. 
|-
| Jitter Buffer Depth
| This option is to specify what will be the size of the fixed Jitter Buffer when in passthrough mode.
|-
| Use NSE
| This option is to specify what method will be used to switch to Passthru. NSE is a way to swith using RTP events instead of SIP re-INVITE.
|
|}

== References ==

*[http://en.wikipedia.org/wiki/Fax#Data_transmission_rate Wikipedia article]
*[http://docs.telcobridges.com/tbwiki/NSE NSE]

[[Category:Glossary]]

Configure Fax Relay C

2012-06-18T13:35:19Z

Jasmin Letendre: Modified some phrasings.

This is the list of fax Options.
To see that list, you have to go in a Profile, then in section Fax/Modem Relay.

{| cellpadding="5" border="1" class="wikitable"
|-
! width="210" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Options
! width="610" style="background: none repeat scroll 0% 0% rgb(239, 239, 239);" | Description
|-
| Enable Fax Relay
| This option is the global option telling if faxes (Passthrough or T38) will be relayed or not.
|-
| Detection Mode
| This option contains one of the following mode: Standard, Use relay mode on any tone or Always Relay. 
Standard: Fax tones and T.38 re-invites will trigger fax relay mode. Modem tones and passthrough re-invites will trigger passthrough mode, though fax detection will still continue. 
Use relay mode on any tone: Both fax and modem tones will immediately cause switch to the chosen relay mode (without going to passthrough first for modem tones). 
Always relay: Calls are directly invited using the specified relay mode, without waiting for any fax/modem tone. This improves performance when the calls are know to always be fax or modem (e.g. when connecting with a fax server).
|-
| Relay Mode
| This option is to choose which mode of fax will be used. This option contains one of the following mode: T.38 or Passthrough. 
T.38: This relay mode is used for faxes modulated in IP. 
Passthrough: Fax passthrough encodes fax traffic with in a G.711 (ulaw or alaw) voice codec and sends it across the VoIP network as a voice call. In this mode, echo cancellers are disabled, there's a fixed jitter buffer and there's no Voice Activity Detection.
|-
| Modem vs. Fax distinction timeout
| This option is the time we wait after we got the CED, to get V21 flags.
This is to avoid to send a SIP re-invite in passthrough and few ms after, when we realize it's a faxes, send another SIP
re-invite in T38.
Since CED is both for modem and faxes, we have the choice to wait a few ms before taking the "final" decision.
The best choice depends on the setup. In general, 0ms will work fine. If the endpoint is T.38, then the option "Always Relay" will override the "Modem vs. Fax distinction timeout". Otherwise, 500ms will save a re-invite, but takes
longer to switch to passthrough if the final result is modem.
|-
| Fax tones detection duration
| This option is the maximum time (in seconds) to listen for FAX tones. After that delay, FAX tones are ignored. This avoids false FAX detection later in the call when a sound in an audio conversation has frequencies very similar to a FAX tone. Default time is 30 seconds. Can be set to 0 to keep fax detection enabled throughout the entire call.
|-
| Enable early Fax/Modem tone detection
| This option is used to detect longer fax tones (CED and CNG) faster. Fax tones will be reported at the beginning of the detection instead of waiting to validate the tone duration before reporting. The drawback is that it increases the chance of detecting false positive, since these fax tones are single frequency tone and can appear frequently in an audio conversation. We suggest to keep this option turned off to avoid these false positives. 
|-
| Enable switching to fax relay upon CNG tone
| This option indicates if the detection of a CNG tone will trigger a switch to fax relay mode. We recommend to leave this option enabled for faster switch to fax in most setup.
|-
| Use V.34
| This option activates support for V.34 faxes. By using that option, faxes can be transferred at speed up to 33.6 Kbps. 
If disabled, only V.17 faxes will be supported (transfer speed up to 14.4 Kbps).
|-
| Max bitrate
| This option is used to limit the maximum bitrate of faxes. By default, faxes will try to train at maximum bitrate. If a Failure to Train (FTT) happens, the bitrate will be reduced again and again. This option is used when you want to specify the maximum bitrate.
By using that option, faxes transmission can complete in less time since unnecessary training sequences will be skipped.
|-
| Fill bit removal
| This option is used to remove inserted fill bits in Phase C for non-ECM data. 
We suggest to leave this option unchecked.
|-
| TCF transfer mode
| Transfer training in T.38 or generate locally the Training Confirmation. 
We suggest to leave this option at Transferred (default option).
|-
| Redundancy Count
| This option indicates how many times each fax control frame will be sent. Note that this only applies to fax control frame. It does not apply to fax page data.
|-
| Transmission level (-1dBm unit)
| This option is to adjust the transmission level to the TDM network. Valid values are between 0 and -15dBm, inclusive.
|-
| Detection type
| This option is used for different types of fax passthrough. When receiving an SIP invite, Our
|-
| Codec
| This option specifies which codec will be used for fax passthrough. By nature, fax passthrough MUST be a non-compressed codec so you can choose between PCMU or PCMA. Note that when a switch to passthrough is initiated by the remote endpoint, our gateway will always use the same codec as the peer.
|-
| Jitter Buffer Depth
| This option is to specify what will be the size of the fixed Jitter Buffer when in passthrough mode.
|}

== References ==

*[http://en.wikipedia.org/wiki/Fax#Data_transmission_rate Wikipedia article]

[[Category:Glossary]]

CAF: Working With Caf Call Legs

2012-01-20T14:50:38Z

Jasmin Letendre: Added missing "ptrAcceptCallProtAttribute = tbnew CTBCMC_PROTOCOL_ATTRIBUTE;"

== Overview of CAF layer ==
TelcoBridges provides multiple API layers for managing calls.
The current page refers the the CAF API layer.

[[File:CAFCallFlow_architecture.png|400px]]

== Overview of CAF call architecture ==

[[File:CAFCallFlow_ownership.png|400px]]

=== CAF Call leg (''CTBCAFCallLeg''): ===
The ''CTBCAFCallLeg'' (based on CTBCMCLeg base class) is the representation of communication with one peer, either through one protocol (SS7, ISDN, SIP, CAS) or media-only.

CTBCAFCallLeg objects can be created either after the [[Toolpack_Application:toolpack_engine|toolpack_engine]] has notified the CAF application that a new call has been received, or else when the CAF application asks [[Toolpack_Application:toolpack_engine|toolpack_engine]] to create a new outgoing call.
When creating a new outgoing call, attributes are provided to indicate [[Toolpack_Application:toolpack_engine|toolpack_engine]] which NAP to make the call to (which also defines the signaling protocol), which calling/called numbers to use, etc.

From the C++ point of view, the CTBCMCLeg contains most of the APIs require to manipulate call legs, while the ''CTBCAFCallLeg'' class is providing the interface to attach call legs to a parent ''CTBCAFCallFlow'' object

=== CAF Mixer (''CTBCAFMixer''): ===
CAF Call Legs (''CTBCAFCallLeg'') have a built-in function to join with another leg, making audio flow from one leg to the other directly.

However, when it is required to mix audio from multiple call legs or sources (building conferences for example), then the ''CTBCAFMixer'' object is used.

The ''CTBCAFMixer'' (based on CTBCMCMixer base class) is the representation of a DSP resource used to mix audio from different sources (call legs, stream server, or other mixers).

From the C++ point of view, the CTBCMCMixer contains most of the APIs require to manipulate mixers, while the ''CTBCAFMixer'' class is providing the interface to attach mixers to a parent ''CTBCAFCallFlow'' object.

The ''CTBCAFMixer'' object can be used for:
* Conferences
* Background music playing on a call
* Recording both call legs of a call into one mixed audio file
* etc.

See more information on mixers here: [[http://docs.telcobridges.com/mediawiki/index.php/AudioMixers Audio Mixers]]

=== CAF Call Flow (''CTBCAFCallFlow''): ===

The ''CTBCAFCallFlow'' base class contains one or multiple ''CTBCAFCallLeg'' objects, and optionally one or multiple ''CTBCAFMixer'' objects. The role of the ''CTBCAFCallFlow'' object is to implement a call flow that involves actions on legs and mixers that have a relation with each other.

=== CAF Call Bridge (''CTBCAFBridge'', based on ''CTBCAFCallFlow''): ===

A typical implementation of a call flow is the ''CTBCAFBridge'' class (based on the ''CTBCAFCallFlow'' base class). This class is designed to
- Receive an incoming call
- Make a corresponding outgoing call
- Join them together
- Terminate both of them when one leg hangups.

=== CAF Call Behavior (''CTBCAFCallBehavior''): ===

Behaviors ''CTBCAFCallBehavior'' can be attached to a call flow (''CTBCAFCallFlow''). Their role is to modify the basic call flow, decorating it with optional functionality (CDR logging, FAX detection, Ring tone playback, etc.)

In order to implement their functionality, behavior objects, like their parent call flow object, receive events from all call legs and mixers of the call flow. They can also manipulate call legs and mixers.

== Performing actions on call legs and mixers ==
=== Actions on call legs ===
The call flow (and it's behaviors) can perform various actions on each of it's call legs. Here is a list of the actions available on the CTBCAFCallLeg objects (please refer to the header file '''CTBCMCLeg.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Call_Leg_Actions Actions on CTBCAFCallLeg]]

=== Actions on mixers ===
The call flow (and it's behaviors) can perform various actions on each of it's mixers. Here is a list of the actions available on the CTBCAFMixer objects (please refer to the header file '''CTBCMCMixer.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Mixer_Actions Actions on CTBCAFMixer]]

== Receiving events from call legs and mixers ==

[[File:CAFCallFlow_event.png|400px]]

=== Events received from call legs by the CTBCAFCallFlow object ===

The call flow object (as well as all it's behaviors) receive the following events from it's call legs (please refer to the header file '''ITBCAFCallFlow.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Call_Leg_Events Call flow events from it's call legs]]

=== Events received from mixers by the CTBCAFCallFlow object ===

The call flow object (as well as all it's behaviors) receive the following events from it's mixers (please refer to the header file '''ITBCAFCallFlowMixer.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Mixer_Events Call flow events from it's mixers]]

=== Events behavior chain ===
All the events describe above are called consecutively on each behavior attached to the call flow, and ultimately, called on the call flow itself.

Each behavior in the chain can
* Pass the event to the next behavior in the chain
* Consume the event so other behaviors in the chain and the call flow are unaware that this event occurred

The ''CTBCAFCallBehavior'' default implementation is to forward the event to the next event in the chain.

When you implement your own behaviors, you can override only a couple of events (like OnCallLegAnswered() for example) to perform specific tasks, and leave all other events to the base class, so you don't have to write a lot of code to create a new behavior.

== Example call flows ==

Example call flow where an incoming call is received, accepted, then terminated from network side:

[[File:example_call_flow.png|500px]]

Example conference call flow with two incoming call legs, one outgoing call leg, and one audio mixer:

[[File:example_call_flow_conf.png|400px]]

== Creating the ''CTBCAFCallFlow'' object, its legs and mixers ==
Steps to create a new call flow are:
* Create a new object (using a class derived from ''CTBCAFCallFlow'' class)
* Attach behaviors to the call flow
* Add attributes of incoming and outgoing legs to create
* Add attributes for mixers to create
* Tell the call flow object to initialize itself, and create the call legs and mixers as requested
* Join legs together, join legs to mixers, or join mixers to other mixers

Here is a (over-simplified) example:
ITBCAFCallFlow* pCallFlow;
ITBCAFCallFlow* pParentCallOrBehavior;

// Create the call flow object (here using the CTBCAFBridge class, based on CTBCAFCallFlow)
pCallFlow = tbnew CTBCAFBridge( 0, this);

// Optionally, attach behaviors
pParentCallOrBehavior = pCallFlow;
pParentCallOrBehavior = tbnew CTBCAFCallBehaviorBusyTone( pParentCallOrBehavior, ... );
pParentCallOrBehavior = tbnew CTBCAFCallBehaviorBridgeCdr( pParentCallOrBehavior, ... );

// Add an incoming call leg to that call flow (CTBCAFCallLeg object will get created based on provided attributes)
pCallFlow->AddIncoming( in_LegId, ptrIncomingLegAttribute, ptrIncomingLegProtocolAttributes, ptrAcceptCallProtAttribute );

// Add an outgoing call leg
pCallFlow->AddOutgoing( ptrOutgoingLegAttribute, ptrOutgoingLegProtocolAttributes );

// Create an audio mixer
pCallFlow->MixerCreate( ptrMixerAttribute );

// Initialize the call (this actually creates the call legs)
pCallFlow->InitCall( &pCallFlow );

During the call flow (upon reception of an event on a call leg for example), more actions can be taken. For example:
MyCallFlowOrBehavior::OnCallLegAnswered()
{
// Ask to detect FAX tones
CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "telcofax/eof" );
GetIncomingActiveLeg()->StartEventCollection( in_EventMask, NULL, TBX_FALSE /* Don't suppress tones */ );

// Call base class to forward event to next behavior
CTBCAFBehavior::OnCallLegAnswered();
}

During the call flow (upon reception of an event on a mixer for example), more actions can be taken. For example:
MyCallFlowOrBehavior::OnMixerCreated()
{
// Immediately add call legs to the mixer
GetFirstMixer()->MixerJoin( GetIncomingActiveLeg().Get(), ptrJoinAttributes );
GetFirstMixer()->MixerJoin( GetOutgoingActiveLeg().Get(), ptrJoinAttributes );

// Answer the incoming leg
GetIncomingActiveLeg()->AnswerCall();

// Play background music on the conference
GetFirstMixer()->MixerPlayStream( PlayAttr );

// Call base class to forward event to next behavior
CTBCAFBehavior::OnMixerCreated();
}

For a more complete code example, please refer to the simple_call application, in file '''CTBS2GWSimpleCall.cpp''', or here:

[[CAF:_Leg_Creation_Samples#Bridging_an_Incoming_Call_Leg_.28using_CTBCAFBridge_.29|CTBCAFBridge creation]]

=== Constructing leg attributes ===
==== Incoming call leg attributes ====
To create the incoming call leg, the following information is required:
* Smart pointer to incoming call leg attributes, received from [[Toolpack_Application:toolpack_engine|toolpack_engine]] through ''OnCallLegPresent''().
ptrIncomingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE( *(in_CallLegAttribute.GetCallLegAttribute()) );
* Smart pointer to incoming call leg protocol attributes, received from [[Toolpack_Application:toolpack_engine|toolpack_engine]] through ''OnCallLegPresent''().
ptrIncomingLegProtocolAttributes = tbnew CTBCMC_PROTOCOL_ATTRIBUTE( in_ProtocolAttribute, TBX_TRUE );
* Smart pointer to empty protocol attributes that Behaviors can fill, and that will be used when accepting the call.
ptrAcceptCallProtAttribute = tbnew CTBCMC_PROTOCOL_ATTRIBUTE;

==== Outgoing call leg attributes ====
To create the outgoing call leg, the following information is required:
* Smart pointer to outgoing call leg attributes to use to create the call, generally derived from the incoming call attributes
ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();
ptrOutgoingLegAttribute->CopyLegAttributeFrom( *(ptrIncomingLegAttribute.Get()) );
* Smart pointer to empty protocol attributes that Behaviors can fill, and that will be used when creating the outgoing call (SIP invite, ISUP IAM, ISDN Setup, etc.)

==== Mixer attributes ====
To create the mixer, the following information is required:
* Smart pointer to mixer attributes to use to create the mixer
ptrMixerAttribute = tbnew CTBCMC_MIXER_ATTRIBUTE();
ptrMixerAttribute->SomeParameter = SomeValue;

=== Call leg initialization callbacks ===
All behaviors attached to the call flow will be notified of the creation of new call legs through callback '''OnInitIncomingCallLeg()''' or '''OnInitOutgoingCallLeg()'''.

==== '''OnInitIncomingCallLeg()''' ====
In this callback, each behavior may consult the incoming call attributes or protocol attributes, and can modify the protocol attributes that will be used to accept the call (actually providing protocol-specific information, like SS7 IEs, or SIP headers).

==== '''OnInitOutgoingCallLeg()''' ====
In this callback, each behavior can modify the protocol attributes that will be used to create the call (actually providing protocol-specific information, like SS7 IEs, or SIP headers that will be used in the initial signaling message, as SIP Invite, ISUP IAM, or ISDN Setup).

==== ''OnMixerInit()'' ====
In this callback, each behavior can modify the mixer attributes that will be used to create the mixer.

== Destruction the ''CTBCAFCallFlow'' object, its legs and mixers ==
=== Self-destructing call legs, mixers, behaviors, and call flow ===
The ''CTBCAFCallFlow'' object contains smart pointers to it's call legs and mixers. Destruction of these will thus occur automatically when the last smart pointer reference is removed (that last reference can be either the smart pointer reference in the CTBCAFCallFlow object, or anywhere else in the application).

Upon destruction of the last call leg or last mixer (when no more leg or mixer are in the call flow), the objects based on ''CTBCAFCallFlow'' or ''CTBCAFCallBehavior'' will delete themselves automatically, by calling the attached "free listener" (that was provided in the constructor of the call flow object).

=== Call leg termination callbacks and actions ===
==== '''OnCallLegTerminatingIndication()''' ====
This callback means that [[Toolpack_Application:toolpack_engine|toolpack_engine]] has received a termination request from a call leg (SIP Bye, ISUP REL, for example).
A typical use of that event is to call '''TerminateCall()''' on both incoming and outgoing legs of a call flow, to hangup both sides.

==== '''TerminateCall()''' ====
This function is used for the application to request the termination of a call leg.
It is also used to confirm that the application is done with a call leg, after '''OnCallLegTerminatingIndication()''' event was received (in that case, '''TerminateCall()''' can be called within the event callback, or later if the application has some more asynchronous cleanup to do).

==== '''OnCallLegTerminated()''' ====
This callback confirms that [[Toolpack_Application:toolpack_engine|toolpack_engine]] has finished closing the data path and signaling for this call leg.
It will also be called when a leg is destroyed because of a lost of communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] (restart, network failure, crash).

==== '''FreeLeg()''' ====
It is MANDATORY that this function is called for each call leg after '''OnCallLegTerminated()'''.

It's up to the application to call the function immediately (within '''OnCallLegTerminated()''' for example) or later after doing some more job (like asynchronous database updates, for example)

==== '''OnLegFreed()''' ====
This callback confirms that the leg is being freed.

It's the last chance for a call flow or a behavior to release things related to a call leg, like canceling timers for example.

*'''Important note:''' Behaviors that implement that function MUST, as the LAST line of their function, call the base class' '''CTBCAFCallBehavior::OnLegFreed'''. Not calling base class' function will cause the call to leak. Calling that before the last line of the function will cause crash, as the Behavior object could destroy itself within that function upon destruction of the last leg/mixer of the call.

=== Mixer termination callbacks and actions ===

==== '''MixerTerminate()''' ====
This function is used for the application to request the termination of a mixer.

==== '''OnMixerTerminated()''' ====
This callback confirms that [[Toolpack_Application:toolpack_engine|toolpack_engine]] has finished destroying resources related to this mixer.
It will also be called when a leg is destroyed because of a lost of communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] (restart, network failure, crash).

==== '''FreeMixer()''' ====
It is MANDATORY that this function is called for each mixer after '''OnMixerTerminated()'''.

It's up to the application to call the function immediately (within '''OnMixerTerminated()''' for example) or later after doing some more job (like asynchronous database updates, for example)

==== '''OnMixerFreed()''' ====
This callback confirms that the mixer is being freed.

It's the last chance for a call flow or a behavior to release things related to a mixer, like canceling timers for example.

*'''Important note:''' Behaviors that implement that function MUST, as the LAST line of their function, call the base class' '''CTBCAFCallBehavior::OnMixerFreed()'''. Not calling base class' function will cause the mixer and call to leak. Calling that before the last line of the function will cause crash, as the Behavior object could destroy itself within that function upon destruction of the last leg/mixer of the call.

== Re-synchronizing with [[Toolpack_Application:toolpack_engine|toolpack_engine]] ==
There are a couple of cases where a CAF application needs to re-synchronize with [[Toolpack_Application:toolpack_engine|toolpack_engine]]:
* The CAF application was restarted
* The [[Toolpack_Application:toolpack_engine|toolpack_engine]] was restarted
* Network connection between CAF application and [[Toolpack_Application:toolpack_engine|toolpack_engine]] was momentarily down

When communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] is lost, all call legs and mixers are notified of the disconnection through '''OnSyncLost()''' and '''OnMixerSyncLost()'''. However, they are not immediately destroyed. They are kept in the CAF framework for 10 seconds waiting for the engine (or backup engine) to reconnect. After 10 seconds, legs and mixers are terminated in the CAF framwork. This does not mean, however, that they are terminated in the toolpack_engine. Upon reconnection with engine, legs and mixers still present in the engine will be sent back to the CAF application through '''OnCallLegSync()''' and '''OnMixerSync()'''.

Possible scenarios for a leg are thus:
* Engine is reconnected within 10 seconds:
** Some legs/mixers no more exist in [[Toolpack_Application:toolpack_engine|toolpack_engine]], and will be notified by '''OnCallLegTerminated()''' / '''OnMixerTerminated()'''.
** Legs/mixers that are still valid will be untouched (though they are notified with '''OnLegSync()''' / '''OnLinkSync()''' / '''OnMixerSync()''', for convenience)
* Engine has been disconnected for more than 10 seconds:
** CAF framework will terminate call legs/mixers, and notify them through '''OnCallLegTerminated()''' / '''OnMixerTerminated()'''
** Later, when engine is reconnected after a >10:
*** Call legs/mixers that are still available in [[Toolpack_Application:toolpack_engine|toolpack_engine]] are pushed back to CAF application through '''OnCallLegSync()''', '''OnLinkSync()''' and '''OnMixerSync()'''
*** CAF application can refuse them, or re-build it's legs/mixers/call flow contexts to resume operation on these calls

=== Re-synchronization sequence ===

In all the cases above, the re-synchronization mechanism involves the following steps:

=> Communication lost with [[Toolpack_Application:toolpack_engine|toolpack_engine]]
* '''OnCmcLibNotReady()''' (CAF application callback): Indicates that communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] has been interrupted. It will not be possible to perform actions (play file, ask for digit collection) on call legs/mixers until [[Toolpack_Application:toolpack_engine|toolpack_engine]] is ready again ('''OnCmcLibReady''').
* '''OnSyncLost()''' (CAF call flow and behavior callback): Same meaning as '''OnCmcLibNotReady()''', passed to each call leg contexts individually.
* '''OnMixerSyncLost()''' (CAF call flow and behavior callback): Same meaning as '''OnCmcLibNotReady()''', passed to each call mixer contexts individually.

=> Communication re-established with [[Toolpack_Application:toolpack_engine|toolpack_engine]]
* '''OnCallLegSync()''' (CAF application callback): Indicates that the [[Toolpack_Application:toolpack_engine|toolpack_engine]] knows about a call leg that does not exist in the CAF application.
* '''OnLinkSync()''' (CAF application callback): Indicates that the [[Toolpack_Application:toolpack_engine|toolpack_engine]] knows about a link between two call legs (legs are joined, audio is flowing from one to the other directly).
* '''OnMixerSync()''' (CAF application callback): Indicates that the [[Toolpack_Application:toolpack_engine|toolpack_engine]] knows about a mixer that does not exist in the CAF application.
* '''OnCmcLibReady()''' (CAF application callback): Indicates that communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] has been restored, and that all legs, links and mixers have been re-synchronized
* '''OnSyncDone()''' (CAF call flow and behavior callback): Indicates to a call leg (that previously received '''OnSyncLost()''') that it is still present in the [[Toolpack_Application:toolpack_engine|toolpack_engine]], and ready to be controlled again.
* '''OnMixerSyncDone()''' (CAF call flow and behavior callback): Indicates to a mixer (that previously received '''OnMixerSyncLost()''') that it is still present in the [[Toolpack_Application:toolpack_engine|toolpack_engine]], and ready to be controlled again.
* '''OnCallLegTerminated()''' (CAF call flow and behavior callback): When this function is called with Reason ''TBCMC_CALL_REASON_CODE_TOOLPACK_SYNC_DROP'', it indicates that this call leg is no more present in [[Toolpack_Application:toolpack_engine|toolpack_engine]] after re-synchronizing, and must thus be freed in the CAF application too.
* '''OnMixerTerminated()''' (CAF call flow and behavior callback): When this function is called, it indicates that this mixer is no more present in [[Toolpack_Application:toolpack_engine|toolpack_engine]] after re-synchronizing, and must thus be freed in the CAF application too.

=== Rebuilding new legs, mixers and call flow objects ===
When an application receives '''OnCallLegSync()''', it must take the decision to either keep the call leg (create a CTBCAFCallLeg object) or refuse it (tell [[Toolpack_Application:toolpack_engine|toolpack_engine]] that we don't want to re-synchronize it, and that it must be terminated).

When an application receives '''OnMixerSync()''', it must take the decision to either keep the mixer (create a CTBCAFMixer object) or refuse it (tell [[Toolpack_Application:toolpack_engine|toolpack_engine]] that we don't want to re-synchronize it, and that it must be terminated).

==== Dropping re-synchronized legs ====
The static helper function '''CTBCMCLeg::RefuseLeg()''' has been provided by the class ''CTBCMCLeg'' to terminate re-synchronized call legs without having to worry about creating any object. An application that wants to refuse a re-synchronized leg should call it.

==== Dropping re-synchronized links ====
The static helper function '''CTBCMCLeg::RefuseLink()''' has been provided by the class ''CTBCMCLeg'' to terminate re-synchronized links without having to worry about creating any object. An application that wants to refuse a re-synchronized link should call it.

==== Dropping re-synchronized mixers ====
The static helper function '''CTBCMCMixer::RefuseMixer()''' has been provided by the class ''CTBCMCMixer'' to terminate re-synchronized mixer without having to worry about creating any object. An application that wants to refuse a re-synchronized mixer should call it.

==== Keeping re-synchronized legs that are part of a link or a mixer ====
The helper class ''CTBCAFCallLegResync'' is provided to help creating CTBCAFCallLeg objects for re-synchronized legs, and later retrieve them and attach them to a CTBCAFCallFlow parent, upon '''OnLinkSync()''' or '''OnMixerSync()''':

Upon '''OnLegSync()''', legs should be allocated inside the class ''CTBCAFCallLegResync'' using function '''AllocateCallLeg()'''. Legs don't yet need to be attached to a parent CTBCAFCallFlow, that's normally done upon '''OnLinkSync()''' or '''OnMixerSync()'''.

Upon '''OnLinkSync()''', the LegId of the two joined call legs are provided. Both legs must be retrieved from the ''CTBCAFCallLegResync'' (using functions '''FindCallLeg()''' and '''RemoveCallLeg()'''), then added to a CTBCAFCallFlow object that will resume the call flow of these two joined call legs.

Upon '''OnMixerSync()''', the LegId of all legs in that mixer (along with Join Attributes) are provided. A new CTBCAFMixer object must be allocated, and all call legs from that mixer must be retrieved from the ''CTBCAFCallLegResync'' object (using functions '''FindCallLeg()''' and '''RemoveCallLeg()'''). The allocated mixer and found legs must then be assigned to a CTBCAFCallFlow object that will resume the call flow.

Finally, upon '''OnCmcLibReady()''', the application can destroy the CTBCAFCallLegResync object, which will take care of refusing (dropping) all call legs that it still references (that have not been removed by '''CTBCAFCallLegResync::RemoveCallLeg''')

Simplified example code:

TBX_VOID CTBMyApp::OnCallLegSync
(
IN TBCMC_LEG_ID in_LegId,
IN CTBCMC_CALL_LEG_ATTRIBUTE_COMMON& in_CallLegAttribute
)
{
// Upon first re-synchronized leg, allocate utility class to contain re-synchronized call legs
if( !mpCallLegResync )
{
mpCallLegResync = new TBCAF::CTBCAFCallLegResync( MY_APP_MAX_CALLS );
}

// Re-create a CTBCAFCallLeg object for this re-synchronized leg
mpCallLegResync->AllocateCallLeg
(
NULL, // Not yet bound to a parent call flow
in_LegId, // Use the leg Id of this re-synchronized call leg
in_CallLegAttribute, // Store the attributes of this re-synchronized call leg
this, // Until it has a parent call flow, set ourself as
TBCMC_MSG_CALL_LEG_STATE_ACTIVE // Consider this call leg as active (answered)
// since only active calls can be re-synchronized
);
}

TBX_VOID CTBMyApp::OnLinkSync
(
IN TBCMC_LINK_ID in_LinkId,
IN TBCMC_LEG_ID in_SrcLegId,
IN TBCMC_LEG_ID in_DstLegId,
IN CTBCMC_JOIN_ATTRIBUTE & in_JoinAttribute
)
{
// Find both call legs in the re-sync utility mpCallLegResync
PTRCTBCAFCallLeg ptrSrcLeg = mpCallLegResync->RemoveCallLeg( in_SrcLegId );
PTRCTBCAFCallLeg ptrDstLeg = mpCallLegResync->RemoveCallLeg( in_DstLegId );

// Allocate a new call flow
PITBCAFCallFlow pMyCallFlow = tbnew CTBCAFMyCallFlow
(
this, // Set current application as free listener for my call flow
in_LinkId, // Id of the link between these two joined legs
in_JoinAttribute, // Attributes of the link between these two joined legs
ptrSrcLeg,
ptrDstLeg
);

// Re-attach behaviors to this call flow
pMyCallFlow = tbnew CTBCAFMyFirstBehavior( pMyCallFlow, ... );
pMyCallFlow = tbnew CTBCAFMySecondBehavior( pMyCallFlow, ... );
}

TBX_VOID CTBMyApp::OnCmcLibReady()
{
// Free all single call legs that remain
// Deleting mpCallLegResync will automatically reject legs still in that object
delete mpCallLegResync;
mpCallLegResync = NULL;
}

TBX_VOID CTBMyApp::OnCmcLibNotReady()
{
// Free all single call legs that remain
// Deleting mpCallLegResync will automatically reject legs still in that object
delete mpCallLegResync;
mpCallLegResync = NULL;
}

For a more complete code example, please refer to the simple_call application, in file '''CTBS2GWSimpleCall.cpp'''.

CAF: Working With Caf Call Legs

2012-01-20T14:48:05Z

Jasmin Letendre: /* Incoming call leg attributes */

== Overview of CAF layer ==
TelcoBridges provides multiple API layers for managing calls.
The current page refers the the CAF API layer.

[[File:CAFCallFlow_architecture.png|400px]]

== Overview of CAF call architecture ==

[[File:CAFCallFlow_ownership.png|400px]]

=== CAF Call leg (''CTBCAFCallLeg''): ===
The ''CTBCAFCallLeg'' (based on CTBCMCLeg base class) is the representation of communication with one peer, either through one protocol (SS7, ISDN, SIP, CAS) or media-only.

CTBCAFCallLeg objects can be created either after the [[Toolpack_Application:toolpack_engine|toolpack_engine]] has notified the CAF application that a new call has been received, or else when the CAF application asks [[Toolpack_Application:toolpack_engine|toolpack_engine]] to create a new outgoing call.
When creating a new outgoing call, attributes are provided to indicate [[Toolpack_Application:toolpack_engine|toolpack_engine]] which NAP to make the call to (which also defines the signaling protocol), which calling/called numbers to use, etc.

From the C++ point of view, the CTBCMCLeg contains most of the APIs require to manipulate call legs, while the ''CTBCAFCallLeg'' class is providing the interface to attach call legs to a parent ''CTBCAFCallFlow'' object

=== CAF Mixer (''CTBCAFMixer''): ===
CAF Call Legs (''CTBCAFCallLeg'') have a built-in function to join with another leg, making audio flow from one leg to the other directly.

However, when it is required to mix audio from multiple call legs or sources (building conferences for example), then the ''CTBCAFMixer'' object is used.

The ''CTBCAFMixer'' (based on CTBCMCMixer base class) is the representation of a DSP resource used to mix audio from different sources (call legs, stream server, or other mixers).

From the C++ point of view, the CTBCMCMixer contains most of the APIs require to manipulate mixers, while the ''CTBCAFMixer'' class is providing the interface to attach mixers to a parent ''CTBCAFCallFlow'' object.

The ''CTBCAFMixer'' object can be used for:
* Conferences
* Background music playing on a call
* Recording both call legs of a call into one mixed audio file
* etc.

See more information on mixers here: [[http://docs.telcobridges.com/mediawiki/index.php/AudioMixers Audio Mixers]]

=== CAF Call Flow (''CTBCAFCallFlow''): ===

The ''CTBCAFCallFlow'' base class contains one or multiple ''CTBCAFCallLeg'' objects, and optionally one or multiple ''CTBCAFMixer'' objects. The role of the ''CTBCAFCallFlow'' object is to implement a call flow that involves actions on legs and mixers that have a relation with each other.

=== CAF Call Bridge (''CTBCAFBridge'', based on ''CTBCAFCallFlow''): ===

A typical implementation of a call flow is the ''CTBCAFBridge'' class (based on the ''CTBCAFCallFlow'' base class). This class is designed to
- Receive an incoming call
- Make a corresponding outgoing call
- Join them together
- Terminate both of them when one leg hangups.

=== CAF Call Behavior (''CTBCAFCallBehavior''): ===

Behaviors ''CTBCAFCallBehavior'' can be attached to a call flow (''CTBCAFCallFlow''). Their role is to modify the basic call flow, decorating it with optional functionality (CDR logging, FAX detection, Ring tone playback, etc.)

In order to implement their functionality, behavior objects, like their parent call flow object, receive events from all call legs and mixers of the call flow. They can also manipulate call legs and mixers.

== Performing actions on call legs and mixers ==
=== Actions on call legs ===
The call flow (and it's behaviors) can perform various actions on each of it's call legs. Here is a list of the actions available on the CTBCAFCallLeg objects (please refer to the header file '''CTBCMCLeg.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Call_Leg_Actions Actions on CTBCAFCallLeg]]

=== Actions on mixers ===
The call flow (and it's behaviors) can perform various actions on each of it's mixers. Here is a list of the actions available on the CTBCAFMixer objects (please refer to the header file '''CTBCMCMixer.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Mixer_Actions Actions on CTBCAFMixer]]

== Receiving events from call legs and mixers ==

[[File:CAFCallFlow_event.png|400px]]

=== Events received from call legs by the CTBCAFCallFlow object ===

The call flow object (as well as all it's behaviors) receive the following events from it's call legs (please refer to the header file '''ITBCAFCallFlow.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Call_Leg_Events Call flow events from it's call legs]]

=== Events received from mixers by the CTBCAFCallFlow object ===

The call flow object (as well as all it's behaviors) receive the following events from it's mixers (please refer to the header file '''ITBCAFCallFlowMixer.hpp''' for more information on each of these functions):

[[http://docs.telcobridges.com/mediawiki/index.php/CAF:_Caf_Mixer_Events Call flow events from it's mixers]]

=== Events behavior chain ===
All the events describe above are called consecutively on each behavior attached to the call flow, and ultimately, called on the call flow itself.

Each behavior in the chain can
* Pass the event to the next behavior in the chain
* Consume the event so other behaviors in the chain and the call flow are unaware that this event occurred

The ''CTBCAFCallBehavior'' default implementation is to forward the event to the next event in the chain.

When you implement your own behaviors, you can override only a couple of events (like OnCallLegAnswered() for example) to perform specific tasks, and leave all other events to the base class, so you don't have to write a lot of code to create a new behavior.

== Example call flows ==

Example call flow where an incoming call is received, accepted, then terminated from network side:

[[File:example_call_flow.png|500px]]

Example conference call flow with two incoming call legs, one outgoing call leg, and one audio mixer:

[[File:example_call_flow_conf.png|400px]]

== Creating the ''CTBCAFCallFlow'' object, its legs and mixers ==
Steps to create a new call flow are:
* Create a new object (using a class derived from ''CTBCAFCallFlow'' class)
* Attach behaviors to the call flow
* Add attributes of incoming and outgoing legs to create
* Add attributes for mixers to create
* Tell the call flow object to initialize itself, and create the call legs and mixers as requested
* Join legs together, join legs to mixers, or join mixers to other mixers

Here is a (over-simplified) example:
ITBCAFCallFlow* pCallFlow;
ITBCAFCallFlow* pParentCallOrBehavior;

// Create the call flow object (here using the CTBCAFBridge class, based on CTBCAFCallFlow)
pCallFlow = tbnew CTBCAFBridge( 0, this);

// Optionally, attach behaviors
pParentCallOrBehavior = pCallFlow;
pParentCallOrBehavior = tbnew CTBCAFCallBehaviorBusyTone( pParentCallOrBehavior, ... );
pParentCallOrBehavior = tbnew CTBCAFCallBehaviorBridgeCdr( pParentCallOrBehavior, ... );

// Add an incoming call leg to that call flow (CTBCAFCallLeg object will get created based on provided attributes)
pCallFlow->AddIncoming( in_LegId, ptrIncomingLegAttribute, ptrIncomingLegProtocolAttributes, ptrAcceptCallProtAttribute );

// Add an outgoing call leg
pCallFlow->AddOutgoing( ptrOutgoingLegAttribute, ptrOutgoingLegProtocolAttributes );

// Create an audio mixer
pCallFlow->MixerCreate( ptrMixerAttribute );

// Initialize the call (this actually creates the call legs)
pCallFlow->InitCall( &pCallFlow );

During the call flow (upon reception of an event on a call leg for example), more actions can be taken. For example:
MyCallFlowOrBehavior::OnCallLegAnswered()
{
// Ask to detect FAX tones
CTBCMC_EVENT_ATTRIBUTE Event;
Event.AddToneString( "telcofax/eof" );
GetIncomingActiveLeg()->StartEventCollection( in_EventMask, NULL, TBX_FALSE /* Don't suppress tones */ );

// Call base class to forward event to next behavior
CTBCAFBehavior::OnCallLegAnswered();
}

During the call flow (upon reception of an event on a mixer for example), more actions can be taken. For example:
MyCallFlowOrBehavior::OnMixerCreated()
{
// Immediately add call legs to the mixer
GetFirstMixer()->MixerJoin( GetIncomingActiveLeg().Get(), ptrJoinAttributes );
GetFirstMixer()->MixerJoin( GetOutgoingActiveLeg().Get(), ptrJoinAttributes );

// Answer the incoming leg
GetIncomingActiveLeg()->AnswerCall();

// Play background music on the conference
GetFirstMixer()->MixerPlayStream( PlayAttr );

// Call base class to forward event to next behavior
CTBCAFBehavior::OnMixerCreated();
}

For a more complete code example, please refer to the simple_call application, in file '''CTBS2GWSimpleCall.cpp''', or here:

[[CAF:_Leg_Creation_Samples#Bridging_an_Incoming_Call_Leg_.28using_CTBCAFBridge_.29|CTBCAFBridge creation]]

=== Constructing leg attributes ===
==== Incoming call leg attributes ====
To create the incoming call leg, the following information is required:
* Smart pointer to incoming call leg attributes, received from [[Toolpack_Application:toolpack_engine|toolpack_engine]] through ''OnCallLegPresent''().
ptrIncomingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE( *(in_CallLegAttribute.GetCallLegAttribute()) );
* Smart pointer to incoming call leg protocol attributes, received from [[Toolpack_Application:toolpack_engine|toolpack_engine]] through ''OnCallLegPresent''().
ptrIncomingLegProtocolAttributes = tbnew CTBCMC_PROTOCOL_ATTRIBUTE( in_ProtocolAttribute, TBX_TRUE );
* Smart pointer to empty protocol attributes that Behaviors can fill, and that will be used when accepting the call

==== Outgoing call leg attributes ====
To create the outgoing call leg, the following information is required:
* Smart pointer to outgoing call leg attributes to use to create the call, generally derived from the incoming call attributes
ptrOutgoingLegAttribute = tbnew CTBCMC_CALL_LEG_ATTRIBUTE();
ptrOutgoingLegAttribute->CopyLegAttributeFrom( *(ptrIncomingLegAttribute.Get()) );
* Smart pointer to empty protocol attributes that Behaviors can fill, and that will be used when creating the outgoing call (SIP invite, ISUP IAM, ISDN Setup, etc.)

==== Mixer attributes ====
To create the mixer, the following information is required:
* Smart pointer to mixer attributes to use to create the mixer
ptrMixerAttribute = tbnew CTBCMC_MIXER_ATTRIBUTE();
ptrMixerAttribute->SomeParameter = SomeValue;

=== Call leg initialization callbacks ===
All behaviors attached to the call flow will be notified of the creation of new call legs through callback '''OnInitIncomingCallLeg()''' or '''OnInitOutgoingCallLeg()'''.

==== '''OnInitIncomingCallLeg()''' ====
In this callback, each behavior may consult the incoming call attributes or protocol attributes, and can modify the protocol attributes that will be used to accept the call (actually providing protocol-specific information, like SS7 IEs, or SIP headers).

==== '''OnInitOutgoingCallLeg()''' ====
In this callback, each behavior can modify the protocol attributes that will be used to create the call (actually providing protocol-specific information, like SS7 IEs, or SIP headers that will be used in the initial signaling message, as SIP Invite, ISUP IAM, or ISDN Setup).

==== ''OnMixerInit()'' ====
In this callback, each behavior can modify the mixer attributes that will be used to create the mixer.

== Destruction the ''CTBCAFCallFlow'' object, its legs and mixers ==
=== Self-destructing call legs, mixers, behaviors, and call flow ===
The ''CTBCAFCallFlow'' object contains smart pointers to it's call legs and mixers. Destruction of these will thus occur automatically when the last smart pointer reference is removed (that last reference can be either the smart pointer reference in the CTBCAFCallFlow object, or anywhere else in the application).

Upon destruction of the last call leg or last mixer (when no more leg or mixer are in the call flow), the objects based on ''CTBCAFCallFlow'' or ''CTBCAFCallBehavior'' will delete themselves automatically, by calling the attached "free listener" (that was provided in the constructor of the call flow object).

=== Call leg termination callbacks and actions ===
==== '''OnCallLegTerminatingIndication()''' ====
This callback means that [[Toolpack_Application:toolpack_engine|toolpack_engine]] has received a termination request from a call leg (SIP Bye, ISUP REL, for example).
A typical use of that event is to call '''TerminateCall()''' on both incoming and outgoing legs of a call flow, to hangup both sides.

==== '''TerminateCall()''' ====
This function is used for the application to request the termination of a call leg.
It is also used to confirm that the application is done with a call leg, after '''OnCallLegTerminatingIndication()''' event was received (in that case, '''TerminateCall()''' can be called within the event callback, or later if the application has some more asynchronous cleanup to do).

==== '''OnCallLegTerminated()''' ====
This callback confirms that [[Toolpack_Application:toolpack_engine|toolpack_engine]] has finished closing the data path and signaling for this call leg.
It will also be called when a leg is destroyed because of a lost of communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] (restart, network failure, crash).

==== '''FreeLeg()''' ====
It is MANDATORY that this function is called for each call leg after '''OnCallLegTerminated()'''.

It's up to the application to call the function immediately (within '''OnCallLegTerminated()''' for example) or later after doing some more job (like asynchronous database updates, for example)

==== '''OnLegFreed()''' ====
This callback confirms that the leg is being freed.

It's the last chance for a call flow or a behavior to release things related to a call leg, like canceling timers for example.

*'''Important note:''' Behaviors that implement that function MUST, as the LAST line of their function, call the base class' '''CTBCAFCallBehavior::OnLegFreed'''. Not calling base class' function will cause the call to leak. Calling that before the last line of the function will cause crash, as the Behavior object could destroy itself within that function upon destruction of the last leg/mixer of the call.

=== Mixer termination callbacks and actions ===

==== '''MixerTerminate()''' ====
This function is used for the application to request the termination of a mixer.

==== '''OnMixerTerminated()''' ====
This callback confirms that [[Toolpack_Application:toolpack_engine|toolpack_engine]] has finished destroying resources related to this mixer.
It will also be called when a leg is destroyed because of a lost of communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] (restart, network failure, crash).

==== '''FreeMixer()''' ====
It is MANDATORY that this function is called for each mixer after '''OnMixerTerminated()'''.

It's up to the application to call the function immediately (within '''OnMixerTerminated()''' for example) or later after doing some more job (like asynchronous database updates, for example)

==== '''OnMixerFreed()''' ====
This callback confirms that the mixer is being freed.

It's the last chance for a call flow or a behavior to release things related to a mixer, like canceling timers for example.

*'''Important note:''' Behaviors that implement that function MUST, as the LAST line of their function, call the base class' '''CTBCAFCallBehavior::OnMixerFreed()'''. Not calling base class' function will cause the mixer and call to leak. Calling that before the last line of the function will cause crash, as the Behavior object could destroy itself within that function upon destruction of the last leg/mixer of the call.

== Re-synchronizing with [[Toolpack_Application:toolpack_engine|toolpack_engine]] ==
There are a couple of cases where a CAF application needs to re-synchronize with [[Toolpack_Application:toolpack_engine|toolpack_engine]]:
* The CAF application was restarted
* The [[Toolpack_Application:toolpack_engine|toolpack_engine]] was restarted
* Network connection between CAF application and [[Toolpack_Application:toolpack_engine|toolpack_engine]] was momentarily down

When communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] is lost, all call legs and mixers are notified of the disconnection through '''OnSyncLost()''' and '''OnMixerSyncLost()'''. However, they are not immediately destroyed. They are kept in the CAF framework for 10 seconds waiting for the engine (or backup engine) to reconnect. After 10 seconds, legs and mixers are terminated in the CAF framwork. This does not mean, however, that they are terminated in the toolpack_engine. Upon reconnection with engine, legs and mixers still present in the engine will be sent back to the CAF application through '''OnCallLegSync()''' and '''OnMixerSync()'''.

Possible scenarios for a leg are thus:
* Engine is reconnected within 10 seconds:
** Some legs/mixers no more exist in [[Toolpack_Application:toolpack_engine|toolpack_engine]], and will be notified by '''OnCallLegTerminated()''' / '''OnMixerTerminated()'''.
** Legs/mixers that are still valid will be untouched (though they are notified with '''OnLegSync()''' / '''OnLinkSync()''' / '''OnMixerSync()''', for convenience)
* Engine has been disconnected for more than 10 seconds:
** CAF framework will terminate call legs/mixers, and notify them through '''OnCallLegTerminated()''' / '''OnMixerTerminated()'''
** Later, when engine is reconnected after a >10:
*** Call legs/mixers that are still available in [[Toolpack_Application:toolpack_engine|toolpack_engine]] are pushed back to CAF application through '''OnCallLegSync()''', '''OnLinkSync()''' and '''OnMixerSync()'''
*** CAF application can refuse them, or re-build it's legs/mixers/call flow contexts to resume operation on these calls

=== Re-synchronization sequence ===

In all the cases above, the re-synchronization mechanism involves the following steps:

=> Communication lost with [[Toolpack_Application:toolpack_engine|toolpack_engine]]
* '''OnCmcLibNotReady()''' (CAF application callback): Indicates that communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] has been interrupted. It will not be possible to perform actions (play file, ask for digit collection) on call legs/mixers until [[Toolpack_Application:toolpack_engine|toolpack_engine]] is ready again ('''OnCmcLibReady''').
* '''OnSyncLost()''' (CAF call flow and behavior callback): Same meaning as '''OnCmcLibNotReady()''', passed to each call leg contexts individually.
* '''OnMixerSyncLost()''' (CAF call flow and behavior callback): Same meaning as '''OnCmcLibNotReady()''', passed to each call mixer contexts individually.

=> Communication re-established with [[Toolpack_Application:toolpack_engine|toolpack_engine]]
* '''OnCallLegSync()''' (CAF application callback): Indicates that the [[Toolpack_Application:toolpack_engine|toolpack_engine]] knows about a call leg that does not exist in the CAF application.
* '''OnLinkSync()''' (CAF application callback): Indicates that the [[Toolpack_Application:toolpack_engine|toolpack_engine]] knows about a link between two call legs (legs are joined, audio is flowing from one to the other directly).
* '''OnMixerSync()''' (CAF application callback): Indicates that the [[Toolpack_Application:toolpack_engine|toolpack_engine]] knows about a mixer that does not exist in the CAF application.
* '''OnCmcLibReady()''' (CAF application callback): Indicates that communication with [[Toolpack_Application:toolpack_engine|toolpack_engine]] has been restored, and that all legs, links and mixers have been re-synchronized
* '''OnSyncDone()''' (CAF call flow and behavior callback): Indicates to a call leg (that previously received '''OnSyncLost()''') that it is still present in the [[Toolpack_Application:toolpack_engine|toolpack_engine]], and ready to be controlled again.
* '''OnMixerSyncDone()''' (CAF call flow and behavior callback): Indicates to a mixer (that previously received '''OnMixerSyncLost()''') that it is still present in the [[Toolpack_Application:toolpack_engine|toolpack_engine]], and ready to be controlled again.
* '''OnCallLegTerminated()''' (CAF call flow and behavior callback): When this function is called with Reason ''TBCMC_CALL_REASON_CODE_TOOLPACK_SYNC_DROP'', it indicates that this call leg is no more present in [[Toolpack_Application:toolpack_engine|toolpack_engine]] after re-synchronizing, and must thus be freed in the CAF application too.
* '''OnMixerTerminated()''' (CAF call flow and behavior callback): When this function is called, it indicates that this mixer is no more present in [[Toolpack_Application:toolpack_engine|toolpack_engine]] after re-synchronizing, and must thus be freed in the CAF application too.

=== Rebuilding new legs, mixers and call flow objects ===
When an application receives '''OnCallLegSync()''', it must take the decision to either keep the call leg (create a CTBCAFCallLeg object) or refuse it (tell [[Toolpack_Application:toolpack_engine|toolpack_engine]] that we don't want to re-synchronize it, and that it must be terminated).

When an application receives '''OnMixerSync()''', it must take the decision to either keep the mixer (create a CTBCAFMixer object) or refuse it (tell [[Toolpack_Application:toolpack_engine|toolpack_engine]] that we don't want to re-synchronize it, and that it must be terminated).

==== Dropping re-synchronized legs ====
The static helper function '''CTBCMCLeg::RefuseLeg()''' has been provided by the class ''CTBCMCLeg'' to terminate re-synchronized call legs without having to worry about creating any object. An application that wants to refuse a re-synchronized leg should call it.

==== Dropping re-synchronized links ====
The static helper function '''CTBCMCLeg::RefuseLink()''' has been provided by the class ''CTBCMCLeg'' to terminate re-synchronized links without having to worry about creating any object. An application that wants to refuse a re-synchronized link should call it.

==== Dropping re-synchronized mixers ====
The static helper function '''CTBCMCMixer::RefuseMixer()''' has been provided by the class ''CTBCMCMixer'' to terminate re-synchronized mixer without having to worry about creating any object. An application that wants to refuse a re-synchronized mixer should call it.

==== Keeping re-synchronized legs that are part of a link or a mixer ====
The helper class ''CTBCAFCallLegResync'' is provided to help creating CTBCAFCallLeg objects for re-synchronized legs, and later retrieve them and attach them to a CTBCAFCallFlow parent, upon '''OnLinkSync()''' or '''OnMixerSync()''':

Upon '''OnLegSync()''', legs should be allocated inside the class ''CTBCAFCallLegResync'' using function '''AllocateCallLeg()'''. Legs don't yet need to be attached to a parent CTBCAFCallFlow, that's normally done upon '''OnLinkSync()''' or '''OnMixerSync()'''.

Upon '''OnLinkSync()''', the LegId of the two joined call legs are provided. Both legs must be retrieved from the ''CTBCAFCallLegResync'' (using functions '''FindCallLeg()''' and '''RemoveCallLeg()'''), then added to a CTBCAFCallFlow object that will resume the call flow of these two joined call legs.

Upon '''OnMixerSync()''', the LegId of all legs in that mixer (along with Join Attributes) are provided. A new CTBCAFMixer object must be allocated, and all call legs from that mixer must be retrieved from the ''CTBCAFCallLegResync'' object (using functions '''FindCallLeg()''' and '''RemoveCallLeg()'''). The allocated mixer and found legs must then be assigned to a CTBCAFCallFlow object that will resume the call flow.

Finally, upon '''OnCmcLibReady()''', the application can destroy the CTBCAFCallLegResync object, which will take care of refusing (dropping) all call legs that it still references (that have not been removed by '''CTBCAFCallLegResync::RemoveCallLeg''')

Simplified example code:

TBX_VOID CTBMyApp::OnCallLegSync
(
IN TBCMC_LEG_ID in_LegId,
IN CTBCMC_CALL_LEG_ATTRIBUTE_COMMON& in_CallLegAttribute
)
{
// Upon first re-synchronized leg, allocate utility class to contain re-synchronized call legs
if( !mpCallLegResync )
{
mpCallLegResync = new TBCAF::CTBCAFCallLegResync( MY_APP_MAX_CALLS );
}

// Re-create a CTBCAFCallLeg object for this re-synchronized leg
mpCallLegResync->AllocateCallLeg
(
NULL, // Not yet bound to a parent call flow
in_LegId, // Use the leg Id of this re-synchronized call leg
in_CallLegAttribute, // Store the attributes of this re-synchronized call leg
this, // Until it has a parent call flow, set ourself as
TBCMC_MSG_CALL_LEG_STATE_ACTIVE // Consider this call leg as active (answered)
// since only active calls can be re-synchronized
);
}

TBX_VOID CTBMyApp::OnLinkSync
(
IN TBCMC_LINK_ID in_LinkId,
IN TBCMC_LEG_ID in_SrcLegId,
IN TBCMC_LEG_ID in_DstLegId,
IN CTBCMC_JOIN_ATTRIBUTE & in_JoinAttribute
)
{
// Find both call legs in the re-sync utility mpCallLegResync
PTRCTBCAFCallLeg ptrSrcLeg = mpCallLegResync->RemoveCallLeg( in_SrcLegId );
PTRCTBCAFCallLeg ptrDstLeg = mpCallLegResync->RemoveCallLeg( in_DstLegId );

// Allocate a new call flow
PITBCAFCallFlow pMyCallFlow = tbnew CTBCAFMyCallFlow
(
this, // Set current application as free listener for my call flow
in_LinkId, // Id of the link between these two joined legs
in_JoinAttribute, // Attributes of the link between these two joined legs
ptrSrcLeg,
ptrDstLeg
);

// Re-attach behaviors to this call flow
pMyCallFlow = tbnew CTBCAFMyFirstBehavior( pMyCallFlow, ... );
pMyCallFlow = tbnew CTBCAFMySecondBehavior( pMyCallFlow, ... );
}

TBX_VOID CTBMyApp::OnCmcLibReady()
{
// Free all single call legs that remain
// Deleting mpCallLegResync will automatically reject legs still in that object
delete mpCallLegResync;
mpCallLegResync = NULL;
}

TBX_VOID CTBMyApp::OnCmcLibNotReady()
{
// Free all single call legs that remain
// Deleting mpCallLegResync will automatically reject legs still in that object
delete mpCallLegResync;
mpCallLegResync = NULL;
}

For a more complete code example, please refer to the simple_call application, in file '''CTBS2GWSimpleCall.cpp'''.

Toolpack:Create an ISUP Circuit

2012-01-10T15:49:37Z

Jasmin Letendre:

The TB640_MSG_ID_SS7_ISUP_OP_CIRCUIT_ALLOC (request/response) message is used to initialize (create) an instance representing one or many ISUP circuits. Since a circuit represents a physical voice (or data) channel between this SS7 node and a remote SS7 node, it is likely that a system will have thousands of circuits created.

As mentioned before, a message TB640_MSG_SS7_ISUP_OP_CIRCUIT_ALLOC can instantiate more than one circuit at the same time. This is to help the host application to reduce the number of messages to send toward the TB640 when it wants to allocate thousand of circuits. The parameter un32NbCircuitAlloc tells the TB640 the number of consecutive circuit to allocate. All configuration parameters for all circuits will be identical with the exception of un32CircuitId (which will be incremented by one for each circuit instance) and un16Cic (which will also be incremented by one for each circuit instance). See configuration parameter description below for a better understanding of those two parameters.

'''NOTE:''' During multiple circuit instantiation, only the un32CircuitId and un16Cic will differ from the configuration from one circuit to the other.

----

The following enumeration lists the different configuration parameters and their description. Unless specifically noted, all parameters are not reconfigurable:

*The '''Circuit ID''' parameter is a 32-bit value, assigned by the host application, that is used as an opaque handle by the ISUP layer to refer to a specific circuit part of a specific interface which is in turn part of a specific userpart. The only two requirements are for this value to be unique for the ISUP overall stack and to not be equal to zero.

'''NOTE:''' The value of Circuit ID cannot be zero

----

*The '''ISUP interface''' parameter is the handle provided by the TB640_MSG_SS7_ISUP_OP_INTERFACE_ALLOC message. It is used to specify within which interface this/these circuit instance(s) is/are to be created.
*The '''CIC''' parameter is the circuit identification code that will be used for incoming and outgoing calls. Allowable values are protocol signaling standard-specific. For example, ITU-T allows 12bits CIC values and ANSI allows 14bits CIC values. Both standards have spare bits to extend this range to 16 bits but, according to specifications, can do so only with a common agreement/understanding over the SS7 network.

----

*The '''Control type''' parameter is used to determine which side is controlling call. This is required when handling special cases such as call collisions or dual seizure. This configuration parameter needs to be understood (i.e. properly configured) by both ends of the circuits. Allowed values are:

{| class="wikitable" border="1"
! width="150" style="background:#efefef;" |Control type
! width="350" style="background:#efefef;" |Description
|-
| Incoming|| Circuit is always controlled by remote end for incoming calls. Only incoming calls are accepted on the circuit. Outgoing call attempts will be refused.
|-
| Outgoing|| Circuit always controls the remote end for outgoing calls. Only outgoing calls are accepted on the circuit. Incoming call attempts will be refused.
|-
| Bothway|| For call collision, the exchange with the higher signalling point code will control even-numbered CIC and the other exchange will control odd-numbered CIC.

Both incoming and outgoing calls are allowed on the circuit.
|-
| Controlled|| Circuit is always controlled by remote end for all calls during a collision. Both incoming and outgoing calls are allowed on the circuit.
|-
| Controlling|| Circuit is always controlled by the local stack during a collision. Both incoming and outgoing calls are allowed on the circuit.
|}

----

*The '''Outgoing continuity check''' parameter is used to instruct the ISUP layer to issue a continuity check request for outgoing calls on that circuit

----

*The '''Slot identification''' parameter contains the slot ID within a trunk group. This field is read while filling the CAM parameter for sending GRS from the ISUP layer. Moreover, the ISUP layer uses it to validate a CAM parameter with it receives a message with a CAM present. It is only used in ANSI95, ITU97 and ETSI variants. The format of the slot ID is shown below:

{| class="wikitable" border="1"
! width="150" style="background:#efefef;" |Slot identification
! width="350" style="background:#efefef;" |Description
|-
| Normal|| MTP2 layer is used in conjunction with an above MTP3 layer
|-
| HSL|| MTP2 layer high speed link is used in conjunction with an above MTP3 layer
|}

7

6

5

4

3

2

1

0

Spare

MRC supported ?

MRC skipped ?

Timeslot ID

{| class="wikitable" border="1"
! width="150" style="background:#efefef;" |Slot identification
! width="350" style="background:#efefef;" |Description
|-
| Bits 0-4|| Represents the 0-31 (E1) or 0-23 (T1) timeslot within the trunk group. Should configure the Slot ID of the first position circuit in a trunk group as 0.
|-
| Bit 5|| Tells whether or not the circuit used for contiguous multi-rate calls or is skipped. Can only be used when the checking of starting circuit is done in accordance with Q.763 Table 3 is not required.
|-
| Bit 6|| Tells whether or not the circuit supporting contiguous multi-rate calls.
|}

----

*The '''Dual seizure control for multi-rate''' parameter is used to indicate the controlling side for CIC for the entire trunk group, where at least one of the calls is a non-single rate connection. This field is used only for ANSI95, ITU97 and ETSI variants.
*The '''Non-SS7 connection''' parameter is used to indicate if this circuit is connected to a non-SS7 network. If set, the outgoing trunk group address provided by the parameter szOutTrkGrpNb is used. This is also used to generate the EXIT message for outgoing calls. The timer tEx (un32ExTimer parameter from the ISUP userpart configuration) is started when the IAM is sent. Upon timer expiry, an EXIT message is sent. This field is used only for ANSI88, ANSI92, ANSI95 and Telcordia variants.

----

*The '''Options''' parameter is used to active per-circuit options. Allowed values are:

Table SEQ Table \* ARABIC 45 - ISUP circuit options

Circuit options

Description

ANSI International Used to support international calls in addition to national (default). Used for ANSI networks only.

Use Confusion Message Activates the use of the CONFUSION message.

Circuit Type Unknown Indicates circuit group carrier information.

Circuit Type Analog

Circuit Type Digital

Circuit Type Analog Digital

Alarm Carrier Unknown Indicates the information of the alarm carrier.

Alarm Carrier Software

Alarm Carrier Hardware

Continuity Check Unknown Indicates the continuity check requirements. These options can be reconfigured.

Continuity Check None

Continuity Check Statistical

Continuity Check Per Call

----

*The '''First CIC''' parameter indicates the first circuit identification code in the circuit group. This field is used only for ANSI88, ANSI92, ANSI95 and Telcordia. When using one of those variants and receiving (or sending) a group command with a range of 0 (within the “range and status” IE), the ISUP layer uses un16FirstCic and un16NbCircuitInGroup to know which CICs are affected by the command. Refer to section 6.3.3.1 08D0C9EA79F9BACE118C8200AA004BA90B0200000008000 for more information.
*The '''Number of circuits in group''' parameter (un16NbCircuitInGroup) indicates total number of CIC part of the circuit group. This field is used only for ANSI88, ANSI92, ANSI95 and Telcordia. When using one of those variants and receiving (or sending) a group command with a range of 0 (within the “range and status” IE), the ISUP layer uses un16FirstCic and un16NbCircuitInGroup to know which CICs are affected by the command. Refer to section 6.3.3.1 08D0C9EA79F9BACE118C8200AA004BA90B020 for more information.
*The '''Outgoing trunk group nb''' parameter is used to store the outgoing trunk group number to be used in the EXIT messages for ANSI88, ANSI92, ANSI95 and Telcordia variants for non-SS7 circuits. For SS7 circuits, this field is used to store the circuit ID name for the Telcordia variant.
*The '''Circuit identification name''' parameter is used to store the circuit identification name expected in the CVR message. This field is only used for ANSI88, ANSI92, ANSI95 and Telcordia to validate the circuit identification name upon validation of incoming CRV messages. Refer to the ANSI specification for the format of this field.
*The '''Location ID''' parameter is contains the common language name to identify the switching office by town, state and building subdivision. This field is only used for ANSI88, ANSI92 and Telcordia variants.

----

*The '''Timer configuration''' parameters are defined as follows; all values must be expressed in milliseconds:

{| class="wikitable" border="1"
! width="150" style="background:#efefef;" |Connection mode
! width="350" style="background:#efefef;" |Description
|-
| T3 Timer|| OVERLOAD message received. Terminated normally after 2 minutes.
|-
| T12 Timer|| BLOCKING message sent. Terminated normally when BLOCKING ACKNOWLEDGEMENT is received. Typical values are 15 to 60 seconds.
|-
| T13 Timer|| INITIAL BLOCKING message sent. Terminated normally when BLOCKING ACKNOWLEDGMENT is received. Typical values are 5 to 15 minutes.
|-
| T14 Timer|| UNBLOCKING message sent. Terminated normally when UNBLOCKING ACKNOWLEDGMENT is received. Typical values are 15 to 60 seconds.
|-
| T15 Timer|| INITIAL UNBLOCKING message sent. Terminated normally when UNBLOCKING ACKNOWLEDGMENT is received. Typical values are 5 to 15 minutes.
|-
| T16 Timer|| RESET message sent. Terminated normally when RELEASE COMPLETE is received. Typical values are 15 to 60 seconds.
|-
| T17 Timer|| INITIAL RESET message sent. Terminated normally when RELEASE COMPLETE is received. Typical values are 5 to 15 minutes.
|-
| Val Timer|| Circuit validation timer for ANSI88, ANSI92, ANSI95 and Telcordia. Typical value is 10 seconds.
|}

'''NOTE:''' The following timers are not required for the UK: T3.

----

The following enumeration lists the different response parameters and their description:
*The '''Number of allocated circuit response''' parameter contains the number of circuits that were successfully allocated. If everything went well, this number should be equal to un32NbCircuitAlloc from the request part of the message (see above).
*The '''Number of non-allocated circuit response''' parameter contains the number of unsuccessful allocation attempts. If this number is non-zero, the host application must consider that the value for Number of Circuit Allocated was allocated. Since circuits are allocated sequentially in case of multiple allocations, the host application can assume that the first value for Number of Circuit Allocated was allocated.

'''NOTE:''' un32NbCircuitAllocated + un32NbCircuitNotAllocated = un32NbCircuitAlloc

'''NOTE:''' As specified in section 6.1.3 08D0C9EA79F9BACE118C8200AA004BA90B0, an ISUP circuit can only be part of a single ISUP interface. On the other hand, multiple circuits can be attached to the same interface instance. Those circuits represent the voice channels available between the local SS7 node and the remote SS7 node.

ISDN

2011-11-30T18:58:55Z

Jasmin Letendre: Fixed link to Tutorial Guide for V2.5

Integrated Systems Digital Network (ISDN) is a circuit-switched telephone system that integrated voice and data on the same lines.

== TelcoBridges and ISDN ==

Tmedia and Tdev systems can be configured to provide an ISDN signalling stack on the trunks of one or more units to meet system configuration requirements. ISDN signaling stacks are signaling resources that are assigned to a specific line of the Tmedia or Tdev unit. Based on the [http://en.wikipedia.org/wiki/Q.931 Q.931] switch variant that will be used by the system, a selection of ISDN variants are available. For each line service requiring ISDN signaling, an ISDN signaling stack is created with its own distinct signaling variant.

[[Image:ISDN signaling stacks.jpg]]

Note: The trunks of each Tmedia or Tdev unit can be configured to have their own ISDN signaling stack.

== Related actions ==

'''Refer to the appropriate Toolpack release:'''

*[[Web Portal Tutorial Guide v2.2#ISDN_Signaling|Toolpack v2.2: ISDN Signaling]]
*[[Web Portal Tutorial Guide v2.3#ISDN_Signaling|Toolpack v2.3: ISDN Signaling]]
*[[Web Portal Tutorial Guide v2.4#ISDN_Signaling|Toolpack v2.4: ISDN Signaling]]
*[[Web Portal Tutorial Guide v2.5#ISDN-SIP_Gateway_Configuration|Toolpack v2.5: ISDN Signaling]]

== References ==

*[http://en.wikipedia.org/wiki/Integrated_Services_Digital_Network Wikipedia article]
*[[ISDN:Specification|Supported ISDN standards and variants]]

[[Category:Glossary]]

Toolpack prerequisite CentOS5 A

2011-08-10T18:05:10Z

Jasmin Letendre: Fixed typo in name of the aio library

This page shows the Toolpack 2-5 prerequisites for CentOS 5.5.


''WARNING'': The host MUST have CentOS 5.5 installed. If you don't want to update your host, please follow the [[Toolpack_prerequisite_CentOS5_2-5_manual | manual procedure]] instead.



''WARNING'': If you followed the [[Toolpack_prerequisite_CentOS5_2-5_manual | manual procedure]] on the system before, you MUST NOT use the steps on this page before doing a cleanup of the previously installed files. You should ask Telcobridges support for help with the cleanup.



''WARNING'': This procedure requires internet access


== CentOS update ==

Update your system to CentOS 5.5

yum update

== TelcoBridges repository ==

Add TelcoBridges repository file

vim /etc/yum.repos.d/TB-Base.repo

Paste the following information in that file:

# TelcoBridges-Base.repo
#
# This repository is using TelcoBridges frozen version of CentOS
# to help client installing the required version of the
# applications required to run Toolpack
#

[tb-base]
name=TelcoBridges-$releasever - Base
baseurl=http://repo.telcobridges.com/centos/5.5/os/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5

#released updates
[tb-updates]
name=TelcoBridges-$releasever - Updates
baseurl=http://repo.telcobridges.com/centos/5.5/updates/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5-tb

Get TelcoBridges repository key

cd /etc/pki/rpm-gpg/
wget http://repo.telcobridges.com/centos/RPM-GPG-KEY-CentOS-5-tb

== Install Toolpack Prerequisites ==

When asked to 'Importing GPG key', answer yes.

yum groupinstall Toolpack-Prerequisites

== Configure Toolpack Prerequisites ==
=== Configure ODBC ===

vim /etc/odbcinst.ini

Remove the '#' in front of each lines of the [MySQL] section
Modify the 'Driver' line to set the correct driver

Example for 32 bits system:

[MySQL]
Description = ODBC for MySQL
Driver = /usr/lib/libmyodbc5.so
Setup = /usr/lib/libodbcmyS.so
FileUsage = 1

Example for 64 bits system:

[MySQL]
Description = ODBC for MySQL
Driver = /usr/lib64/libmyodbc5.so
Setup = /usr/lib/libodbcmyS.so
FileUsage = 1

=== Configure MySQL ===

vim /etc/my.cnf

Add 2 new variables in the file under the [mysqld] section:
*log-bin
*server-id=''[UniqueId]''

The server-id needs to be a non-zero unique value (do not use 0). If you use the host redundancy feature, the value needs to be different on each host .

Add max_allowed_packet to increase the maximum size of binary blobs in the database.
Make sure it is in the [mysqld] section AND [mysqldump] section
max_allowed_packet = 200MB

Example:
[mysqld]
datadir=/var/lib/mysql
socket=/var/lib/mysql/mysql.sock
user=mysql
log-bin
server-id=5876
max_allowed_packet = 200MB
# Default to using old password format for compatibility with mysql 3.x
# clients (those using the mysqlclient10 compatibility package).
old_passwords=1

[mysqldump]
max_allowed_packet = 200MB

=== Start MySQL ===

service mysqld start

=== Configure MySQL Users ===

*Set password for the root user to 'tbdbpw' (TelcoBridges recommends that you set your own password for root)
*Enable root connection from localhost only
*Create a tbdb user (required by Toolpack)
*Remove anonymous connection

Example:

/usr/bin/mysqladmin -u root password tbdbpw

mysql -uroot -ptbdbpw
DELETE FROM mysql.user WHERE !(Host = 'localhost' AND User = 'root');
FLUSH PRIVILEGES;
CREATE USER 'tbdb'@'%' IDENTIFIED BY 'tbdbpw';
GRANT ALL PRIVILEGES ON *.* TO 'tbdb'@'%' IDENTIFIED BY 'tbdbpw';
FLUSH PRIVILEGES;
exit

== Toolpack Development Prerequisite (Optional) ==
The Toolpack System Development prerequisite section is only required for customers that will develop their own application using the Toolpack API:

yum install gcc-c++ libxml2-devel libpcap-devel unixODBC-devel libaio libaio-devel

== Validation Guide (highly recommended) ==
If you would like to verify your installation go to the [[Toolpack_Installation:Validate_Toolpack_Installation_2-5|Toolpack Validation Guide]]

== Toolpack System installation ==

Now that the prerequisite are installed, now it is time to install the [[toolpack_installer_2-4|Toolpack system]]

Toolpack:Configuring tbSnmpAgent A

2011-06-21T20:52:31Z

Jasmin Letendre:

Once you are logged into the Web Portal and have successfully activated the tbSnmpAgent application, follow these steps to configure the application to suit your needs:

*Under the '''Applications''' heading, in the Web Portal navigation panel, click the '''Configurations''' tab.
[[File:Snmp_cfg_click_configurations.gif|border]]
 
*In the '''Application Configuration List''', find the entry for '''tbsnmpagent''' and click the link labeled '''edit''', next to that entry.
[[File:Snmp_cfg_click_edit.gif|border]]
 
===The tbSnmpAgent '''Application Configuration''' window is divided into several sections, which may be of interest to customers===

#Under the '''Application Params''' heading, the following general application parameters can be configured:
#*SNMP IP Port: the '''IP port''' to use for making SNMP requests (standard default value is 161)
#*SNMP System Description: the textual description that will appear when polling the '''sysDescr''' variable of the SNMPv2-MIB
#*SNMP System Object ID: the value appended to TelcoBridges' value (.1.3.6.1.4.1.21776.3) for the SNMPv2-MIB variable '''sysObjectId'''
#*SNMP System Name: the textual description that will appear when polling the '''sysName''' variable of the SNMPv2-MIB
#*SNMP System Location: the textual description that will appear when polling the '''sysLocation''' variable of the SNMPv2-MIB
#*SNMP System Contact: the textual description that will appear when polling the '''sysContact''' variable of the SNMPv2-MIB [[File:Snmp_cfg_application_params.gif|border]] 
#Under the '''Advanced Params''' heading, the following general application parameter can be configured:
#*Polling delay to generate traps: this sets the length for the time intervals at which the SNMP agent polls for newly generated traps. The value entered is in seconds [[File:Snmp_cfg_advanced_params.gif|border]] 
#Under the '''SNMPv1 SNMPv2c Communities''' heading, new '''communities''' can be created for SNMP versions 1 or 2:
#*By default, the standard communities '''public''' (read-only access), and '''private''' (read-write access) have been created
#*Click [[Creating an SNMPv1/SNMPv2 Community|'''Create new community''']] to create a new community for SNMPv1, or SNMPv2 [[File:Snmp_cfg_communities.gif|border]] 
#Under the '''SNMPv3 Users''' heading, new '''users''' can be created for SNMP version 3:
#*By default, no SNMPv3 users are created
#*Click [[Creating an SNMPv3 User|'''Create new SNMPv3 user''']] to create a new user definition for SNMPv3 [[File:Snmp_cfg_create_user.gif|border]] 
#Under the '''SNMP Trap Destinations''' heading, destination addresses for SNMP traps can be defined:
#*By default, no SNMP trap destinations are defined
#*Click [[Creating an SNMP Trap Destination|'''Create New SNMP Trap Destination''']] to create a new destination for sending SNMP traps to [[File:Snmp_cfg_create_trap.gif|border]] 
#Under the '''Log Params''' heading, logging parameters for the application can be set. The directory and format that logs are stored in can be selected. 
#Under the '''Advance Params''' heading, operational time delays ca be modified.

TbSnmpAgent Configuration

2011-06-21T20:51:13Z

Jasmin Letendre:

The '''tbSnmpAgent''' is a software application that interfaces between the TMedia system hardware and the [http://www.net-snmp.org NetSnmp] implementation of the Simple Network Management Protocol (SNMP) that is supported by TelcoBridges.
By default, tbSnmpAgent is '''disabled'''. In order to use the SNMP protocol to monitor and manage your hardware, the following steps must be taken:
 
* tbSnmpAgent must be '''activated'''
* tbSnmpAgent must be '''configured''' to suit your needs
 
The aforementioned tasks can be accomplished through the [[Web Portal]]:
 
#[[Activating tbSnmpAgent|Activate tbSnmpAgent]]
#[[Configuring tbSnmpAgent|Configure tbSNMPAGENT to suit your needs]]
 
Once these tasks have been completed, your TMedia platform is ready to expose system variables for polling with the Simple Network management Protocol (SNMP).

TbSnmpAgent Configuration

2011-06-21T20:50:52Z

Jasmin Letendre:

The '''tbSnmpAgent''' is a software application that interfaces between the TMedia system hardware and the [http://www.net-snmp.org NetSnmp] implementation of the Simple Network Management Protocol (SNMP) that is supported by TelcoBridges.
By default, tbSnmpAgent is '''disabled'''. In order to use the SNMP protocol to monitor and manage your hardware, the following steps must be taken:
 
* tbSnmpAgent must be activated
* tbSnmpAgent must be configured to suit your needs
 
The aforementioned tasks can be accomplished through the [[Web Portal]]:
 
#[[Activating tbSnmpAgent|Activate tbSnmpAgent]]
#[[Configuring tbSnmpAgent|Configure tbSNMPAGENT to suit your needs]]
 
Once these tasks have been completed, your TMedia platform is ready to expose system variables for polling with the Simple Network management Protocol (SNMP).

TB-MIB

2011-06-21T18:38:23Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance
 
==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware.
 
*'''The tbCommon Group:''' This group contains two tables: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.
 
*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua
 
*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.
 
[[Category:Glossary|TB-MIB]]

SNMP

2011-06-21T17:45:00Z

Jasmin Letendre:

The Simple Network Management Protocol (SNMP) is used in network management systems to monitor attached hardware for changes in operation activity. SNMP provides a standardized approach to monitoring and managing network systems.
 For information on configuring your TMedia product to use the SNMP protocol, see the section labeled [[SNMP#Related Tasks|"'''Related Tasks'''"]].
 
== TelcoBridges and SNMP ==
TelcoBridges offers basic support for SNMP versions 1, 2, and 3. More specifically, this grants users the ability to remotely poll (or GET) system variables, known as Managed Objects, which are represented in files known as MIB modules. TelcoBridges currently offers polling on '''standard''' MIB modules (RTP, SONET, DS1, DS3, ISDN, etc...) and on the TelcoBridges '''privately defined''' module ([[Media:TB-MIB-2011.txt|'''TB-MIB''']]).
 SNMP '''traps''', which are automatically generated by the NetSnmp implementation, are currently supported for the ifTable of the IF-MIB module. This module allows users to monitor the operation status of all network interfaces, and receive notifications when the states change.
 
'''Note:''' The SNMP '''SET''' ability is not currently supported by TelcoBridges.
 
====List of MIB modules currently exposed by TMedia gateways====
 
#[http://www.ietf.org/rfc/rfc1213.txt RFC 1213 MIB II (RFC1213-MIB)]
#*All tables of the RFC1213-MIB are supported, '''with the exception of''':
#**ipRouteTable
#**EGP group
#**atTable
#[http://www.ietf.org/rfc/rfc1573.txt RFC 1573 Evolution of Interfaces Group of MIB-II (IF-MIB)]
#*The following tables are supported:
#**ifTable
#**ifStackTable
#[http://www.rfc-editor.org/rfc/rfc2959.txt RFC 2959 Real-Time Transport Protocol Management Information Base (RTP-MIB)]
#*The following tables of the RTP-MIB are supported:
#**rtpSessionTable
#**rtpSenderTable
#**rtpRcvrTable
#[http://www.faqs.org/rfcs/rfc4805.html RFC 4805 DS1, J1, E1, DS2, and E2 Interfaces (DS1-MIB)]
#*The following tables of the DS1-MIB are supported:
#**Dsx1ConfigTable
#**Dsx1CurrentTable
#**Dsx1IntervalTable
#**Dsx1TotalTable
#[http://www.faqs.org/rfcs/rfc3896.html RFC 3896 - Definitions of Managed Object for the DS3/E3 Interface Type (DS3-MIB)]
#*The following tables of the DS3-MIB are supported:
#**Dsx3ConfigTable
#**Dsx3CurrentTable
#**Dsx3IntervalTable
#**Dsx3TotalTable
#[http://www.faqs.org/rfcs/rfc3592.html RFC 3592 - Definitions of Managed Object for the SONET/SDH Interface Type (SONET-MIB)]
#*The following tables of the SONET-MIB are supported:
#**sonetMediumTable
#**sonetSectionCurrentTable
#**sonetSectionIntervalTable
#**sonetLineCurrentTable
#**sonetLineIntervalTable
#**sonetFarendLineCurrentTable
#**sonetFarendLineIntervalTable
#**sonetPathCurrentTable
#**sonetPathIntervalTable
#**sonetFarendPathCurrentTable
#**sonetFarendPathIntervalTable
#**sonetVtCurrentTable
#**sonetVtIntervalTable
#**sonetFarendVtCurrentTable
#**sonetFarendVtIntervalTable
#[http://www.rfc-editor.org/rfc/rfc2127.txt RFC 2127 - ISDN Management Information Base using SMIv2 (ISDN-MIB)]
#*The following tables of the ISDN-MIB are supported:
#**isdnBearerGroup
#**isdnSignalingGroup
#[[Media:TB-MIB-2011.txt|Telcobridges Private MIB module (TB-MIB)]]
 

== Related Tasks ==
*[[tbSnmpAgent Configuration|Configuring the tbSnmpAgent application]]
*[[TB-MIB|Introduction to the TelcoBridges Private MIB Module (TB-MIB)]]
*[[Installing NetSNMP from an External Host]]
*[[TMG SNMP support|How to relay SNMP on TMG products]]
 

== Other Tasks ==
*[[How to start NTP|How to install and start NTP on TMG products]]
 

== External Sources ==
*[http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol Wikipedia article on SNMP]
*[http://www.net-snmp.org/ NetSNMP implementation of the SNMP protocol]
 

[[Category:Glossary]]

SNMP

2011-06-21T17:42:06Z

Jasmin Letendre: /* TelcoBridges and SNMP */

Simple Network Management Protocol (SNMP) is a protocol used in network management systems to monitor attached hardware for changes in operation activity. SNMP provides a standardized approach to monitoring and managing network systems.
 For information on configuring your TMedia product to use the SNMP protocol, see the section labeled [[SNMP#Related Tasks|"'''Related Tasks'''"]].
 
== TelcoBridges and SNMP ==
TelcoBridges offers basic support for SNMP versions 1, 2, and 3. More specifically, this grants users the ability to remotely poll (or GET) system variables, known as Managed Objects, which are represented in files known as MIB modules. TelcoBridges currently offers polling on '''standard''' MIB modules (RTP, SONET, DS1, DS3, ISDN, etc...) and on the TelcoBridges '''privately defined''' module ([[Media:TB-MIB-2011.txt|'''TB-MIB''']]).
 SNMP '''traps''', which are automatically generated by the NetSnmp implementation, are currently supported for the ifTable of the IF-MIB module. This module allows users to monitor the operation status of all network interfaces, and receive notifications when the states change.
 
'''Note:''' The SNMP '''SET''' ability is not currently supported by TelcoBridges.
 
====List of MIB modules currently exposed by TMedia gateways====
 
#[http://www.ietf.org/rfc/rfc1213.txt RFC 1213 MIB II (RFC1213-MIB)]
#*All tables of the RFC1213-MIB are supported, '''with the exception of''':
#**ipRouteTable
#**EGP group
#**atTable
#[http://www.ietf.org/rfc/rfc1573.txt RFC 1573 Evolution of Interfaces Group of MIB-II (IF-MIB)]
#*The following tables are supported:
#**ifTable
#**ifStackTable
#[http://www.rfc-editor.org/rfc/rfc2959.txt RFC 2959 Real-Time Transport Protocol Management Information Base (RTP-MIB)]
#*The following tables of the RTP-MIB are supported:
#**rtpSessionTable
#**rtpSenderTable
#**rtpRcvrTable
#[http://www.faqs.org/rfcs/rfc4805.html RFC 4805 DS1, J1, E1, DS2, and E2 Interfaces (DS1-MIB)]
#*The following tables of the DS1-MIB are supported:
#**Dsx1ConfigTable
#**Dsx1CurrentTable
#**Dsx1IntervalTable
#**Dsx1TotalTable
#[http://www.faqs.org/rfcs/rfc3896.html RFC 3896 - Definitions of Managed Object for the DS3/E3 Interface Type (DS3-MIB)]
#*The following tables of the DS3-MIB are supported:
#**Dsx3ConfigTable
#**Dsx3CurrentTable
#**Dsx3IntervalTable
#**Dsx3TotalTable
#[http://www.faqs.org/rfcs/rfc3592.html RFC 3592 - Definitions of Managed Object for the SONET/SDH Interface Type (SONET-MIB)]
#*The following tables of the SONET-MIB are supported:
#**sonetMediumTable
#**sonetSectionCurrentTable
#**sonetSectionIntervalTable
#**sonetLineCurrentTable
#**sonetLineIntervalTable
#**sonetFarendLineCurrentTable
#**sonetFarendLineIntervalTable
#**sonetPathCurrentTable
#**sonetPathIntervalTable
#**sonetFarendPathCurrentTable
#**sonetFarendPathIntervalTable
#**sonetVtCurrentTable
#**sonetVtIntervalTable
#**sonetFarendVtCurrentTable
#**sonetFarendVtIntervalTable
#[http://www.rfc-editor.org/rfc/rfc2127.txt RFC 2127 - ISDN Management Information Base using SMIv2 (ISDN-MIB)]
#*The following tables of the ISDN-MIB are supported:
#**isdnBearerGroup
#**isdnSignalingGroup
#[[Media:TB-MIB-2011.txt|Telcobridges Private MIB module (TB-MIB)]]
 

== Related Tasks ==
*[[tbSnmpAgent Configuration|Configuring the tbSnmpAgent application]]
*[[TB-MIB|Introduction to the TelcoBridges Private MIB Module (TB-MIB)]]
*[[Installing NetSNMP from an External Host]]
*[[TMG SNMP support|How to relay SNMP on TMG products]]
 

== Other Tasks ==
*[[How to start NTP|How to install and start NTP on TMG products]]
 

== External Sources ==
*[http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol Wikipedia article on SNMP]
*[http://www.net-snmp.org/ NetSNMP implementation of the SNMP protocol]
 

[[Category:Glossary]]

SNMP

2011-06-21T17:41:57Z

Jasmin Letendre: /* External Sources */

Simple Network Management Protocol (SNMP) is a protocol used in network management systems to monitor attached hardware for changes in operation activity. SNMP provides a standardized approach to monitoring and managing network systems.
 For information on configuring your TMedia product to use the SNMP protocol, see the section labeled [[SNMP#Related Tasks|"'''Related Tasks'''"]].
 
== TelcoBridges and SNMP ==
 
TelcoBridges offers basic support for SNMP versions 1, 2, and 3. More specifically, this grants users the ability to remotely poll (or GET) system variables, known as Managed Objects, which are represented in files known as MIB modules. TelcoBridges currently offers polling on '''standard''' MIB modules (RTP, SONET, DS1, DS3, ISDN, etc...) and on the TelcoBridges '''privately defined''' module ([[Media:TB-MIB-2011.txt|'''TB-MIB''']]).
 SNMP '''traps''', which are automatically generated by the NetSnmp implementation, are currently supported for the ifTable of the IF-MIB module. This module allows users to monitor the operation status of all network interfaces, and receive notifications when the states change.
 
'''Note:''' The SNMP '''SET''' ability is not currently supported by TelcoBridges.
 
====List of MIB modules currently exposed by TMedia gateways====
 
#[http://www.ietf.org/rfc/rfc1213.txt RFC 1213 MIB II (RFC1213-MIB)]
#*All tables of the RFC1213-MIB are supported, '''with the exception of''':
#**ipRouteTable
#**EGP group
#**atTable
#[http://www.ietf.org/rfc/rfc1573.txt RFC 1573 Evolution of Interfaces Group of MIB-II (IF-MIB)]
#*The following tables are supported:
#**ifTable
#**ifStackTable
#[http://www.rfc-editor.org/rfc/rfc2959.txt RFC 2959 Real-Time Transport Protocol Management Information Base (RTP-MIB)]
#*The following tables of the RTP-MIB are supported:
#**rtpSessionTable
#**rtpSenderTable
#**rtpRcvrTable
#[http://www.faqs.org/rfcs/rfc4805.html RFC 4805 DS1, J1, E1, DS2, and E2 Interfaces (DS1-MIB)]
#*The following tables of the DS1-MIB are supported:
#**Dsx1ConfigTable
#**Dsx1CurrentTable
#**Dsx1IntervalTable
#**Dsx1TotalTable
#[http://www.faqs.org/rfcs/rfc3896.html RFC 3896 - Definitions of Managed Object for the DS3/E3 Interface Type (DS3-MIB)]
#*The following tables of the DS3-MIB are supported:
#**Dsx3ConfigTable
#**Dsx3CurrentTable
#**Dsx3IntervalTable
#**Dsx3TotalTable
#[http://www.faqs.org/rfcs/rfc3592.html RFC 3592 - Definitions of Managed Object for the SONET/SDH Interface Type (SONET-MIB)]
#*The following tables of the SONET-MIB are supported:
#**sonetMediumTable
#**sonetSectionCurrentTable
#**sonetSectionIntervalTable
#**sonetLineCurrentTable
#**sonetLineIntervalTable
#**sonetFarendLineCurrentTable
#**sonetFarendLineIntervalTable
#**sonetPathCurrentTable
#**sonetPathIntervalTable
#**sonetFarendPathCurrentTable
#**sonetFarendPathIntervalTable
#**sonetVtCurrentTable
#**sonetVtIntervalTable
#**sonetFarendVtCurrentTable
#**sonetFarendVtIntervalTable
#[http://www.rfc-editor.org/rfc/rfc2127.txt RFC 2127 - ISDN Management Information Base using SMIv2 (ISDN-MIB)]
#*The following tables of the ISDN-MIB are supported:
#**isdnBearerGroup
#**isdnSignalingGroup
#[[Media:TB-MIB-2011.txt|Telcobridges Private MIB module (TB-MIB)]]
 
== Related Tasks ==
*[[tbSnmpAgent Configuration|Configuring the tbSnmpAgent application]]
*[[TB-MIB|Introduction to the TelcoBridges Private MIB Module (TB-MIB)]]
*[[Installing NetSNMP from an External Host]]
*[[TMG SNMP support|How to relay SNMP on TMG products]]
 

== Other Tasks ==
*[[How to start NTP|How to install and start NTP on TMG products]]
 

== External Sources ==
*[http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol Wikipedia article on SNMP]
*[http://www.net-snmp.org/ NetSNMP implementation of the SNMP protocol]
 

[[Category:Glossary]]

SNMP

2011-06-21T17:41:52Z

Jasmin Letendre: /* Other Tasks */

Simple Network Management Protocol (SNMP) is a protocol used in network management systems to monitor attached hardware for changes in operation activity. SNMP provides a standardized approach to monitoring and managing network systems.
 For information on configuring your TMedia product to use the SNMP protocol, see the section labeled [[SNMP#Related Tasks|"'''Related Tasks'''"]].
 
== TelcoBridges and SNMP ==
 
TelcoBridges offers basic support for SNMP versions 1, 2, and 3. More specifically, this grants users the ability to remotely poll (or GET) system variables, known as Managed Objects, which are represented in files known as MIB modules. TelcoBridges currently offers polling on '''standard''' MIB modules (RTP, SONET, DS1, DS3, ISDN, etc...) and on the TelcoBridges '''privately defined''' module ([[Media:TB-MIB-2011.txt|'''TB-MIB''']]).
 SNMP '''traps''', which are automatically generated by the NetSnmp implementation, are currently supported for the ifTable of the IF-MIB module. This module allows users to monitor the operation status of all network interfaces, and receive notifications when the states change.
 
'''Note:''' The SNMP '''SET''' ability is not currently supported by TelcoBridges.
 
====List of MIB modules currently exposed by TMedia gateways====
 
#[http://www.ietf.org/rfc/rfc1213.txt RFC 1213 MIB II (RFC1213-MIB)]
#*All tables of the RFC1213-MIB are supported, '''with the exception of''':
#**ipRouteTable
#**EGP group
#**atTable
#[http://www.ietf.org/rfc/rfc1573.txt RFC 1573 Evolution of Interfaces Group of MIB-II (IF-MIB)]
#*The following tables are supported:
#**ifTable
#**ifStackTable
#[http://www.rfc-editor.org/rfc/rfc2959.txt RFC 2959 Real-Time Transport Protocol Management Information Base (RTP-MIB)]
#*The following tables of the RTP-MIB are supported:
#**rtpSessionTable
#**rtpSenderTable
#**rtpRcvrTable
#[http://www.faqs.org/rfcs/rfc4805.html RFC 4805 DS1, J1, E1, DS2, and E2 Interfaces (DS1-MIB)]
#*The following tables of the DS1-MIB are supported:
#**Dsx1ConfigTable
#**Dsx1CurrentTable
#**Dsx1IntervalTable
#**Dsx1TotalTable
#[http://www.faqs.org/rfcs/rfc3896.html RFC 3896 - Definitions of Managed Object for the DS3/E3 Interface Type (DS3-MIB)]
#*The following tables of the DS3-MIB are supported:
#**Dsx3ConfigTable
#**Dsx3CurrentTable
#**Dsx3IntervalTable
#**Dsx3TotalTable
#[http://www.faqs.org/rfcs/rfc3592.html RFC 3592 - Definitions of Managed Object for the SONET/SDH Interface Type (SONET-MIB)]
#*The following tables of the SONET-MIB are supported:
#**sonetMediumTable
#**sonetSectionCurrentTable
#**sonetSectionIntervalTable
#**sonetLineCurrentTable
#**sonetLineIntervalTable
#**sonetFarendLineCurrentTable
#**sonetFarendLineIntervalTable
#**sonetPathCurrentTable
#**sonetPathIntervalTable
#**sonetFarendPathCurrentTable
#**sonetFarendPathIntervalTable
#**sonetVtCurrentTable
#**sonetVtIntervalTable
#**sonetFarendVtCurrentTable
#**sonetFarendVtIntervalTable
#[http://www.rfc-editor.org/rfc/rfc2127.txt RFC 2127 - ISDN Management Information Base using SMIv2 (ISDN-MIB)]
#*The following tables of the ISDN-MIB are supported:
#**isdnBearerGroup
#**isdnSignalingGroup
#[[Media:TB-MIB-2011.txt|Telcobridges Private MIB module (TB-MIB)]]
 
== Related Tasks ==
*[[tbSnmpAgent Configuration|Configuring the tbSnmpAgent application]]
*[[TB-MIB|Introduction to the TelcoBridges Private MIB Module (TB-MIB)]]
*[[Installing NetSNMP from an External Host]]
*[[TMG SNMP support|How to relay SNMP on TMG products]]
 

== Other Tasks ==
*[[How to start NTP|How to install and start NTP on TMG products]]
 

== External Sources ==
 
*[http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol Wikipedia article on SNMP]
*[http://www.net-snmp.org/ NetSNMP implementation of the SNMP protocol]
 

[[Category:Glossary]]

SNMP

2011-06-21T17:41:44Z

Jasmin Letendre: /* Related Tasks */

Simple Network Management Protocol (SNMP) is a protocol used in network management systems to monitor attached hardware for changes in operation activity. SNMP provides a standardized approach to monitoring and managing network systems.
 For information on configuring your TMedia product to use the SNMP protocol, see the section labeled [[SNMP#Related Tasks|"'''Related Tasks'''"]].
 
== TelcoBridges and SNMP ==
 
TelcoBridges offers basic support for SNMP versions 1, 2, and 3. More specifically, this grants users the ability to remotely poll (or GET) system variables, known as Managed Objects, which are represented in files known as MIB modules. TelcoBridges currently offers polling on '''standard''' MIB modules (RTP, SONET, DS1, DS3, ISDN, etc...) and on the TelcoBridges '''privately defined''' module ([[Media:TB-MIB-2011.txt|'''TB-MIB''']]).
 SNMP '''traps''', which are automatically generated by the NetSnmp implementation, are currently supported for the ifTable of the IF-MIB module. This module allows users to monitor the operation status of all network interfaces, and receive notifications when the states change.
 
'''Note:''' The SNMP '''SET''' ability is not currently supported by TelcoBridges.
 
====List of MIB modules currently exposed by TMedia gateways====
 
#[http://www.ietf.org/rfc/rfc1213.txt RFC 1213 MIB II (RFC1213-MIB)]
#*All tables of the RFC1213-MIB are supported, '''with the exception of''':
#**ipRouteTable
#**EGP group
#**atTable
#[http://www.ietf.org/rfc/rfc1573.txt RFC 1573 Evolution of Interfaces Group of MIB-II (IF-MIB)]
#*The following tables are supported:
#**ifTable
#**ifStackTable
#[http://www.rfc-editor.org/rfc/rfc2959.txt RFC 2959 Real-Time Transport Protocol Management Information Base (RTP-MIB)]
#*The following tables of the RTP-MIB are supported:
#**rtpSessionTable
#**rtpSenderTable
#**rtpRcvrTable
#[http://www.faqs.org/rfcs/rfc4805.html RFC 4805 DS1, J1, E1, DS2, and E2 Interfaces (DS1-MIB)]
#*The following tables of the DS1-MIB are supported:
#**Dsx1ConfigTable
#**Dsx1CurrentTable
#**Dsx1IntervalTable
#**Dsx1TotalTable
#[http://www.faqs.org/rfcs/rfc3896.html RFC 3896 - Definitions of Managed Object for the DS3/E3 Interface Type (DS3-MIB)]
#*The following tables of the DS3-MIB are supported:
#**Dsx3ConfigTable
#**Dsx3CurrentTable
#**Dsx3IntervalTable
#**Dsx3TotalTable
#[http://www.faqs.org/rfcs/rfc3592.html RFC 3592 - Definitions of Managed Object for the SONET/SDH Interface Type (SONET-MIB)]
#*The following tables of the SONET-MIB are supported:
#**sonetMediumTable
#**sonetSectionCurrentTable
#**sonetSectionIntervalTable
#**sonetLineCurrentTable
#**sonetLineIntervalTable
#**sonetFarendLineCurrentTable
#**sonetFarendLineIntervalTable
#**sonetPathCurrentTable
#**sonetPathIntervalTable
#**sonetFarendPathCurrentTable
#**sonetFarendPathIntervalTable
#**sonetVtCurrentTable
#**sonetVtIntervalTable
#**sonetFarendVtCurrentTable
#**sonetFarendVtIntervalTable
#[http://www.rfc-editor.org/rfc/rfc2127.txt RFC 2127 - ISDN Management Information Base using SMIv2 (ISDN-MIB)]
#*The following tables of the ISDN-MIB are supported:
#**isdnBearerGroup
#**isdnSignalingGroup
#[[Media:TB-MIB-2011.txt|Telcobridges Private MIB module (TB-MIB)]]
 
== Related Tasks ==
*[[tbSnmpAgent Configuration|Configuring the tbSnmpAgent application]]
*[[TB-MIB|Introduction to the TelcoBridges Private MIB Module (TB-MIB)]]
*[[Installing NetSNMP from an External Host]]
*[[TMG SNMP support|How to relay SNMP on TMG products]]
 

== Other Tasks ==
 
*[[How to start NTP|How to install and start NTP on TMG products]]
 
== External Sources ==
 
*[http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol Wikipedia article on SNMP]
*[http://www.net-snmp.org/ NetSNMP implementation of the SNMP protocol]
 

[[Category:Glossary]]

TB-MIB

2011-06-21T17:41:09Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance
 
==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware.
 
*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.
 
*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua
 
*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.
 
[[Category:Glossary|TB-MIB]]

TB-MIB

2011-06-21T17:40:56Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance
 
==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware.
 
*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.
 
*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua
 
*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.

[[Category:Glossary|TB-MIB]]

TB-MIB

2011-06-21T17:40:49Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance
 
==TB-MIB Groups==
 
*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware.
 
*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.
 
*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua
 
*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.

[[Category:Glossary|TB-MIB]]

TB-MIB

2011-06-21T17:40:21Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance

==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware.
 
*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.
 
*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua
 
*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.

[[Category:Glossary|TB-MIB]]

TB-MIB

2011-06-21T17:40:05Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance

==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware.
 
*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.
 
*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua
 
*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.

[[Category:Glossary|TB-MIB]]

TB-MIB

2011-06-21T17:39:29Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance

==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware. 

*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.

*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua

*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.

[[Category:Glossary|TB-MIB]]

TB-MIB

2011-06-21T17:39:19Z

Jasmin Letendre:

The TelcoBridges privately-defined MIB module, TB-MIB, is used to poll status information and usage statistics that have not been defined in standardized MIB modules.
The TB-MIB can be divided into four (4) main groups:
* tbDirectory
* tbCommon
* tbSignaling
* tbConformance

==TB-MIB Groups==

*'''The tbDirectory Group:''' This group contains the tbModule table. This table can be used to view a list of all MIB-modules currently supported by TelcoBridges, and exposed by the TMedia hardware. 

*'''The tbCommon Group:''' This group contains two table: the tbHwCommon table, and the tbSwCommon table. These tables can be used to view general identification and performance details for TMedia hardware and software.

*'''The tbSignaling Group:''' This group contains sub-groups, each with a different number of tables, that define MIB objects for SS7 and SIGTRAN signaling protocols. Subgroups include:
**tbMtp2
**tbM2pa
**tbM2ua
**tbIua
**tbM3ua

*'''The tbConformance Group:''' This group contains only conformance information for the TB-MIB module. This is SMIv2-compliant information for setting compliance standards, and does not contain fetchable information.

[[Category:Glossary|TB-MIB]]

Toolpack:Configuring tbSnmpAgent A

2011-06-21T17:38:13Z

Jasmin Letendre:

Once you are logged into the Web Portal and have successfully activated the tbSnmpAgent application, follow these steps to configure the application to suit your needs:

*Under the '''Applications''' heading, in the Web Portal navigation panel, click the '''Configurations''' tab.
[[File:Snmp_cfg_click_configurations.gif|border]]
 
*In the '''Application Configuration List''', find the entry for '''tbsnmpagent''' and click the link labeled '''edit''', next to that entry.
[[File:Snmp_cfg_click_edit.gif|border]]
 
===The tbSnmpAgent '''Application Configuration''' window is divided into several sections, which may be of interest to customers===

#Under the '''Application Params''' heading, the following general application parameters can be configured:
#*SNMP IP Port: the port to use for making SNMP requests (standard default value is 161)
#*SNMP System Description: the textual description that will appear when polling the '''sysDescr''' variable of the SNMPv2-MIB
#*SNMP System Object ID: the value appended to TelcoBridges' value (.1.3.6.1.4.1.21776.3) for the SNMPv2-MIB variable '''sysObjectId'''
#*SNMP System Name: the textual description that will appear when polling the '''sysName''' variable of the SNMPv2-MIB
#*SNMP System Location: the textual description that will appear when polling the '''sysLocation''' variable of the SNMPv2-MIB
#*SNMP System Contact: the textual description that will appear when polling the '''sysContact''' variable of the SNMPv2-MIB [[File:Snmp_cfg_application_params.gif|border]] 
#Under the '''Advanced Params''' heading, the following general application parameter can be configured:
#*Polling delay to generate traps: this sets the length for the time intervals at which the SNMP agent polls for newly generated traps. The value entered is in seconds [[File:Snmp_cfg_advanced_params.gif|border]] 
#Under the '''SNMPv1 SNMPv2c Communities''' heading, new '''communities''' can be created for SNMP versions 1 or 2:
#*By default, the standard communities '''public''' (read-only access), and '''private''' (read-write access) have been created
#*Click [[Creating an SNMPv1/SNMPv2 Community|'''Create new community''']] to create a new community for SNMPv1, or SNMPv2 [[File:Snmp_cfg_communities.gif|border]] 
#Under the '''SNMPv3 Users''' heading, new '''users''' can be created for SNMP version 3:
#*By default, no SNMPv3 users are created
#*Click [[Creating an SNMPv3 User|'''Create new SNMPv3 user''']] to create a new user definition for SNMPv3 [[File:Snmp_cfg_create_user.gif|border]] 
#Under the '''SNMP Trap Destinations''' heading, destination addresses for SNMP traps can be defined:
#*By default, no SNMP trap destinations are defined
#*Click [[Creating an SNMP Trap Destination|'''Create New SNMP Trap Destination''']] to create a new destination for sending SNMP traps to [[File:Snmp_cfg_create_trap.gif|border]] 
#Under the '''Log Params''' heading, logging parameters for the application can be set. The directory and format that logs are stored in can be selected. 
#Under the '''Advance Params''' heading, operational time delays ca be modified.

Activating tbSnmpAgent A

2011-06-21T17:37:23Z

Jasmin Letendre:

Once you are logged into the Web Portal, follow these steps to activate the tbSnmpAgent application:

*Click the '''Status''' tab in the navigation panel.
[[File:Snmp_click_status.gif|border]]
 
*In the '''status''' information window, click the '''Applications''' tab.
[[File:Snmp_click_applications.gif|border]]
 
*In the '''Applications''' information window, '''tbsnmpagent''' should appear in the '''Not running list'''. Click '''tbsnmpagent'''.
[[File:Snmp_click_tbSnmpAgent.gif|border]]
 
*In the '''Application instance status''' window for tbSnmpAgent, click the '''Oam target state''' dropdown box and select '''Run'''. Click '''Apply states'''.
[[File:Snmp_tbSnmpAgent_run.gif|border]]
 
*Return to the '''Applications''' information window. '''tbsnmpagent''' should now appear in the '''Ready list'''.
[[File:Snmp_tbSnmpAgent_active.gif|border]]
 
*'''The tbSnmpAgent application has now been activated'''.
 
==Next Step==
*Now that you have activated the SNMP agent application, you are ready to [[Configuring tbSnmpAgent|configure the application for your needs]].

SNMP

2011-06-21T17:17:54Z

Jasmin Letendre:

Simple Network Management Protocol (SNMP) is a protocol used in network management systems to monitor attached hardware for changes in operation activity. SNMP provides a standardized approach to monitoring and managing network systems.
 For information on configuring your TMedia product to use the SNMP protocol, see the section labeled [[SNMP#Related Tasks|"'''Related Tasks'''"]].
 
== TelcoBridges and SNMP ==
 
TelcoBridges offers basic support for SNMP versions 1, 2, and 3. More specifically, this grants users the ability to remotely poll (or GET) system variables, known as Managed Objects, which are represented in files known as MIB modules. TelcoBridges currently offers polling on '''standard''' MIB modules (RTP, SONET, DS1, DS3, ISDN, etc...) and on the TelcoBridges '''privately defined''' module ([[Media:TB-MIB-2011.txt|'''TB-MIB''']]).
 SNMP '''traps''', which are automatically generated by the NetSnmp implementation, are currently supported for the ifTable of the IF-MIB module. This module allows users to monitor the operation status of all network interfaces, and receive notifications when the states change.
 
'''Note:''' The SNMP '''SET''' ability is not currently supported by TelcoBridges.
 
====List of MIB modules currently exposed by TMedia gateways====
 
#[http://www.ietf.org/rfc/rfc1213.txt RFC 1213 MIB II (RFC1213-MIB)]
#*All tables of the RFC1213-MIB are supported, '''with the exception of''':
#**ipRouteTable
#**EGP group
#**atTable
#[http://www.ietf.org/rfc/rfc1573.txt RFC 1573 Evolution of Interfaces Group of MIB-II (IF-MIB)]
#*The following tables are supported:
#**ifTable
#**ifStackTable
#[http://www.rfc-editor.org/rfc/rfc2959.txt RFC 2959 Real-Time Transport Protocol Management Information Base (RTP-MIB)]
#*The following tables of the RTP-MIB are supported:
#**rtpSessionTable
#**rtpSenderTable
#**rtpRcvrTable
#[http://www.faqs.org/rfcs/rfc4805.html RFC 4805 DS1, J1, E1, DS2, and E2 Interfaces (DS1-MIB)]
#*The following tables of the DS1-MIB are supported:
#**Dsx1ConfigTable
#**Dsx1CurrentTable
#**Dsx1IntervalTable
#**Dsx1TotalTable
#[http://www.faqs.org/rfcs/rfc3896.html RFC 3896 - Definitions of Managed Object for the DS3/E3 Interface Type (DS3-MIB)]
#*The following tables of the DS3-MIB are supported:
#**Dsx3ConfigTable
#**Dsx3CurrentTable
#**Dsx3IntervalTable
#**Dsx3TotalTable
#[http://www.faqs.org/rfcs/rfc3592.html RFC 3592 - Definitions of Managed Object for the SONET/SDH Interface Type (SONET-MIB)]
#*The following tables of the SONET-MIB are supported:
#**sonetMediumTable
#**sonetSectionCurrentTable
#**sonetSectionIntervalTable
#**sonetLineCurrentTable
#**sonetLineIntervalTable
#**sonetFarendLineCurrentTable
#**sonetFarendLineIntervalTable
#**sonetPathCurrentTable
#**sonetPathIntervalTable
#**sonetFarendPathCurrentTable
#**sonetFarendPathIntervalTable
#**sonetVtCurrentTable
#**sonetVtIntervalTable
#**sonetFarendVtCurrentTable
#**sonetFarendVtIntervalTable
#[http://www.rfc-editor.org/rfc/rfc2127.txt RFC 2127 - ISDN Management Information Base using SMIv2 (ISDN-MIB)]
#*The following tables of the ISDN-MIB are supported:
#**isdnBearerGroup
#**isdnSignalingGroup
#[[Media:TB-MIB-2011.txt|Telcobridges Private MIB module (TB-MIB)]]
 
== Related Tasks ==
 
*[[tbSnmpAgent Configuration|Configuring the tbSnmpAgent application]]
*[[TB-MIB|Introduction to the TelcoBridges Private MIB Module (TB-MIB)]]
*[[Installing NetSNMP from an External Host]]
*[[TMG SNMP support|How to relay SNMP on TMG products]]
 
== Other Tasks ==
 
*[[How to start NTP|How to install and start NTP on TMG products]]
 
== External Sources ==
 
*[http://en.wikipedia.org/wiki/Simple_Network_Management_Protocol Wikipedia article on SNMP]
*[http://www.net-snmp.org/ NetSNMP implementation of the SNMP protocol]
 

[[Category:Glossary]]

Installing NetSNMP from an External Host

2011-06-21T15:10:17Z

Jasmin Letendre:

All current TMedia products come with the NetSNMP implementation of the SNMP protocol pre-installed. However, for TDev customers and older TMedia customers, NetSNMP must be installed on the hardware from an external host.
The following commands will install NetSNMP from a '''Linux''' host:
 
<div style="font-family:courier;border:solid;border-width:1px;padding:5px;width:25%;">
yum install net-snmp 
yum install net-snmp-utils 
yum install net-snmp-libs 
yum install lm-sensors
</div>
 
====Applications Installed====
*net-snmp: the core net-snmp application
*net-snmp-utils: utilities used by net-snmp to poll OIDs (GET, GET-NEXT, etc...)
*net-snmp-libs: libraries used by the net-snmp-utils
*lm-sensors: sensors used by net-snmp to poll hardware statistics

Installing NetSNMP from an External Host

2011-06-21T15:09:48Z

Jasmin Letendre:

All current TMedia products come with the NetSNMP implementation of the SNMP protocol pre-installed. However, for TDev customers and older TMedia customers, NetSNMP must be installed on the hardware from an external host.
The following commands will install NetSNMP from a '''Linux''' host:
 
<div style="font-family:courier;border:solid;border-width:1px;padding:5px;width:25%;">
yum install net-snmp 
yum install net-snmp-utils 
yum install net-snmp-libs 
yum install lm-sensors
</div>
 
*net-snmp: the core net-snmp application
*net-snmp-utils: utilities used by net-snmp to poll OIDs (GET, GET-NEXT, etc...)
*net-snmp-libs: libraries used by the net-snmp-utils
*lm-sensors: sensors used by net-snmp to poll hardware statistics

Installing NetSNMP from an External Host

2011-06-21T15:09:26Z

Jasmin Letendre:

All current TMedia products come with the NetSNMP implementation of the SNMP protocol pre-installed. However, for TDev customers and older TMedia customers, NetSNMP must be installed on the hardware from an external host.
The following commands will install NetSNMP from a Linux host:
 
<div style="font-family:courier;border:solid;border-width:1px;padding:5px;width:25%;">
yum install net-snmp 
yum install net-snmp-utils 
yum install net-snmp-libs 
yum install lm-sensors
</div>
 
*net-snmp: the core net-snmp application
*net-snmp-utils: utilities used by net-snmp to poll OIDs (GET, GET-NEXT, etc...)
*net-snmp-libs: libraries used by the net-snmp-utils
*lm-sensors: sensors used by net-snmp to poll hardware statistics

Toolpack:Creating an SNMP Trap Destination A

2011-06-21T15:08:01Z

Jasmin Letendre:

SNMP traps are automatically generated on TMedia platforms by the NetSNMP installation, which monitors hardware and software interfaces registered with the ifTable of the IF-MIB module. When the operation status of an interface changes, a trap is generated by NetSNMP, and sent to a destination address for processing. In order for this mechanic to function, an '''SNMP trap destination''' must be defined in the Web Portal.
 
To create an SNMP trap destination, carry out the following steps:
 
'''NOTE:''' The procedure is slightly different, dependng on whether you are creating a trap destination for SNMPv1/v2, or for SNMPv3.
 
*Click Create New SNMP Trap Destination under the '''SNMP Trap Destinations''' heading
[[File:Snmp_cfg_create_trap.gif|border]] 
====Creating an SNMPv1/v2 Trap Destination====
*In the trap destination configuration panel, set the following parameters '''if you are creating a trap destination for SNMPv1/v2''':
**Enter a '''name''' to identify the trap destination
**Enter a destination '''IP Address''' for sending generated traps
**Enter a destination '''port number''', on which to send generated traps (standard default value is 162)
**Click on the '''SNMP Version''' drop-down box and select version 1 or 2
**Enter the name of the SNMPv1/v2 '''community''' to use (configured previously)
**Click '''Create'''
[[File:Snmp_cfg_creating_trap_v1.gif|border]] 
====Creating an SNMPv3 Trap Destination====
*In the trap destination configuration panel, set the following parameters '''if you are creating a trap destination for SNMPv3''':
**Enter a '''name''' to identify the trap destination
**Enter a destination '''IP Address''' for sending generated traps
**Enter a destination '''port number''', on which to send generated traps (standard default value is 162)
**Click on the '''SNMP Version''' drop-down box and select version 3
**Enter the name of the SNMPv3 '''user''' to use (configured previously)
**Click on the '''security level''' drop-down box, and select the appropriate '''security level''' for the user
**Click on the '''authentication''' drop-down box, and select the appropriate '''authentication algorithm''' for the user
**Enter the appropriate authentication '''pass phrase''' for the user
**Click on the '''privacy protocol''' drop-down box, and select the appropriate '''privacy standard''' for the user
**Enter the appropriate authentication '''privacy phrase''' for the user
**Click '''Create'''
[[File:Snmp_cfg_creating_trap_v3.gif|border]] 
*Verify that the '''"SNMP Trap Destination was Successfully Created"''' message appears at the top of the following window
[[File:Snmp_cfg_trap_confirm.gif|border]] 
*The new SNMP trap destination should appear under the '''SNMP Trap Destinations''' heading
[[File:Snmp_cfg_trap_created.gif|border]]

Toolpack:Creating an SNMP Trap Destination A

2011-06-21T15:07:40Z

Jasmin Letendre:

SNMP traps are automatically generated on TMedia platforms by the NetSNMP installation, which monitors hardware and software interfaces registered with the ifTable of the IF-MIB module. When the operation status of an interface changes, a trap is generated by NetSNMP, and sent to a destination address for processing. In order for this mechanic to function, an '''SNMP trap destination''' must be defined in the Web Portal.
 
To create an SNMP trap destination, carry out the following steps:
 
NOTE: The procedure is slightly different, dependng on whether you are creating a trap destination for SNMPv1/v2, or for SNMPv3.
 
*Click Create New SNMP Trap Destination under the '''SNMP Trap Destinations''' heading
[[File:Snmp_cfg_create_trap.gif|border]] 
====Creating an SNMPv1/v2 Trap Destination====
*In the trap destination configuration panel, set the following parameters '''if you are creating a trap destination for SNMPv1/v2''':
**Enter a '''name''' to identify the trap destination
**Enter a destination '''IP Address''' for sending generated traps
**Enter a destination '''port number''', on which to send generated traps (standard default value is 162)
**Click on the '''SNMP Version''' drop-down box and select version 1 or 2
**Enter the name of the SNMPv1/v2 '''community''' to use (configured previously)
**Click '''Create'''
[[File:Snmp_cfg_creating_trap_v1.gif|border]] 
====Creating an SNMPv3 Trap Destination====
*In the trap destination configuration panel, set the following parameters '''if you are creating a trap destination for SNMPv3''':
**Enter a '''name''' to identify the trap destination
**Enter a destination '''IP Address''' for sending generated traps
**Enter a destination '''port number''', on which to send generated traps (standard default value is 162)
**Click on the '''SNMP Version''' drop-down box and select version 3
**Enter the name of the SNMPv3 '''user''' to use (configured previously)
**Click on the '''security level''' drop-down box, and select the appropriate '''security level''' for the user
**Click on the '''authentication''' drop-down box, and select the appropriate '''authentication algorithm''' for the user
**Enter the appropriate authentication '''pass phrase''' for the user
**Click on the '''privacy protocol''' drop-down box, and select the appropriate '''privacy standard''' for the user
**Enter the appropriate authentication '''privacy phrase''' for the user
**Click '''Create'''
[[File:Snmp_cfg_creating_trap_v3.gif|border]] 
*Verify that the '''"SNMP Trap Destination was Successfully Created"''' message appears at the top of the following window
[[File:Snmp_cfg_trap_confirm.gif|border]] 
*The new SNMP trap destination should appear under the '''SNMP Trap Destinations''' heading
[[File:Snmp_cfg_trap_created.gif|border]]

Toolpack:Creating an SNMP Trap Destination A

2011-06-21T15:06:22Z

Jasmin Letendre:

SNMP traps are automatically generated on TMedia platforms by the NetSNMP installation, which monitors hardware and software interfaces registered with the ifTable of the IF-MIB module. When the operation status of an interface changes, a trap is generated by NetSNMP, and sent to a destination address for processing. In order for this mechanic to function, an '''SNMP trap destination''' must be defined in the Web Portal.
 
To create an SNMP trap destination, carry out the following steps:
 
*Click Create New SNMP Trap Destination under the '''SNMP Trap Destinations''' heading
[[File:Snmp_cfg_create_trap.gif|border]] 
====Creating an SNMPv1/v2 Trap Destination====
*In the trap destination configuration panel, set the following parameters '''if you are creating a trap destination for SNMPv1/v2''':
**Enter a '''name''' to identify the trap destination
**Enter a destination '''IP Address''' for sending generated traps
**Enter a destination '''port number''', on which to send generated traps (standard default value is 162)
**Click on the '''SNMP Version''' drop-down box and select version 1 or 2
**Enter the name of the SNMPv1/v2 '''community''' to use (configured previously)
**Click '''Create'''
[[File:Snmp_cfg_creating_trap_v1.gif|border]] 
====Creating an SNMPv3 Trap Destination====
*In the trap destination configuration panel, set the following parameters '''if you are creating a trap destination for SNMPv3''':
**Enter a '''name''' to identify the trap destination
**Enter a destination '''IP Address''' for sending generated traps
**Enter a destination '''port number''', on which to send generated traps (standard default value is 162)
**Click on the '''SNMP Version''' drop-down box and select version 3
**Enter the name of the SNMPv3 '''user''' to use (configured previously)
**Click on the '''security level''' drop-down box, and select the appropriate '''security level''' for the user
**Click on the '''authentication''' drop-down box, and select the appropriate '''authentication algorithm''' for the user
**Enter the appropriate authentication '''pass phrase''' for the user
**Click on the '''privacy protocol''' drop-down box, and select the appropriate '''privacy standard''' for the user
**Enter the appropriate authentication '''privacy phrase''' for the user
**Click '''Create'''
[[File:Snmp_cfg_creating_trap_v3.gif|border]] 
*Verify that the '''"SNMP Trap Destination was Successfully Created"''' message appears at the top of the following window
[[File:Snmp_cfg_trap_confirm.gif|border]] 
*The new SNMP trap destination should appear under the '''SNMP Trap Destinations''' heading
[[File:Snmp_cfg_trap_created.gif|border]]