Chapter 27

TAPI Behind the Scenes--The TELEPHON.INI File


CONTENTS


In this chapter you'll learn how the TAPI system uses entries in the TELEPHON.INI file to determine what TAPI service providers are installed, how to handle outbound dialing rules, the current dialing location, and which providers are to be used for TAPI service requests.

Almost all of this information is updated from the various configuration dialog boxes available through calls to TAPI functions. As part of this chapter, you'll build a short program that calls the TAPI Line dialog boxes and allows you to inspect the resulting changes to the TELEPHON.INI file.

Building the TAPI Dialog Utility Program

Before getting into the details of how the TELEPHON.INI file is used for TAPI services, let's build a short Visual Basic program that gives you easy access to the TAPI dialog boxes that affect the file, and a quick TELEPHON.INI viewer.

Note
If you do not have Visual Basic on your machine or you want to skip over this section, you can find the completed program (TAPIDLG.EXE) on the CD-ROM that comes with this book. You can use this compiled version of the program to follow along with the rest of the chapter.

Creating the TAPI Dialog Utility project takes only a few controls and a small amount of code. The following two sections of the chapter will walk you through the details of building this handy utility.

Laying Out the TAPI Dialog Utility Form

Start by loading Visual Basic 4.0 and creating a new project. Next, you need to lay out the form. Refer to Table 27.1 and Figure 27.1 as guides. Be sure to load the TAPILINE.OCX into your toolbox before you start coding. Also, make sure you add the frame control before you add the option buttons, and paint the option buttons within the frame control. That way they will be registered as child controls of the frame.

Figure 27 1 : Laying out the TAPI Dialog Utility project

Tip
If you plan to do a lot of coding with the TAPILINE control, add it to your startup project. Open AUTO32LD.VBP (or AUTO16LD.VBP) and add the TAPILINE control. Then save the project. Now every new project you create will have the TAPILINE control in the toolbox.

Table 27.1. Controls for the TAPI Dialog Utility project.
ControlProperty Setting
VB.Form Name Form1
 Caption "Form1"
 Height 2670
 Left 1530
 Top 1770
 Width 5685
VB.CommandButton Name cmdButton
 Caption "&Telepho.ini"
 Height 495
 Index 2
 Left 60
 TabIndex 8
 Top 1620
 Width 1215
VB.ListBox Name List1
 Height 1035
 Left 60
 TabIndex 6
 Top 420
 Width 2595
VB.CommandButton Name cmdButton
 Caption "&Apply"
 Height 495
 Index 1
 Left 4200
 TabIndex 5
 Top 1680
 Width 1215
VB.CommandButton Name cmdButton
 Caption "E&xit"
 Height 495
 Index 0
 Left 2820
 TabIndex 4
 Top 1680
 Width 1215
VB.Frame Name Frame1
 Caption "Dialog Selection"
 Height 1395
 Left 2820
 TabIndex 0
 Top 120
 Width 2595
VB.OptionButton Name optDialog
 Caption "Line Configure Provider"
 Height 195
 Index 2
 Left 120
 TabIndex 3
 Top 960
 Width 2295
VB.OptionButton Name optDialog
 Caption "Line Configure Dialog"
 Height 195
 Index 1
 Left 120
 TabIndex 2
 Top 660
 Width 2295
VB.OptionButton Name optDialog
 Caption "Line Translate Dialog"
 Height 195
 Index 0
 Left 120
 TabIndex 1
 Top 360
 Width 2295
VB.Label Name Label1
 BorderStyle 1 'Fixed Single
 Caption "TAPI Line Devices:"
 Height 255
 Left 60
 TabIndex 7
 Top 120
 Width 2595
TapilineLib.Tapiline Name Tapiline1
 Left 1980
 Top 1680

Once you complete the layout of the dialog box, save the form as TAPIDLG.FRM and the project as TAPIDLG.VBP. Now you're ready to add code to the form.

Coding the TAPI Dialog Utility Project

There isn't much code to add here, just a few lines to initialize TAPI and then some code to respond to user selections on the option buttons, command buttons, and the list control.

First, add a new subroutine called StartTAPI to the form. This will hold the code that initializes the TAPI session and confirms the available devices. Listing 27.1 shows the code for the StartTAPI routine. Add this to your project.


Listing 27.1. Adding the StartTAPI routine.
Public Sub StartTAPI()
    '
    ' start up tapi
    '
    Dim lRtn As Long
    Dim x As Integer
    '
    ' init tapi
    lRtn = Tapiline1.LineInitialize(App.EXEName)
    If lRtn <> 0 Then
        MsgBox "Unable to Start TAPI!", vbCritical
        Unload Me
    End If
    '
    ' get devices
    For x = 0 To Tapiline1.NumDevices - 1
        Tapiline1.LineNegotiateAPIVersion x, 65536, 65540
        List1.AddItem "TAPI Line #" & CStr(x)
    Next x
    '
End Sub

As you can see, this routine just calls the lineInitialize method, gets the total number of devices, and then performs the lineNegotiateAPIVersion method for all the available TAPI line devices. In the process, the line devices are loaded into the list box for the user.

Next you need to add some code to the Form_Load event. This code is executed when the program first starts. Listing 27.2 shows the code you need to add to your project.


Listing 27.2. Adding the Form_Load event code.
Private Sub Form_Load()
    '
    Me.Caption = "TAPI Dialog Utility"
    Me.Left = (Screen.Width - Me.Width) / 2
    Me.Top = (Screen.Height - Me.Height) / 2
    '
    StartTAPI
    '
End Sub

The code in the Form_Load event sets the form caption, centers the form, and then calls the StartTAPI routine to initialize TAPI services.

The really important code is in the cmdButton_Click event. This is the code that handles the user's dialog box selections. Listing 27.3 shows the code needed for the cmdButton_Click event. Add it to your project.


Listing 27.3. Adding the cmdButton_Click event code.
Private Sub cmdButton_Click(Index As Integer)
    '
    ' handle button selections
    '
    Dim lRtn As Long
    Dim nLine As Integer
    '
    ' get line to work with
    nLine = List1.ListIndex
    If nLine = -1 Then
        nLine = 0
    End If
    '
    ' get button selection
    Select Case Index
        Case 0 ' exit
            Tapiline1.LineClose
            Unload Me
        Case 1 ' start dialog
            '
            ' call line translate
            If optDialog(0) = True Then
                Tapiline1.LineTranslateDialog nLine, Me.hWnd, "+1 (606)555-1212"
            End If
            '
            ' call line config
            If optDialog(1) = True Then
                Tapiline1.LineConfigDialog nLine, Me.hWnd, "tapi/line"
            End If
            '
            ' call provider config
            If optDialog(2) = True Then
                Tapiline1.PermanentProviderID = 1
                Tapiline1.LineConfigProvider Me.hWnd
            End If
        Case 2 ' load telephon.ini w/ notepad
            lRtn = Shell("notepad.exe c:\windows\telephon.ini", 1)
    End Select
    '
End Sub

Tip
If you do not have a copy of NOTEPAD.EXE, or it is in some directory other than your Windows directory, change the Shell call in Listing 27.3 to point to your favorite ASCII editor.

The first few lines of code make sure one of the line devices in the list box has been selected. If not, it automatically selects the first one in the list. Next, the SELECT CASE statements determine which button has been pressed.

If the Exit button was pressed, the program executes the lineClose method before unloading the form. This is not strictly needed, since this project does not open any available line devices. However, it is a good practice to release any remaining TAPI resources before exiting.

If the user selects the Apply button, the program checks to see which option button was selected and then calls the requested dialog box. Notice that the call to the Translate dialog box contains an optional dialing address. This will be displayed in the lower left of the dialog box to show the user how the dialing rules will be applied to the selected phone number.

If the user selects the Telephon.ini button, the program launches a shell operation which calls NOTEPAD.EXE and loads the TELEPHON.INI file for viewing. You can use this option to view the results of editing the various settings in the dialog boxes.

The last bit of code to add to the project is a single line behind the List1_DblClick event. This will automatically launch the selected dialog box each time the user double-clicks the item in the list. Add the code shown in Listing 27.4 to your project.


Listing 27.4. Adding the List1_DblClick event code.
Private Sub List1_DblClick()
    '
    cmdButton_Click 1 ' call apply button
    '
End Sub

That's all the code you need. Save this form (TAPIDLG.FRM) and project (TAPIDLG.VBP) and then test it out. When running the project, you should see a list of available line devices in the list box and be able to call up each of the TAPI dialogs for the various devices (see Figure 27.2).

Figure27 2 : Testing the TAPI dialog utility

Once you are sure the program is working correctly, compile it (TAPIDLG.EXE) to disk. You'll use the TAPIDLG.EXE program in the next several sections of the chapter.

The TELEPHON.INI File

The TAPI system uses the TELEPHON.INI file to hold important control parameters. Even though the TAPI system is implemented on Win95 and WinNT, the control values are not stored in the system registry. This is because TAPI was originally deployed as part of the Windows 3.1 operating system. Also, as of this writing, all TAPI service providers (TSPs) are 16-bit applications. For these reasons, the old 16-bit INI file is still used by TAPI.

Most of the TELEPHON.INI file is updated through TAPI dialog boxes. In fact, it is not a good idea to modify the INI file directly, since this may result in invalidating your TAPI installation. Still, you can call up the TELEPHON.INI file using NOTEPAD.EXE (or some other ASCII editor) and view the contents. This is a good way to learn a lot about how TAPI services are managed by the Windows operating system.

Warning
If you are working with the old TAPI 1.3 system on Windows 3.1 machines, your TELEPHON.INI file will look quite different. In fact, you cannot use the TELEPHON.INI file from TAPI 1.3 for TAPI 1.4 installations. Any attempt to do so will cause an error when you try to start any TAPI service. All the material covered here is based on TAPI 1.4 TELEPHON.INI file layouts.

The TELEPHON.INI file is divided into four main sections:

The rest of this chapter reviews each of the four main sections and shows you examples of how to modify the information using the TAPI dialog utility you built earlier in the chapter.

Tip
Now is a good time to load the TAPIDLG.EXE file you created earlier. If you did not enter and compile the program described above, you can find a completed version of it on the CD-ROM, which you can load instead.

TAPI Service Provider Information

The TAPI service provider information is actually stored in two separate sections of the TELEPHON.INI file. The [Providers] section lists all the TSPs installed on the machine. This section gives each of them a unique ID value. Each TSP then has its own section in the TELEPHON.INI file. That section is named based on the provider ID that appears in the [Providers] section. The provider-specific section contains data about the services supported by the TSP and any other TSP-related data for that provider.

TAPI uses this information to initialize all available service providers when the lineInitialize method is first invoked on the workstation.

The Providers Section

The [Providers] section of the TELEPHON.INI file has three main parts:

Listing 27.5 shows how a typical [Providers] section of a TELEPHON.INI file looks.


Listing 27.5. A typical [Providers] section of TELEPHON.INI.
[Providers]
NumProviders=2
NextProviderID=5
ProviderID0=1
ProviderFilename0=unimdm.tsp
ProviderID1=4
ProviderFileName1=esp.tsp

In the example shown in Listing 27.4, there are two TSPs active on the workstation, the UNIMDM.TSP and the ESP.TSP. They are given the provider IDs "0" and "4" respectively. You can see that the next TSP added to the workstation will be given the ID "5." The values in this section are altered by the TSPs themselves.

There is no dialog box from TAPI that makes changes to these settings. Changing these settings manually can cause your system to lock up when you start TAPI services.

The Provider-Specific Section

For each ProviderFileName, ProviderID pair in the [Providers] section, there is a separate section header that bears the ProviderID value. This section contains entries used to describe the properties of the lines and phones supported by the service provider. Listing 27.6 shows the set of provider sections that match the [Providers] section that appears in Listing 27.5.


Listing 27.6. Example provider-specific sections.
[Provider1]
NumLines=1
NumPhones=0

[Provider4]
NumLines=8
NumPhones=4

In Listing 27.6, Provider1 supports only one line device and no phone devices. Provider4 supports up to eight lines and four phones.

The entries shown in Listing 27.6 are the required minimum entries for each provider-specific section. TSPs can also add other values to their sections if they wish. These values could identify individual lines and phones, provide additional configuration settings used by the TSP, and so on. Microsoft suggests TSPs establish a system for identifying line or phone parameters similar to the one used for identifying providers. For example, each line could have an ID and name value along with any special settings. Listing 27.7 shows how this might look in the TELEPHON.INI file.


Listing 27.7. Extended provider-specific entries.
[Provider1]
NumLines=2
NumPhones=1
NextLineID=2
NextPhoneID=1
LineID0=1
LineName1=MCA's Data Line
LinePort1=COM1
LineInitString1=ATH0
LineID1=2
LineName2=Voice Line
LinePort2=COM2
LineInitString2=

Notice the use of the NextLineID and NextPhoneID settings. This will allow the TSP to add future lines or phones with unique values. The additional settings here are related to communications ports and initialization strings, but they could be anything at all that the TSP needs to manage the TAPI service on the line.

The main thing to keep in mind about the provider settings is that they are managed by the Telephony service provider application-not the TAPI.DLL or your own desktop applications. All settings that appear here are the result of actions by the TSPs. You run the risk of trashing your TAPI installation if you meddle with these values!

Handoff Priorities Information

When there is more than one TAPI application registered on the workstation, the TAPI system must have some process for deciding which service request is handled by which TAPI application. The [HandOffProrities] section of the TELEPHON.INI file helps TAPI handle this situation. The [HandOffPriorities] section lists all the applications that can handle inbound and outbound calls. Also, the applications are listed in preference order. The first items on the list should be called before the last items on the list.

Each entry in the [HandOffPriorities] section lists the type of TAPI service request followed by one or more registered programs capable of handling the request. Listing 27.8 shows a typical [HandOffPriorities] section from the TELEPHON.INI file.


Listing 27.8. A typical [HandOffPriorities] section.
[HandoffPriorities]
datamodem=rasapi32.dll,
interactivevoice=AMENGINE.DLL,MSPHONE.EXE,
automatedvoice=AMENGINE.DLL,
RequestMakeCall=C:\PROGRA~1\MICROS~3\MSPHONE.EXE,C:\WINDOWS\DIALER.EXE,

Listing 27.8 shows that the workstation can support four TAPI service request types:

You'll notice that the last entry in the section (RequestMakeCall) shows that there are two different programs on the workstation that can handle the TAPI service request. In this case, when a program makes a call to the RequestMakeCall TAPI function, TAPI will attempt to hand the request to the MSPHONE.EXE application first. If that application does not respond (it is busy with another call or not working properly), then TAPI will attempt to pass the service request to DIALER.EXE.

The [HandOffPriorities] section can contain several different entries, each corresponding to a media mode recognized by TAPI. Listing 27.9 shows a prototype of the [HandOffPriorities] section with all the known media modes and a sample extended media mode listed.


Listing 27.9. A prototype [HandOffPriorities] section.
[HandoffPriorities]
RequestMakeCall=[<appname>[,<appname>]...]
RequestMediaCall=[<appname>[,<appname>]...]
unknown=[<appname>[,<appname>]...]
interactivevoice=[<appname>[,<appname>]...]
automatedvoice=[<appname>[,<appname>]...]
g3fax=[<appname>[,<appname>]...]
g4fax=[<appname>[,<appname>]...]
datamodem=[<appname>[,<appname>]...]
teletex=[<appname>[,<appname>]...]
videotex=[<appname>[,<appname>]...]
telex=[<appname>[,<appname>]...]
mixed=[<appname>[,<appname>]...]
tdd=[<appname>[,<appname>]...]
adsi=[<appname>[,<appname>]...]
digitaldata=[<appname>[,<appname>]...]

Note
TAPI also allows TSPs to define their own media modes and place them in the [HandOffPriorities] section. These settings are important only to those developing TSPs and are not covered in this book. For more on TSPs and extended media modes, you can refer to the Win32 Extensions documentation that ships with Microsoft Visual C++, or versions of the TAPI documentation that appear on the MSDN Professional Level CD-ROMs.

Like the provider section, the values in this section are manipulated by the TAPI applications that are designed to fulfill TAPI service requests. If you develop an application that is designed to process a particular type of media, you can place its name in this section. Most of the examples covered in this book are designed to make TAPI requests, not respond to them. For this reason, you will not be making any changes to the entries in the [HandOffPriorities] section of the TELEPHON.INI file.

Dialing Location Information

The next important section is the [Locations] section. This section holds information on the current location from which the workstation is placing calls. The values here are used to determine how to actually dial the telephone numbers provided to TAPI. For example, TAPI will attempt to determine if the telephone number can be handled using local dialing rules, long distance rules, or international rules.

The TAPI system allows users to define more than one location entry for the workstation. This way, users can move their computer to different locations and not have to reinstall or reinitialize the TAPI location each time. The best example of this is a laptop user who travels to different locations, but still wants to use TAPI services to place and receive calls. When the user arrives at a new location, the TAPI system need only be informed of the current location (and its dialing rules) and all applications will behave as normal, without any changing of phone numbers or dialing rules.

There are three main entries in the [Locations] section of the TELEPHON.INI:

Listing 27.10 shows a typical [Locations] section of the TELEPHON.INI file.


Listing 27.10. A typical [Locations] section.
[Locations]
CurrentLocation=5,3
Locations=4,6
Location0=0,"Default Location","","","606",1,0,0,1,"",0,""
Location1=1,"Office","","","513",1,0,0,0,"",0,""
Location2=3,"Oak Ridge, TN","","","423",1,0,0,0,"",0,""
Location3=5,"Sweden Office","9","8","013",46,1,0,0,"",0,""

The first entry in the section (CurrentLocation) tells TAPI that the current location is location index "5". The second parameter tells TAPI apps that they can find location index "5" by looking at the third location item in the list. This speeds selection of the record.

The second entry in the section (Locations) tells TAPI how many locations are defined here (4) and what the index value of the next location will be ("6"). This is used when adding new locations to the list.

The rest of the entries in the [Locations] section contain information about each defined location for this workstation. Listing 27.11 shows the prototype for all location entries in the TELEPHON.INI file.


Listing 27.11. The Location entry prototype.
Location<index>=<LocationID>,"<FriendlyName>","<LocalPrefix>","<LDPrefix>","<AreaCode>",<CountryCode>,
Â<PreferredCardID>,<CardHint>,<InsertAreaCode>,"<TollPrefixes>",<TonePulseDialing>,
Â<DisableCallWaiting>

Table 27.2 shows the list of parameters in the location line along with a short description of their use and meaning. The parameters are listed in the order in which they appear in the Location entry.

Table 27.2. The Location entry parameters.
ParameterDescription
<LocationID> This is the unique ID value for this location.
<FriendlyName> This is the easy-to-read name for this location (such as "Cincinnati, OH" or "My Home Office").
<LocalPrefix> This is the digit(s) that must be dialed in order to place a local call from the location. This can be used in offices where users must dial "9" to reach an outside line, and so on.
<LdPrefix> This is the digit(s) that must be dialed in order to place a long distance call from the location. This can be used in offices that must gain direct access to long distance lines before placing a call.
<AreaCode> This is the area or city code for the location. This is compared against the requested outbound number to see if long distance must be used to complete the call.
<CountryCode> This is the country code for the current location. This is used to determine whether international dialing rules must be employed to complete the requested outbound call.
<PreferredCardID> This is the calling card that should be used to complete the long distance call.
<CardHint> This is the direct index value of the calling card indicated in the <PreferredCardID> entry. This speeds the collection of the calling card entry data.
<InsertAreaCode> This entry must be set to 1 or 0. If set to 1, the area code will be used when placing calls to phone addresses that have the same area code and have a dialing prefix that appears in the <TollPrefixes> entry for this location (see the following description).
<TollPrefixes> This is a list of three-digit phone address prefixes that require long distance dialing even though they are in the same area code as the current location. In order for TAPI to treat these as toll calls, the <InsertAreaCode> value for this location must be set to 1.
<TonePulseDialing> This value must be set to 1 or 0. If it is set to 0, tone dialing will be used to place calls from this location. If it is set to 1, pulse dialing will be used.
<DisableCallWaiting> This parameter contains the digit(s) that must be dialed to disable call waiting on the line. This can be used to turn off call waiting during data transmission calls in order to prevent loss of data during the call.

Modifying the Location Values with the lineTranslateDialog Method

You can adjust the values for location entries by using the lineTranslateDialog method of the TapiLine control. To test this out, run the TAPIDLG.EXE program and select the Telephon.ini button to view the current settings for the [Location] section. Figure 27.3 shows what your screen might look like at this point.

Figure 27.3 : Displaying the TELEPHON.INI file from TAPIDLG.EXE

Now close the instance of NOTEPAD.EXE (be sure not to save any incidental changes you might have made). Now select the Line Translate Dialog option button and press Apply. This will bring up the Dialing Properties dialog box. You are ready to add a new location entry into the TELEPHON.INI file.

Press the New... button and create a new location. Use the information in Table 27.3 and Figure 27.4 to set the location parameters.

Figure. 27.4 Building a new location

Table 27.3. New location parameters.
Setting NameSetting Value
NameTAPI Book
Area Code999
Local Outside Line Access9
Long Distance Outside Line Access8
Disable Call Waiting1170
Dialing MethodTone Dialing

After you enter and save the new location data, press the Telephon.ini button to bring up the TELEPHON.INI file. Find the new entry in the [Location] section to see how the dialog box updated the INI file. Your new entry should look like the one in Listing 27.12.


Listing 27.12. The results of adding a new location to TELEPHON.INI.
Location4=6,"TAPI Book","9","8","999",1,2,0,1,"",0,"1170,"

You have now used the TAPI dialog boxes to add new locations to your TELEPHON.INI file. Next you'll use the same dialog box to add calling card information for the location.

Credit Card Dialing Instructions

Another very important section in the TELEPHON.INI file is the [Cards] section. This section holds information on the calling cards defined for this workstation. The first entry in the [Cards] section tells TAPI how many calling card definitions are in the section and the next available entry ID. Each additional entry in the [Cards] section represents one set of calling parameters. Listing 27.13 shows what a typical [Cards] section of the TELEPHON.INI file looks like.


Listing 27.13. A typical [Cards] section.
[Cards]
Cards=23,23
Card0=0,"None (Direct Dial)","","","","",1
Card1=1,"AT&T Direct Dial via 10ATT1","","G","102881FG","10288011EFG",1
Card2=4,"MCI Direct Dial via 102221","","G","102221FG","10222011EFG",1
Card3=5,"MCI via 102220","","G","102220FG$TH","1022201EFG$TH",1
Card4=6,"MCI via 1-800-888-8000","","G","18008888000,,,,,,TH,,FG","
Â18008888000,,,,,,TH,,011EFG",1
Card5=7,"MCI via 1-800-674-0700","","G","18006740700,,,,,,TH,,FG","
Â18006740700,,,,,,TH,,011EFG",1
Card6=8,"MCI via 1-800-674-7000","","G","18006747000,,,,,,TH,,FG","
Â18006747000,,,,,,TH,,011EFG",1
Card7=9,"US Sprint Direct Dial via 103331","","G","103331FG","10333011EFG",1
Card8=10,"US Sprint via 103330","","G","103330FG$TH","1033301EFG$TH",1
Card9=11,"US Sprint via 1-800-877-8000","","G","18008778000,,,T0FG,,H","
Â18008778000,,,T01EFG#,H",1
Card10=12,"Calling Card via 0","","G","0FG$TH","01EFG$TH",1
Card11=13,"Carte France Telecom","","T3610,H,G#","T3610,H,16,FG#","
ÂT3610,H,19,EFG#",1
Card12=14,"Mercury (UK)","","0500800800$TH,0FG","0500800800$TH,0FG","
Â0500800800$TH,0FG",1
Card13=15,"British Telecom (UK)","","144$H,0FG","144$H,0FG","144$H,010EFG",1
Card14=16,"CLEAR Communications (New Zealand)","","0502333$TH,OFG"," Â0502333$TH,0FG","0502333$TH,00EFG",1
Card15=17,"Telecom New Zealand","","012,0FG?H","012,0FG?H","012,00EFG?H",1
Card16=18,"Global Card (Taiwan to USA)","","G","0FG","0080,102880$TFG$H",1
Card17=19,"Telecom Australia via 1818 (voice)","","1818$TH,FG#","1818$TH,FG#","
Â1818$TH,0011EFG#",1
Card18=20,"Telecom Australia via 1818 (fax)","","1818$TH,FG#","1818$TH,FG#","
Â1818$TH,0015EFG#",1
Card19=21,"Optus (Australia) via 1812","","FG","FG","1812@TH,0011EFG",1
Card20=22,"Optus (Australia) via 008551812","","FG","FG","008551812@TH,0011EFG",1
Card21=3,"AT&T via 1-800-321-0288","634567890","G","18003210288$TFG$TH","
Â18003210288$T01EFG$TH",1
Card22=2,"AT&T via 10ATT0","42345678","G","102880FG$TH","1028801EFG$TH",1

Every calling card entry has seven parts. Listing 27.14 shows the prototype entry for the [Cards] section. Table 27.4 shows the [Cards] entry parameters and short descriptions of their use.


Listing 27.14. The prototype entry for the [Cards] section.
Card<index>=<CardID>,"<FriendlyName>","<ScrambledCardNum>","<SameArea>","<LongDistance>",
Â"<International>",<Hidden>

Table 27.4. The card entry parameters.
Parameter NameDescription
<CardID> This is the unique card ID for this entry.
<FriendlyName> This is an easy-to-read name for the card entry (such as "ATT Calling Card").
<ScrambledCardNum> This is the calling card number. It is scrambled by the TAPI dialog box in order to increase security.
<SameArea> This is the dialing rule for placing a call within the same area code using the calling card.
<LongDistance> This is the dialing rule for placing a long distance call using the calling card.
<International> This is the dialing rule for placing an international call using the calling card.
<Hidden> This value must be 0, 1, 2, or 3. It controls the user's access to the calling card entry.
1 = User can see and edit the entry
2 = User can see, but not edit the entry
3 = User can edit the entry, but not see it
4 = User can neither see nor edit the entry

Understanding the TAPI Dialing Rules

Several entries in the [Cards] section contain dialing rules used by TAPI. These rules are expressed in a series of codes that appear as part of the dialing string. The dialing string can contain the standard values of "0" through "9" along with many other values. These values can be divided into three groups:

Dialable digits or tones include 0 through 9, A through D, and # and *. TAPI recognizes several pause or control codes and insertion codes. Table 27.5 shows the valid control and insertion codes for TAPI dialing strings.

Table 27.5. Valid control and insertion codes for dialing strings.
Dialing Code
Description
T
Use tone (DTMF) dialing
P
Use pulse dialing
!
Flash the hookswitch (to make a transfer)
,
Pause (for about one second)
W
Wait for second dial tone (for DID calls)
@
Wait for quiet answer (call pick-up only)
$
Wait for "bong" tone (for billing cards)
E
Insert the country code
F
Insert the area code
G
Insert the phone number
H
Insert the calling card number
I
Optionally insert the area code

You can use the information in Table 27.5 to decipher entries in the [Cards] section of the TELEPHON.INI file. For example, the dialing rules for placing calls using the card entry shown in Listing 27.15 indicate the dialing rules for local, long distance, and international calls.


Listing 27.15. A sample dialing rule set.
Card1=1,"AT&T Direct Dial via 10ATT1","","G","102881FG","10288011EFG",1

Local calls are placed by simply dialing the phone number ("G"). Long distance calls require dialing "102881" plus the area code ("F") and the phone number ("G"). While the international calls must be placed using "10288011" plus the country code ("E"), the area code ("F"), and the phone number ("G").

Testing the Calling Card Settings of TAPIDLG.EXE

You can check the effects of TAPI dialog boxes on the long distance dialing rules by clicking the Dial Using Calling Card check box and selecting a calling card to use. Fill in the calling card number as eight 9s ("99999999"). Refer to Figure 27.5. Then click OK to save the calling card data and OK to save the location data.

Figure 27.5 : Entering calling card data

After saving the data, press the Telephon.ini button to bring up the TELEPHON.INI file and find the [Cards] entry you modified. It should look something like the one in Listing 27.16.


Listing 27.16. The modified [Cards] entry.
Card22=2,"AT&T via 10ATT0","42345678","G","102880FG$TH","1028801EFG$TH",1

Notice that the dialog box scrambled the calling card number before saving it to the INI file

.

Warning
Be sure to restore your location settings after you finish with this chapter. If you do not, your TSPs will not know how to place a call from your "experimental" location.

Summary

In this chapter you learned a bit about how TAPI works behind the scenes to place call requests generated by your programs. You learned that the TAPI system keeps track of vital information in the TELEPHON.INI file kept in the WINDOWS folder on the workstation. You learned there are four main sections in the TELEPHON.INI file:

You learned the different predefined media modes that can be handled by registered TAPI applications in the [HandOffPriorities] section. You also learned the dialing codes that are used in the [Cards] section to tell TAPI how to place requested calls.

Finally, you built a small Visual Basic application that allowed you to gain direct access to the various TAPI line dialog boxes that can affect the TELEPHON.INI file.

In the next chapter, you'll learn how the Telephony Service Providers work and how they fit into the TAPI model.