(Page 1 of 1 in this chapter)

Chapter 8

Demonstration Program

8.1 Introduction
8.2 Functional Overview
8.3 Running inoutcta
8.3.1 Hardware Requirements
8.3.2 Software Requirements
8.3.3 Compiling the Demonstration Program
8.3.4 Launching the Demonstration Program
8.3.5 Demonstration Program Options
8.4 Program Structure and Coding Features
8.4.1 The main Function
8.4.2 Opening the Driver, Context and Protocol
8.4.3 MyReceiveCall and MyPlaceCall
8.4.4 MyReceiveCall
8.4.5 MyPlaceCall
8.5 UNIX Variations

8.1 Introduction

This chapter describes the functionality and structure of the inoutcta demonstration program supplied with your protocol software package. This program demonstrates the operation of various CAS TCPs, either on a live trunk (placing and receiving calls while connected with the PSTN) or through the MVIP bus (for testing purposes), and provides an example of C code implementation of a two-way trunk application (that can both place and receive calls) using an NMS telephony API.

This chapter also describes the demonstration programs used with an MFC-R2 TCP. However, the application code for other digital TCPs is very similar. Several other TCPs are also addressed in the code.

8.2 Functional Overview

To place and receive calls, inoutcta uses digital CAS protocols such as the
MFC-R2 TCP mfc0.tcp. This TCP can handle inbound calls, receive a dial command, and seize the line for an outbound call. Optionally, the demonstration program can act either as a purely inbound or as a purely outbound application, for use on one-way lines.

When the demonstration program is invoked, it does the following:

  1. It loads the user option parameters that the TCP will use. To do so, it loads and parses the parameter file provided with the product.

    

  2. It starts the TCP specified on its command-line, configuring it using the parameters loaded in step 1.
    

    

  3. It either places a call or waits for one, depending on the -i command line argument.
    

    

  4. If commanded to dial out (outbound behavior), it dials either automatically or interactively, depending on the -i command line argument.
    

    

  5. If the demonstration program is commanded to wait for a call (inbound behavior):
    

      

    

  6. It waits for incoming calls.
    

    

  7. When a call is received, the program prints out the received call information. If so instructed by the user, it accepts the call through one of the standard call acceptance procedures. If the call is accepted by playing silence or ring, the user has the option to press a key on the keyboard to answer or reject the call.
    

    

  8. After the accepting phase is completed, the program checks the first digit of the incoming number. If the digit is an 8, it rejects the call and plays a busy tone. If the digit is a 9, it rejects the call, and plays a reorder tone. If the digit is a 0, it rejects the call and plays a Special Information Tone (SIT). After rejecting the call, the program returns to waiting for a call.
    

    
Note:  These digits are assigned in the code with a preprocessor directive. You can change them, for example, in a test environment where the demonstration program is connected to a line with an address starting with 8, 9, or 0.


  9. If the first digit of the incoming call is not an 8, 9, or 0, the program answers the call by playing a specified number of rings, then connecting the call.
    

    

  10. The program speaks the digits received.
    

    

  11. The program plays another prompt asking the user for a DTMF specifying the action to take next: playing a voice file, recording a voice file, or hanging up.
    

    

  12. The program starts the DTMF detector and waits for a tone. If the tone does not arrive, it hangs up.
    

    

  13. If the tone arrives, the demonstration program performs the action that the tone specifies, then hangs up.
    

    
 
    




  • If the demonstration program seizes the line first (outbound behavior), the program does the following:
    

      

    

  • It dials the number specified by the user.
    

    

  • When the call is answered, it starts recording.
    

    

  • When silence is detected, it stops recording and plays the DTMF tone meaning "record" for its inbound counterpart (for back-to-back operations).
    

    

  • The program starts playing back the newly recorded voice file.
    

    

  • When playing is completed, it hangs up.
    

    


    

    The demonstration program hangs up if the caller hangs up at any time. If a verbose flag is set, the demonstration program displays the CT Access messages it receives on the screen.
    


    The following table lists the interactions between two inoutcta applications in which one acts as an inbound application, and the other as an outbound application:
    

  

    


    
 Outbound
    

    		
 
    

    		
 Inbound
    


    
 Place call
    

    		
 
    

 
    

    		
 Wait for call 
    

 Optionally, may accept the call
    


    
 Get connected
    

    		
 
    

    		
 Answer call
    


    
 Record
    

    		
 
    

    		
 Speak prompt and digits
    


    
 Send DTMF
    

    		
 
    

    		
 Detect DTMF
    


    
 Play back recorded file
    

    		
 
    

    		
 Record voice
    


    
 Wait for hang up, or hang up
    

    		
 
    

    		
 Wait for hang up, or hang up
    



    


    

    

    

    


    The demonstration program supports both the one-context-per-process CT Access programming model, and the multi-threaded model with one context per thread. The functionality does not change in either case (the table above still applies).
    

 
    

    • 

    


    8.3	 Running inoutcta
    

    


    This section describes the system requirements for running the demonstration program, and how to compile, run, and use inoutcta.
    

    

    

    8.3.1	 Hardware Requirements
    

    


    inoutcta can work with any AG board with a processor and DSPs (AG-T1, 
    AG-E1, AG-24, AG-30, AG-48, AG-60, AG-8, AG Quad). 
    

Note:  Not all TCPs supported by the demonstration program will work with all AG boards.


    When used with Digital CAS TCPs, inoutcta does not perform MVIP switching. For this reason, a board with an MVIP switch is not required.
    

    

    

    8.3.2	 Software Requirements
    

    


    To compile and use the demonstration program you need the following:
    

    

    

    8.3.3	 Compiling the Demonstration Program 
    

    


    To compile inoutcta, do one of the following:
    

  

    


    
 Under this OS...
    

    		
 Go to this directory...
    

    		
 Enter...
    


    
 NT
    

    		
 c:\nms\ctaccess\demo\inoutcta
    

    		
 nmake
    


    
 OS/2
    

    		
 c:\nms\ctaccess\demo\inoutcta
    

    		
 makedemo
    


    
 UNIX
    

    		
 /opt/nms/ctaccess/demo/inoutcta
    

    		
 make
    



    


    

    

    

    

 
    

Note:  This assumes you are running the appropriate C development environment.


    For more information, see the readme file that came with the protocol software package.
    

    

    

    8.3.4	 Launching the Demonstration Program 
    

    


    To launch the demonstration program:
    

      


    1. Set up your AG configuration file to describe your board and software configuration. For more information, see Chapter 4.
      

      

    2. Run agmon to make your AG configuration file changes effective.
      

      

    3. To start the demonstration program, enter the following at the command line:
      

         inoutcta [options]
      

    


    Refer to the Section 8.3.4 for information about inoutcta options.
    

 
    

    

    

    8.3.5	 Demonstration Program Options
    

    


    inoutcta options include the following:
    

 General Options
    

  

    


    
 Option
    

    		
 Description
    


    
 -?
    

    		
 Displays a help screen, and terminates.
    


    
 -b board_#
    

    		
 AG board number. Default: board 0
    


    
 -d
    

    		
 Use the TCP's default parameters without loading a country-specific parameter file.
    


    
 -l law
    

    		
 The companding law used in the network (A or M). Default = A (A-law - applies to ISDN only
    


    
 -P protocol
    

    		
 Name of TCP to use. protocol can be any of the following:
    

 eam0      TCP for Pulsed E and M protocol
    

 mfc0            TCP for MFC-R2 bidirectional protocol (default)
    

 euc0            TCP for European digital CAS protocol
    

 iwk0            TCP for International Wink Start protocol
    

 ss50              TCP for Signalling System 5 protocol
    

 r150             TCP for System R1.5 protocol (inbound)
    

 r151             TCP for System R1.5 protocol (outbound)
    


    
 -P
    

    		
 User PREFERRED mode (default = EXCLUSIVE). Applies to ISDN only.
    


    
 -s n:m
    

    		
 MVIP stream:timeslot. Default: 18:0
    


    
 -t timeslot
    

    		
 This option causes the application to exploit the multithreaded CT Access programming model. Two threads are created that talk to each other. The first thread uses the command line options you specify when launching the program. The second uses a complementary protocol, and the timeslot you specify (default = 1). This option is not available under SCO UNIX, which does not support multi-threading.
    


    
 -u
    

    		
 Send user-to-user information. Applies to ISDN only.
    


    
 -v level
    

    		
 Verbosity level of messages printed on screen. level can be any of the following:
    

 0                         Display error messages only.
    

 1                          Display errors and unexpected high-level events.
    

 2                         Display errors and all high-level events (default).
    

 3                          Display errors and all events.
    



    


    

    

    

    

 Inbound Options
    

  

    


    
 Option
    

    		
 Description
    


    
 -a mode
    

    		
 Accept the inbound calls before answering or rejecting:
    

 mode = 1 : accept and play ring back
    

 mode = 2 : accept and remain silent until further command
    

 mode = 3 : accept with user audio and play a voice file
    

 mode = 4 : accept with user audio and detect DTMFs
    


    
 -B rate
    

    		
 Rate of billing
    

 rate = 0     : free call
    

 rate = N : N cents a minute (ISDN) or normally billed call (CAS)
    


    
 -g
    

    		
 Emulate a gateway application. The user controls the timing of the incoming call being accepted or rejected.
    


    
 -i
    

    		
 Enable interactive dialing (valid for outbound or trunk protocols only).
    


    
 -r rings
    

    		
 Number of ring tones to play before answering a call (default = 2)
    



    


    

    

    

    

 Outbound Options
    

  

    


    
 Option
    

    		
 Description
    


    
 -n number_to_dial
    

    		
 For outbound or inout protocols only. Default: 123
    

 number_to_dial must be formatted appropriately for the TCP.
    



    


    

    

    

    

    

    

    8.4	 Program Structure and Coding Features
    

    


    inoutcta is based on the asynchronous programming model implemented by CT Access. One example is ctaGetParms, a function that queries the environment to retrieve a specified parameter category. Other function calls in the program are found in the CTADEMO library supplied with CT Access to provide users with examples of how to use the APIs. 
    


    CTADEMO functions have names starting with Demo. One example is DemoReleaseCall, which uses adiReleaseCall and then waits for the result of the call (either SUCCESS or DISCONNECT) before returning. Most CTADEMO functions are wrappers that enclose the corresponding adi function and wait for an event to terminate the function, either by signaling that the function was successful or by signaling a failure. In this way, they transform an asynchronous wait for an event into a synchronous function call.
    

    

    

    8.4.1	 The main Function
    

    


    The main function of inoutcta first defines the list of CT Access service managers that the application will need. Then it parses its command line arguments, and assigns the corresponding values to its variables. Then it checks that the TCP the user has specified is supported. All of the standard CT Access TCPs are supported by the application, in addition to the TCPs discussed in this manual. The function also checks that none of the user options are inconsistent with each other, and warns the user if it finds a problem. Then it registers an error handler with CT Access and starts CT Access.
    


    main launches the demonstration loop in one of two ways, depending on whether -t (the use threads option) is specified on the command line. If the -t option is not specified, the demonstration program simply calls the RunDemo function. Otherwise, the demonstration program launches RunDemo twice with different parameters, as two separate threads that continuously place calls to each other.
    

 
    

    

    

    8.4.2	 Opening the Driver, Context and Protocol
    

    


    In inoutcta, RunDemo defines the list of CT Access services needed by the thread. Then it calls DemoOpenPort, a function from the CTADEMO library. DemoOpenPort opens the CT Access application queue, attaching all defined service managers. It then creates a CT Access context and opens the defined services on the new queue.
    


    Next, RunDemo checks whether the protocol specified on the command line is one of those which allow that user option parameters to be loaded. If such parameters are allowed, RunDemo calls DemoLoadParameters, a function from the CTADEMO library. DemoLoadParameters loads a parameter file, containing parameters to configure the TCP for its specific implementation. Parameter files are found in the following locations:
    

    

    If the parameter file is not found, RunDemo uses the TCP's default values.
    


    Next, RunDemo modifies one or more parameters in the standard ADI start parameter structure. To do so, it uses ctaGetParms to retrieve the current ADI default, and then explicitly sets the parameter mentioned below. It then starts the TCP on the opened CT Access context. To do so, it calls adiStartProtocol with:
    

    

    The two CT Access parameters that are changed are:
    

    

  • adi.start.callctl.mediamask
    
    This parameter tells the TCP what functions are to be started and ready for 
the application to use in conversation state. Functions that can be started by 
the TCP include DTMF detection, energy detection, silence detection, and 
echo cancellation.

    

    
 
    

 Starting Protocols on AG Quad Boards
    

    

    In configurations that run on AG Quad boards and require resource management, the TCPs cannot start detectors and services to be ready to use in the conversation phase of the call. This is due to the restrictions imposed by resource management on these boards. 
    


    When calling adiStartProtocol, the mediamask value in the ADICALLCTL_PARMS substructure (within the ADICALLCTL_PARMS structure) must be set to zero for AG Quad boards. If the value is not zero, when adiStartProtocol is called, the TCP will fail to start. In this case, the application receives the event ADIEVN_STARTPROTOCOL_DONE with a reason field ADIERR_NOT_ENOUGH_RESOURCES.
    


    The inoutcta demonstration program looks at the ADIEVN_STARTPROTOCOL_DONE reason field. If the program finds the reason ADIERR_NOT_ENOUGH_RESOURCES, it sets mediamask to zero and starts the protocol again. In addition, since DTMF detection is not started on the board when the call is connected, the program sets a global flag to start DTMF detection once the connected state is reached.
    

Note:  These restrictions only apply when the AG Quad board is configured with all four trunks enabled. If the AG Quad board is used as a Dual board, no special restrictions apply.


    For more information about AG Quad board resource management refer to the AG Quad Installation and Developer's Manual.
    

 
    

    • 

    

    8.4.3	 MyReceiveCall and MyPlaceCall
    

    


    Once the protocol is started on the board, depending on the type of TCP, RunDemo is ready to accept incoming calls or dial outgoing calls. The inbound call loop is very simple: the function MyReceiveCall is invoked repeatedly. This function performs all call control, and hangs up the line when the call is completed. 
    


    If the TCP is a purely outbound one, able only to place outgoing calls, the loop does the following:
    

    

    If the TCP is bidirectional, the loop behaves almost in the same way it would for an outbound TCP. The main difference is that if a call comes in while the loop is waiting for the user to press a key, the function MyReceiveCall is called, since this is a legal event for a bidirectional trunk.
    

 
    

    

    

    8.4.4	 MyReceiveCall
    

    


    MyReceiveCall does the following:
    

      


    1. Checks to see why it has been invoked.
      

      
If MyReceiveCall was invoked because an incoming call was detected while the program was waiting to place an outgoing call, there is no need to wait further for a call. MyReceiveCall queries CT Access to get information about the incoming call, by invoking adiGetCallStatus. The information includes the following:
      
  

      


      
 Information 
      

      		
 Description
      


      
 called number
      

      		
 Called number digits.
      


      
 calling party number
      

      		
 ANI digits.
      


      
 calling name
      

      		
 Calling party name.
      


      
 user category
      

      		
 Shows the user category of the calling party (i.e., normal subscriber, operator, test equipment).
      


      
 toll category
      

      		
 Usually the same as the user category, but in some countries it can have a different meaning (toll category). 
      


      
 calling number type
      

      		
 Type of calling user.
      


      
 redirecting number
      

      		
 Redirecting number.
      


      
 reason for redirection
      

      		
 Reason for redirection.
      


      
 originally called number
      

      		
 First called line identity.
      


      
 calling number presentation indicator
      

      		
 The ANI digits might not be available, because of interworking of different protocols with different features in the call path, or ANI presentation might be restricted. 
      

 This value is used even when no ANIs are present, when the TCP does not support ANI reception, and when the TCP's parameters specify that ANIs are not requested.
      

 Possible values include:
      

 0 = calling number presentation allowed (default)
      

 1 = calling number presentation restricted
      

 2 = calling number not available
      



      


      

      

      

      

      
These attributes are stored in a data structure ADI_CALL_STATUS. Fields filled in vary depending on a protocol and a country. For more information see Section 8.2, and Appendix C.
      
If a purely inbound TCP is active and MyReceiveCall is called, or if the TCP signals to the application that the line has been seized and that call setup has begun, then the application must wait for the incoming call setup to be completed. The function does so by waiting for the appropriate event (ADIEVN_INCOMING_CALL). Once this event is detected, the function calls adiGetCallStatus to get the digit information as described above.
      
On digital trunks, while waiting for ADIEVN_INCOMING_CALL, MyReceiveCall may receive the ADIEVN_INCOMING_DIGIT event which indicates that a digit has arrived in the queue. MyReceiveCall displays a message to the screen that indicates the digit. 
      
MyReceiveCall may also receive an ADIEVN_CALL_DISCONNECTED, indicating that the calling party has hung up. MyReceiveCall jumps to the label hangup_in to hang up the call.
      

    2. On digital trunks MyReceiveCall can optionally set the billing rate of the incoming call. This is not supported by all CAS protocols. See Appendix B for details. The TCP replies with one of the following:
      

        

      • ADIEVN_BILLING_SET: The billing rate has been set. See the value 
field to check if the network accepted the requested billing rate.

        

        

      • ADIEVN_PROTOCOL_ERROR: The protocol does not support the set 
billing operation.

        

        

      • ADIEVN_SEQUENCE_ERROR: The protocol supports the set billing 
operation, but the operation was requested at a time when it was no 
longer allowed by the protocol, for instance after the call was accepted 
(with the default billing indication).

        

        
 
        

        

      • MyReceiveCall can optionally accept the call before answering or rejecting. Three modes of accept are demonstrated:
        

          

        • ADI_ACCEPT_PLAY_RING: Accept the call, and play ring indefinitely. 
This may be important for applications that intend to answer the call, 
but need time to process the information associated with the incoming 
call. This is the only available option for analog loop start TCPs.

          

          

        • ADI_ACCEPT_USER_AUDIO: Accept the call and play a voice 
message on the line. This may be necessary for IVR applications that 
want to explain features of the service offered, without billing the caller. 
An option of this accept mode is also demonstrated, that of detecting 
DTMF tones at this stage. This might not be allowed by the network, as 
typically at accept time the voice path is connected only in one 
direction, from the NMS board to the caller, and not in the other 
direction. This option is not supported for analog protocols.

          

          

        • ADI_ACCEPT_QUIET: Accept the call and remain silent. This option is 
useful for trunk-to-trunk switching applications. This option is not 
supported for analog protocols.

          

          
Note:  On loop start lines, the call is rejected by not answering it. This is the equivalent of using ADI_REJ_PLAYRINGTONE with digital CAS TCPs, and is the only rejection method available for loop start lines.

 
          


        • On digital trunks:  MyReceiveCall answers the call or rejects it in a particular way based on the first digit in the called number. MyReceiveCall uses the definitions from inoutcta.c. to determine when to reject calls.
          

          
  

          


          
 Digit
          

          		
 Action
          


          
 BUSY_DIGIT
          

          		
 Rejects the call. To do so, it calls the CTADEMO function DemoRejectCall, which calls adiRejectCall, directing it to signal that the line is busy. The MFC-R2, MFS, and EAM TCPs do this by sending a special MF tone in the compelled sequence. (Other TCPs use methods that are protocol-specific.) Then DemoRejectCall waits for the event signifying that the caller has hung up (ADIEVN_CALL_DISCONNECTED).
          


          
 REJECT_DIGIT
          

          		
 Rejects the call using DemoRejectCall, directing the TCP to signal that the number called is not allocated.
          


          
 USER_AUDIO_DIGIT
          

          		
 Rejects the call using CustomRejectCall, which plays a Special Information Tone (SIT). CustomRejectCall defines the SIT, and then calls adiRejectCall with the argument ADI_REJ_USER_AUDIO. This tells the TCP to reject the call, and open the DSP resource to the application, so that custom audio can be played on the line. CustomRejectCall plays the defined SIT, and monitors the event queue for ADIEVN_TONES_DONE with reason ADI_REASON_RELEASED, and an ADIEVN_CALL_DISCONNECTED event. When both have been received, the function terminates.
          


          
 None of the above.
          

          		
 Answers the call. To do so, it calls adiAnswerCall with an argument specified by the -r command line option. Default is 2 rings. 
          



          


          

          

          

          

 
          

          
If MyReceiveCall answers the call, it allows the demonstration program to talk either with a human being on a telephone or with a corresponding outbound application. MyReceiveCall performs the following operations:
            

          • Plays voice files announcing the called number and the calling number, 
if available. Applies to digital trunks only. 

            

            

          • Plays another voice file with a menu, prompting the user to enter a 
DTMF tone from the keypad to do one of the following: record a voice 
file, play a previously recorded voice file, or hang up.

            

            

          • To play voice files, it calls the CTADEMO function MyPlayMessage, which opens a voice file and calls VcePlayList to play it.
            

              

            • Waits for a DTMF tone to be detected. To do so, it calls 
DemoPromptDigit, which sets three-second timeouts between digits, 
and calls adiCollectDigits twice in an attempt to get the digits. If a 
DTMF is not detected, MyReceiveCall hangs up. On an AG Quad 
board, an application must call adiStartDTMFDetector in order to be 
able to detect DTMF digits in the connected state. This is done as soon 
as the demonstration program receives the event 
ADIEVN_CALL_CONNECTED.

              

              

            • If a DTMF digit is detected, MyReceiveCall does what the DTMF tones 
direct it to do, and then hangs up. (If the command was to hang up, it 
hangs up immediately.) If no voice file exists, MyReceiveCall plays a 
default voice file (i.e., there is nothing to play).

              

              
 
              

            

            

            

            8.4.5	 MyPlaceCall
            

            


            MyPlaceCall does the following:
            

              


            1. Tries to place a call to the number that the user specified in the command line.
              

              
To place the call, MyPlaceCall invokes adiPlaceCall with the digits to call, and waits for events. Possible events include:
                

              • ADIEVN_PLACING_CALL: Placing call.

                

                

              • ADIEVN_CALL_PROCEEDING: All digits delivered to the network.

                

                

              • ADIEVN_REMOTE_ALERTING: Outbound ring detected.

                

                

              • ADIEVN_STATUSINFO_UPDATE: Call status message received. 
                
(protocol-specific)

                

                

              • ADIEVN_REMOTE_ANSWERED: Outbound answer detected.

                

                

              • ADIEVN_CALL_DISCONNECTED: Call control is in Disconnected 
state.

                

                

              • ADIEVN_CALL_CONNECTED: Call control is in Connected state.

                

                

              •  When the call is connected, MyPlaceCall starts recording whatever is on the line, waiting for a period of silence to stop recording. This operation is designed both to interact with a human being ("Hello") and to interact with the MyReceiveCall function, which speaks a little longer.
                

                
To record the voice on the line, MyPlaceCall calls vceRecordMessage.
                

              •  If silence is detected, MyPlaceCall first sends a DTMF tone, by invoking adiStartDTMF. This is strictly to interact with MyReceiveCall: the DTMF tone is the one that tells it to start recording.
                

                

              •  MyPlaceCall invokes MyPlayMessage to play back what was just recorded. When playback is finished, MyPlaceCall calls DemoHangUp to hang up.
                

                

              • On digital trunks, if billing pulses are detected, MyPlaceCall displays a message for each pulse, with a pulse count (if billing pulse detection is enabled).
                

              

              

              

              8.5	 UNIX Variations
              

              


              The demonstration programs differ slightly when compiled and run under the two different UNIX systems supported by the development package.
              

              

              


              


              

              

              


              
 
    (Page 1 of 1 in this chapter)
              


              
 



              
tech_support@nmss.com

              

Copyright © 1998, Natural MicroSystems, Inc.   All rights
reserved.