Difference between revisions of "CRBT logic"

Revision as of 13:32, 28 October 2013

The crbt_scp.php is an implementation for a CAMEL gsmSCP application which provides a Colourful Ring Back Tone service by interfacing with a CAMEL gsmSSF.

Upon service invocation, this script implements the required actions in order to instruct the gsmSSF to provide the required ringback tone.

Configuration

Script side

The CRBT script supports two ways of communicating with Yate:

1. One based on the XML protocol, communication being realized through a TCP socket.
2. The other one based done through Yate messages, using extmodule.

The way which the script will use is chosen according to configuration - in particular, through the $ioType setting.

Configuration of this script is done through config.php. This allows setting the following parameters:

• 1. $appName- value of the application parameters set in the camel.message. This value is used to check that the message is indeed intented for this script.

• 2. $ioType - type of I/O to use to communicate with Yate. The script recognizes these two values:
  • TCP - use the configured TCP socket to communicate with Yate.
  • MSG - use messages through exmodule protocol for communication.

• 3. $host,$port - host and port where the application should connect to in order to communicate with Yate if $ioType is set to TCP.

• 4. $transTimeout - integer. It sets the time for which the PHP TCAP library will keep alive a TCAP dialogue after remaining with no active components. A new TCAP message will reset the associated timer. If the timer runs out, the library will generate a TCAP End in order to terminate the dialog. For this application, this timer is set by default to 180 seconds.

• 5. $findMelodyID - boolean. It specifies whether the gsmSCF should take the necessary steps in order to find out the required ringtone for the called user. Its default value is false, meaning that the gsmSCF will assume that all requests reaching it are requests for subscribers which have the service activated

• 6. $httpRequest - string. It's the HTTP request to be made in order to find out the ringtone associated with the user.

• 7. $myServiceKey - integer. The ID of the service provided by this gsmSCF application and which should come in IDP in order to accept the request.

• 8. $myDP - string. The DP for which this SCP should be triggered and which should come in IDP in order to accept the request.

• 9. $sendAll - bool. If true, it will send all response components batched in a single TCAP message, otherwise it will send them each with its own TCAP message. It is set by default to true.

• 10. $buildSRFNum - string. It specifies how the address of the gsmSRF for the EstablishTemporaryConnection operation will be built. It can have of of the following values:
  • prefix_called - build the gsmSRF address following this rule @@$srfNumber.$srfSeparator.$correlationID.$srfSeparator.$sfcID@@.
  • fixed_number - use $srfNumber as a fixed address for the gsmSRF address. Setting this means that correlationID and scfID for ETC wil be set separately.

When instructing the SSF to establish a temporary connection to a SRF through an ETC operation, the SCF must provide addressing information to the SSF in regards to the SRF. This information requires:

• the address of the SRF - a routable number
• a correlation ID - that can mean whatever the operators want, but that, according to specification, can be used by the SRF if/when contacting the SCF in order to associate the SSF -> SCF dialogue with the SRF ->SCF dialogue.
• a scfID - an ID for the contacting SCF. This could be used by the SRF to know where to contact the SCF.

The script provides this information in an ETC operation in 2 ways:

• providing all the above information in the assistingSSPIPAddress. This is done by concatenating the SRF number, correlation ID and scfID -according to an agreement between the SSF and SCF operators. The script simply concatenates these parameters, putting between them the configured separator.
• providing the information in 3 separated parameters:
  • assistingSSPIPAddress - the SRF Number
  • correlationID - the script will set this parameter to either the melody ID or the called party number, encoded in hexified BCD form.
  • scfID - the script will set this parameter to the hexified BCD form of the SCP's GT number.

Listed bellow are the parameters that need to be configured for the gsmSRF number:

• $srfNumber - string. It specifies a number at which the gsmSRF is found.

• $srfSeparator - string. Digit(s) used as separator between SRF number, correlationID and sfcID when the assistingSSPIPAddress contains all of them.

• $srfNumber_qualifier - string. It specifies the GenericNumber qualifier. It can be one of the following values:
  • dialed-digits
  • called-additional
  • caller-failed
  • caller-not-screened
  • terminating
  • connected-additional
  • caller-additional
  • called-original
  • redirecting
  • redirection

• $srfNumber_complete - boolean. It specifies whether the called number is complete or not. It should be complete.

• $srfNumber_nature - string. Nature of number. It can have one of the following values:
  • unknown
  • international
  • national
  • network-specific
  • subscriber
  • reserved
  • abbreviated
  • extension-reserved

• $srfNumber_plan - string. It's the used numbering plan. It can have one of the following values:
  • unknown
  • isdn
  • data
  • telex
  • land-mobile
  • isdn-mobile
  • national
  • private
  • extension-reserved

• $srfNumber_restrict - string. It specifies the presentation of the number. Possible values are:
  • allowed
  • restricted
  • unavailable
  • no
  • false
  • yes
  • true

• $srfNumber_screened - string. It specifies the screening indicator for the number. Possible values are:
  • user-provided
  • user-provided-passed
  • user-provided-failed
  • network-provided
  • no
  • false
  • yes
  • true

• 11. $shortTimer, $mediumTimer, $longTimer - integer. Timeout values for operations. Some operation have short timeouts, other medium or long times. These parameters configure their values. These default to 3,6 and 9 seconds respectively. In case of larger delays on the network, they should be increased.

• 12. $maxPhase - integer.Represents the maximum CAMEL phase allowed for CAMEL interaction. If not set, it will default to 4, meaning that all supported CAMEL phases are allowed.

• 13. $msStateNotAllowed - array. List of states received for the subscriber in IDP for which the SCP will abandon CRBT handling and will continue with the call. Recognized values are:
  • assumedIdle
  • camelBusy
  • netDetNotReachable
  • notProvidedFromVLR

It has no default, meaning that it will do CRBT handling ignoring the subscriber state.

• 14. $noAnswerTimer - integer. Timer value to be set when arming o/tNoAnswer. If not configured, this value will not be provided by RRBE. If set, the SSF should report a noAnswer DP after the timer value has expired and no other event was armed.

• 15. $prearrangedEndOn - array. List of DP events reported as notifications that should determine a prearranged end situation. The listed events should match events listed for BCSMs in camel_map module (see s_eventTypeBCSM[] in camel_map.cpp). In no events are listed, basic termination will be assumed for all DPs that represent an end to the TCAP dialogue.

Note - The following parameters need not be set usually:

• $host, $port - set only if you intend to use TCP communication.
• $transTimeout
• $sendAll
• $shortTimer, $mediumTimer, $longTimer
• $maxPhase
• $msStateNotAllowed
• $prearrangedEndOn - if there is no prearranged end agreement between operator, this doesn't need to be configured.

• 16. $mynum - string. GTT number assigned to this SCP.

Yate side

On the Yate side, the camel_map module must be configured through camel_map.conf.

For functionality provided through a TCP socket, a @@[tcap name]@@ section should be configured. A section looks like this:

 [tcap camel] -- what comes after tcap will be the name of the translator
 ;enable=no -- enable this translator
 tcap=tcap-test-itu -- TCAP to be used by the translator for SS7 network communication, a section with that name should be configured in ysigchan.conf
 host=0.0.0.0 -- address on which to listen for incoming applications
 port=16101 -- port on which to listen for incoming applications
 type=CAMEL -- type of translator (MAP/CAMEL). For the intended case, CAMEL should be set
 print-messages=true -- whether or not to print TCAP and XML messages in the logs
 add-encoding=false -- whether to add encoding attribute to data translated to XML

For functionality through Yate messages, an additional section, named @@[local appName]@@ should be configured:

 [local camelLocal] - what comes after local will be the name of the application
 ;enable=no -- enable this application
 translator=camel - which translator should be used. A section named [tcap translatorValue] should be present in the config file.
 capabilities=Camel - capabilities supported by this application. CAMEL translator have only one capability and that is Camel.
 export_xml_as=both - how to export the XML part: string, object or both?

Note:
* setting port to 0 will disable the support for TCP applications
* the name of the local application should match the name set in $appName for the script

Behaviour

Script behaviour

This is a global script that awaits dialog beginnings from SSFs and it is able to handle CAMEL phases 2, 3 and 4. The phase used for handling the call will be determined using the information provided in the InitialDP operation using the following rules:

• first, an application context check will be done. As seeing that every phase has a different context assigned, phase will be first determined at this stage.
• if the application context determined a phase 4 handling, in the handling of the InitialDP operation these additional checks will be made:
  • the value for supportedCamelPhases will be checked. In this parameter, the MSC advertises the CAMEL phases that it can handle. From that list, the SCP will choose the highest phase advertised.
  • the value for offeredCamel4Functionalities will be checked. SCP will verify that all the CAMEL 4 functionalities required for doing CRBT handling in phase 4 are supported. If that is not so, the SCP will downgrade the phase to phase 2 as seeing that the presence of this parameter implied phase 4 functionality and phase 4 functionality implies, by convention, prior phases support also.

In case of phase 1 detection, the SCP will end the dialogue either with an Abort with application-context-not-supported, either with a Continue operation for CAMEL.

An configuration parameter was added ($maxPhase) - mainly for testing purposes - in order to limit what phase the SCP will accept.

Bellow there is detailed description of how the script will act in different scenarios.

Behaviour CAMEL phase 4

Normal procedure for dialogue

In case of a normal, error free dialogue, things will proceed according to the describing flow below:

      SSF                                                                                   SCP
 1.    --------------------- IDP(serviceKey,termAttemptAuth) -------------------------------->
 2.    <-------------------- RRBE (tAbandon,leg1) --------------------------------------------
 3.    <-------------------- DL (leg2) -------------------------------------------------------
 4.    --------------------- DL Result ------------------------------------------------------>
 5.    <-------------------- ICA (CS2,leg3) --------------------------------------------------
 6.    --------------------- ICA Result ----------------------------------------------------->
 7.    <-------------------- RRBE (oTermSeized,oBusy,oAnswer,oNoAnswer,routeFailure,leg3) ----
 8.    <-------------------- CWA (leg3)-------------------------------------------------------
 9.    --------------------- ERBE (oTermSeized,leg3) ---------------------------------------->
 10.   <-------------------- CWA (leg3) ------------------------------------------------------
 11.   <-------------------- ETC (CS1) -------------------------------------------------------
 12.   --------------------- ERBE (oAnswer,leg3) -------------------------------------------->
 13.   <-------------------- DFCWA (CS1) -----------------------------------------------------
 14.   <-------------------- ML (leg3) -------------------------------------------------------
 15.   --------------------- ML Result ------------------------------------------------------>
 16.   <-------------------- CWA (leg3) ------------------------------------------------------
 17.   <-------------------- CWA (CS1) -------------------------------------------------------

In case of busy received from the called party, the call flow is:

 1.  --------------- ERBE (oCalledPartyBusy, leg3, cause) ---------------------->
 2. <-------------- RC (cause received in ERBE/Busy) --------------------------

Abnormal procedures

The following schematics will describe the behaviour of the script in certain scenarios. The numbers assigned above (in the normal dialogue schematic) designate states in the dialogue. These will be used to describe a starting state for when an error is detected.

Initial DP ServiceKey mismatch / DP mismatch

      SSF                                                                                   SCP
       --------------------- IDP(serviceKey,oTermAttemptAuth) ------------------------------->
       <-------------------- ReturnError(unexpectedDataValue) --------------------------------

Initial DP missing parameters

      SSF                                                                                   SCP
       --------------------- IDP(serviceKey,oTermAttemptAuth) ------------------------------->
       <-------------------- ReturnError(missingParameter) -----------------------------------

1.2.3 Application context mismatch

      SSF                                                                                   SCP
       --------------------- IDP(serviceKey,oTermAttemptAuth) ------------------------------->
       <-------------------- U_Abort (user-application-context-name-not-supported) -----------

Receiving an unsupported CAMEL phase

This error can be detected upon receiving an InitialDP operation, or in the ReturnResult for InitiateCallAttempt. Depending upon the state when the error is detected, handling will be done as described below:

      SSF                                                                                   SCP
    1. --------------------- IDP(serviceKey,oTermAttemptAuth) ------------------------------->
       <-------------------- Continue --------------------------------------------------------

      SSF                                                                                   SCP
    6. --------------------- ICA Result ----------------------------------------------------->
       <-------------------- ReleaseCall -----------------------------------------------------

1.2.5 Errors received from SSF / Timeout detected for class 1 and 3 operations

The following schematics describe general error procedures when a error is reported by the SSF or when a result for an operation is not received in the specified time allotted for the operation.

      SSF                                                                                   SCP
                 SCP can be in either of the states : 1 / 2 / 3   
       <-------------------- Continue --------------------------------------------------------

      SSF                                                                                   SCP
                 SCP can be in either of the states : 4 / 5 / 13/ 14   
       <-------------------- ReleaseCall --------------------------------------------------------

      SSF                                                                                   SCP
                 SCP can be in either of the states : 6  - 11  
   14.  <-------------------- MoveLeg --------------------------------------------------------

Behaviour CAMEL phase 2/3

Normal procedure for dialogue

The following diagrams will detail the operation of the CRBT script in case of normal, error free phase 2/3 handling.

       SSF                                                                                    SCP
    1. -------------------------- IDP (serviceKey, termAttemptAuth) --------------------------->
    2. <------ RRBE (leg1,tAbandon) & (leg2,tBusy,tAnswer,tNoAnswer)----------------------------
    3. <------------------------- ETC ----------------------------------------------------------
    4. <------------------------- CONT ---------------------------------------------------------
    5. -------------------------- ERBE (leg2,tAnswer) ------------------------------------------
    6. <------------------------- DFC ----------------------------------------------------------
    7. <------------------------- CONT ---------------------------------------------------------

Abnormal procedures

Situations described in sections 1.2.1 - 1.2.4 shall also apply here.

Errors received from SSF

      SSF                                                                                   SCP
                 SCP can be in either of the states : 2 / 3   
       <-------------------- Continue --------------------------------------------------------