Windows Telephony Software Development Kit Release Notes
Chicago PDK Release

1. Getting Started
2. Release Contents
3. Telephony SDK support
4. Known limitations and problems
5. Configuring the AT service provider and running the DIALER sample
6. Compiling the sample code
7. Using the extension identifier generation utility (EXTIDGEN) 
8. AT service provider modem compatibility issues
=================================================

1. Getting Started

The Chicago system setup program automatically installs Telephony runtime 
components in your Windows and Windows system directories.  Sample code 
and telephony programming documentation are installed in the TAPI subdirectory 
of the SDK main directory, while C language headers, Windows help files, 
and the telephony import library are installed in the LIB16, HELP, and INC16
subdirectories of the SDK main directory.

Before running the DIALER application, you should run the Telephony
Control Panel to set your current country code and area or city code for 
dialing.  Depending on how your machine's modem is configured, you may also 
need to configure the AT Modem service provider preinstalled with retail
Chicago.

Set your country code and area or city code by doing the following:
- Open the Chicago Control Panels folder.  This should be located within 
  the Main folder.  Double-click on the Telephony icon.
- Press the button labeled "Location Setup..."
- In the "Locations" dialog, ensure that 'Default Location' in the 
  "Defined Locations" listbox is highlighted.  
- Press the "Edit..." button.
- In the "Edit Location" dialog, select your current country
  in the 'Country Code' dropdown listbox.  Enter your area code
  or city code in the 'Area Code' edit field.  
- If you need to dial "9" or some other code to access an outside line  
  on a PBX system, enter the appropriate digits in the fields provided.
- Press OK, then press Close twice to exit the Telephony control panel 
  applet.


Modify the AT modem service provider driver configuration by doing
the following:
- If you haven't already opened the Telephony control panel, do
  so by opening the Chicago Control Panels folder and double-clicking
  on the Telephony icon.
- When the Telephony control panel main dialog appears, press the
  "Driver Setup..." button.
- When the "Telephony Drivers" dialog appears, press the "Add..." button.
- Select the "AT Command Set Modem Telephony SP" entry in the 
  "Telephony Drivers" listbox, and press the "Add" button.
- In the "AT/SP Configuration" dialog, set the "Communications Port" 
  listbox to indicate the COM port to which your modem is connected, 
  and the "Speed (DTE Rate)" listbox to the baud rate for that port.
- If you would like to define a name for the AT modem line device to
  be displayed in lists of devices shown by Dialer and other Telephony
  applications, press the "Configure Line..." button and enter the 
  line's name and an optional line number in the fields provided.
  Press OK when done.
- Press OK, then Close to return to the Telephony control panel
  main dialog.

2. Release Contents

The Chicago SDK includes documentation, samples, headers, and libraries
needed for developing 16-bit Windows Telephony applications and service
providers.  The SDK release contents are organized into subdirectories 
of the SDK root directory, as follows:

INC16 - TAPI.H and TSPI.H interface definition header files
LIB16 - TAPI.LIB import library
BIN - EXTIDGEN.EXE - Extension ID generator application
HELP - Programmer's API references in Windows Help format.
TAPI\DOCS\API - TAPI documentation, in Word for Windows 2.0 format.
TAPI\DOCS\SPI - TSPI documentation, in Word for Windows 2.0 format.
TAPI\SAMPLES\WIN16\ATSP - Complete source code for a simple modem service provider.
TAPI\SAMPLES\WIN16\DIALER - Complete source code for the dialer application.

Note: The contents of this PDK release of the Windows Telephony SDK are 
for development and test and evaluation, and are not to be included in 
shipping products, since this is not a retail release of the Telephony 
SDK.

Runtime Telephony components should already be installed in your \WINDOWS
and \WINDOWS\SYSTEM as part of the main Chicago system setup.  
Runtime components include:

TAPI.DLL: the WOSA interface layer which connects Telephony 
applications to Telephony service providers.

TAPIEXE.EXE: a small program which is automatically launched 
(and terminated) by TAPI.DLL when needed to provide a context for 
processing of Telephony events.

TELEPHON.CPL: a Control Panel application used for setting information
on: a Telephony user's location (such as current country and area or 
city code); long distance service calling card information (such as
personal card number and dialing rules).  This application is also
used to install, configure, and remove Telephony service providers.

DIALER.EXE: a Windows Telephony application which can dial 
voice calls, maintain a call log by monitoring other telephony activity, 
and process Simple Telephony requests from other applications.  
Source code is included for reference.

ATSP.TSP: a Windows Telephony service provider which can dial 
voice calls through AT command set-based modems and similar 
devices.  Source code is included for reference.

If you cannot find these files, you may need to re-run the main Chicago 
system setup program and ensure that you have elected to install Telephony 
runtime files.

3. Telephony SDK support
		  
Please see the general Chicago PDK information for guidance on 
where to post Windows Telephony questions on the Chicago PDK 
support forum on CompuServe.

4. Known limitations and problems


The following problems exist in this release of the 
Telephony SDK and will be corrected in a future release:

- Only one instance of the AT command set modem service provider (ATSP)
  should be installed in TELEPHON.INI at a single time.  It is possible
  to install and run multiple instances of ATSP at the same time, but
  proper behavior is not guaranteed.

- TAPI.DLL does not explicitly free default icons loaded by itself if
  an application calls lineGetIcon or phoneGetIcon and the service
  provider associated with the specified device does not supply an
  icon.  This may lead to a small loss of GDI memory.

- If a service provider signals an incoming call by setting the current
  call's state to LINECALLSTATE_OFFERING, it must not specify a media
  mode of LINEMEDIAMODE_UNAVAIL - this will crash TAPI.  The media
  mode should be specified as one of the other available values.

- TAPI incorrectly parses extension IDs used in "extendX" TELEPHON.INI
  settings.  Although each component of an extension ID is specified
  to be eight ASCII characters from the hexadecimal digit set [0-9,A-F],
  TAPI.DLL will not correctly parse an extension ID containing any
  characters in the range A-F, or any component which is all zeros.
  
  If you use EXTIDGEN (see section 8) to generate a unique ID, simply
  transform any hexadecimal digits in the range A-F into digits in the
  range 0-9.

- Certain service provider-implemented functions (such as TSPI_lineMakeCall
  and TSPI_lineSetupTransfer) cause new call handles to be created.  These
  call handles are considered valid by TAPI only *after* the service provider
  routine returns to TAPI.  It is important to note that while it is possible
  for a service provider to send event messages to TAPI concerning the call
  being created before returning from these functions, such event messages 
  have no meaning to TAPI (since the call handle is not recognized until 
  the original service provider function returns to TAPI).  Normally, TAPI 
  should ignore these "early events", however this release will try 
  to interpret these events, and may GP fault.  Service provider writers 
  should refrain from sending events to TAPI within the implementation of 
  routines which create call handles.

- Multiple applications using TAPI's "phone" API subset may receive 
  incorrect values for the number of owners/monitors active (sent via
  a PHONE_STATE callback) when one of the applications monitoring a 
  particular phone shuts down.  Generally, the surviving applications
  will receive a value one greater than actual.

- The UNIMODEM service provider installed with Chicago does not support
  voice calls and is not recognized by the DIALER application, since DIALER
  looks for providers supporting LINEMEDIAMODE_INTERACTIVEVOICE only.
  
5. Configuring the AT service provider and running the DIALER 
sample

The AT service provider requires you have a modem or other device 
which responds to AT command set commands connected to your 
computer on COM1-COM4.  See section 1, "Getting Started", for
instructions on configuring the AT Modem service provider.

You may get unexpected behavior if you try running DIALER with an improperly
configured AT service provider or improper hardware configuration.  Some 
errors you may see include:

- If you have no TELEPHON.INI, or you have a TELEPHON.INI but there is no
  service provider installed which supports LINEMEDIAMODE_INTERACTIVEVOICE,
  DIALER will bring up the message box:

  "There is no voice line available! Dialer can't run without one"
  
  on startup.  Exit DIALER, start the Telephony Control Panel, and check
  under "Driver Setup..." to ensure you have installed the AT modem service
  provider or another provider which supports LINEMEDIAMODE_INTERACTIVEVOICE.
  
- If you have installed the AT modem service provider but have specified a COM
  port not available on your machine, DIALER will behave as follows:
  On dialing a number, the "Dialing" dialog will appear, followed immediately
  by the warning:
  
  "An error occurred while completing the TAPI request."
  
  Exit Dialer, start the Telephony Control Panel, and check the AT modem service
  provider settings to ensure you have specified the correct COM port.
    
- If you have correctly specified an existing COM port but have not connected
  an AT command set device to that port, DIALER will behave as follows:
  On dialing a number, the dialing dialog will appear and system will seem 
  to hang for 20-30 seconds - the service provider is trying to get a 
  response from the disconnected modem.  After timing out, you will get 
  the warning:

  "An error occurred while completing the TAPI request."
  
  Click OK, check your modem connection, and try redialing.


6. Compiling the sample code

The ATSP and DIALER samples have been developed using Visual 
C++ 1.0;  however, the source code is completely compatible with 
Microsoft C/C++ 7.0 with Windows SDK.  The makefiles supplied 
with the samples are external makefiles; these makefiles can be used 
either with NMAKE at the command line, or with the Visual C++ 
Visual Workbench or the Programmer's Workbench supplied with 
Microsoft C/C++ 7.0 by treating them as external makefiles.

Before compiling the sample source code, you must set the LIB and
INCLUDE environment variables to reference the SDK's INC16 and LIB16
directories, respectively.

Both makefiles use the following syntax:

nmake DEBUG=1 - creates a version of the sample with Codeview 
information and debugging messages included.
nmake DEBUG=0 - creates a 'nodebug' version of the sample, with no 
Codeview information or debugging messages.


7. Using the extension identifier generation utility (EXTIDGEN):

Service providers which support non-standard extensions to the TAPI 
through lineDevSpecific, lineDevSpecificFeature, phoneDevSpecific,
or by inserting non-standard fields into the variable portion of data 
structures, or extending (where permitted) enumerated types and bit 
fields must establish a unique extension identifier, encoded in a 
LINEEXTENSIONID or PHONEEXTENSIONID structure.  The 
EXTIDGEN.EXE program supplied in the BIN directory generates a 
unique hexadecimal number each time it is run; the number is based 
on the host computer's network hardware adapter address and the 
current time and date.

To generate a unique identifier:
(1) Run EXTIDGEN with no arguments, and capture the output into a 
text file: extidgen >ident.txt
(2) Load ident.txt into your programming editor.  The unique 
identifier will be of the format:
	
	dwExtensionID0 = 0xXXXXXXXX;
	dwExtensionID1 = 0xXXXXXXXX;
	dwExtensionID2 = 0xXXXXXXXX;
	dwExtensionID3 = 0xXXXXXXXX;

where each digit 'X' is a hexadecimal digit.

NOTE: Due to a bug in this TAPI release, extension IDs which
are all zeros or which contain hex digits in the range A-F may
result in TAPI incorrectly diagnosing TELEPHON.INI as corrupt.
If EXTIDGEN generates an extension identifier which contains these
constructs, simply modify the identifier by hand.

8. AT service provider modem compatibility issues

Please note that ATSP is very sensitive to the degree of Hayes 
compatibility that your modem provides.  Many modems claim to be Hayes
compatible but are only partially Hayes compatible.  If you 
find that ATSP is not hanging up calls correctly or seems to be freezing 
your machine for periods of 20 to 30 seconds, then your modem may be 
at fault.  Please check your modem owner's manual or contact your modem 
manufacturer.
 
For those who are interested in determining whether or not a modem will run 
with ATSP, start up your favorite terminal emulation program and try 
the following:

Dial a number with a ; appended to the number so that the modem
returns immediately after dialing.  The modem should dial and return.

		AT
		OK
		ATDT16364;
		OK

Send the ATD command to commence busy detection.  The modem
should not return until it detects a call state or times out.

		ATD
		BUSY
		
Before the modem detects a call state, press return.  This should hang
up the call.  Send an ATH0 to hang up the modem just in case.

		ATD
		(carriage return)
		(modem hangs up)
		NO CARRIER
		ATH0
		OK

If you can make it through these steps, then ATSP should drive your modem (the 
other things that it does are fairly simple).  Known problem modems include:

- Forval modems return two OK replies after a dial request which causes a
  race condition in ATSP to overrun the dial string.
- Scout modems do not correctly handle asynchronous dial requests.
- PDI modems do not support the semicolon (;) in the same way that Hayes modems
  do and will only work if the X0 command is included in the setup
  init string from the control panel.
