INFO: README for Win32 Software Development Kit, Part 1 of 2

• Microsoft Visual C++, 32-bit Editions, version 5.0

SUMMARY

This is part 1 of 2, of the Win32 Software Development Kit (SDK) readme that is compatible with the SDK that was included with Visual C++ 5.0.

This article includes the original text of the readme. There are references to directories that are on the CD the SDK originally shipped on, not the Visual C++ CD.

                 Microsoft Win32 SDK for Microsoft Windows
                              August, 1996

Contents:

     1. Introduction
     2. New in This Release
     3. Header File Conventions
     4. OpenGL
     5. Windows Sockets 2
     6. Windows Telephony (TAPI)

     Sections 7, 8 and 9 are included in the article titled,

        "README for Win32 Software Development Kit, Part 2 of 2"

MORE INFORMATION

1. Introduction

Welcome to the Microsoft Win32 SDK for Microsoft Windows. This release of the Win32 SDK provides the tools and information necessary to build retail applications for Windows 95 and Windows NT version 4.0. It is possible to install the Win32 SDK on Windows NT version 3.51, and it is possible to build applications that will run on Windows NT version 3.51. However, some of the Windows NT-specific tools in the SDK will not run correctly on Windows NT version 3.51.

To install the Win32 SDK on a development machine, run SETUP.EXE from the root of the SDK. The setup program will detect whether the target machine is running Windows 95 or Windows NT, the processor type (if Windows NT), and the default language. The setup program will copy the appropriate pieces of the Win32 SDK to the target hard drive depending on these three values.

Most of the utilities, headers, libraries, documentation, and sample code in the Win32 SDK are useful when building applications for both Windows 95 and Windows NT. Platform-specific files are located in appropriately named subdirectories: WIN95 and WINNT. Language-specific files are usually located in a subdirectory on the Win32 SDK compact disc (for example, \MSTOOLS\DEBUG\JAPAN); however, they are installed in the standard SDK directories (for example, \MSTOOLS\DEBUG).

There is no compiler, linker, lib utility, or make utility provided with this SDK. This version of the Win32 SDK has been thoroughly tested with Microsoft Visual C++ version 4.x.

For a general introduction to the Win32 SDK, including many of the tools, see the Getting Started help file (\MSTOOLS\HELP\SDKSTART.HLP).

Windows 95, OEM Service Release 2 is the most recent OEM (Original Equipment Manufacturer) release of the Windows 95 operating system. Beginning in the second half of 1996, this is the version of Windows 95 that most computer manufacturers will pre-install on new machines. Windows 95, OEM Service Release 2 will be made available to MSDN customers in a release later this year. Since that release will not include an update of the Win32 SDK, all of the API information about OEM Service Release 2 is included in this Win32 SDK. See the online documentation for additional information.

2. New in This Release

Windows 95 debug binaries are provided for the following localized versions: USA, China, Japan, Korea, NEC, Taiwan, Arabic and Hebrew. For all eight locales, the debug binaries are provided for build 950 of Windows 95. Since August of 1995, Microsoft has released OEM Service releases of Windows 95 with later build numbers. If the build number of the Windows 95 system that the SDK is being installed to does not equal 950, then the debug binaries are not copied to the system.

DirectX is now implemented in Windows NT 4.0, with the exception of Direct3D. See \MSTOOLS\SAMPLES\DIRECTX\README.TXT for more information on DirectX. See \MSTOOLS\D3DFORNT\README.TXT for more information on the beta release of Direct3D for Windows NT that is provided in the SDK.

Microsoft Internet Server Application Programming Interface (ISAPI) is included as an integrated part of the SDK. The sample code is located in \MSTOOLS\SAMPLES\WIN32\WINNT\ISAPI, the two headers (HTTPEXT.H and HTTPFILT.H) are installed to the \MSTOOLS\INCLUDE directory, and the documentation is located under the "Internet" table of contents entry in the general SDK documentation.

Windows 95 introduced a new INF file format used for installing drivers and utilities. This INF file format is now supported on Windows NT 4.0 and is now described in the online SDK documentation.

Windows NT 4.0 has a new SETUPAPI DLL that works with the new INF file format and will be useful for writing install programs. This new setup API is described in the online SDK documentation. There is a version of SETUPAPI.DLL and CFGMRG32.DLL provided in the SDK that may be used for Windows 95. The CFGMRG32.DLL provided for Windows 95 is a pure stub DLL needed only so that SETUPAPI.DLL will load. See the \MSTOOLS\SAMPLES\WIN32\WINNT\INFINST sample for more information.

The interface to the system performance counters has been abstracted in the new "performance data helper" DLL. This new DLL is fully described in the online SDK documentation. See sample code in \MSTOOLS\SAMPLES\WIN32\WINNT\PERFTOOL for more information.

Windows NT 4.0 introduces a new access-control-list management API that is fully described in the online SDK documentation. See sample code in \MSTOOLS\SAMPLES\WIN32\WINNT\SECURITY\ACLAPI for more information.

Previous releases of the Win32 SDK included a statically linked library that provided support for the Simple Network Management Protocol (SNMP). This library has been removed. The functionality has been moved into a dynamic-link library named SNMPAPI.DLL. This new DLL is distributed with Windows NT 4.0. ISVs that want to use the DLL on Windows NT 3.51 or on Windows 95 should see the \MSTOOLS\SNMPAPI directory on the Win32 SDK compact disc.

The MSTOOLS\RPC_RT16 directory contains the RPC run-time components for MS- DOS and 16-bit Windows. The MSTOOLS\RPC_SDK directory contains the SDK components for building RPC applications for MS-DOS, 16-bit Windows, and the Macintosh. The two directories named RPC_DOS and RPC_MAC on previous releases of the Win32 SDK have been superseded by the new RPC_RT16 and RPC_SDK directories.

The compact disc containing the checked build of Windows NT Workstation 4.0 contains a new tool in the PAGEHEAP directory that will be useful to many application developers. The Pageheap tool provides an alternate system heap manager that aligns each allocation at the end of a separate virtual page, and marks the next virtual page with NO_ACCESS. In this way, read or write operations beyond the end of the heap allocation will cause an immediate access violation, allowing you to more quickly identify errors in your applications.

3. Header File Conventions

In the header files, information guarded by

    #if _WIN32_WINNT >= 0x0400

The value of _WIN32_WINNT is set in WIN32.MAK, depending on the platform you choose to target. By default, WIN32.MAK now sets the TARGETOS to WINNT and the APPVER to 4.0. As a result, by default, _WIN32_WINNT is now defined as 0x0400.

If you are building an application to run on Windows 95 and you want compile-time notification of compatibility issues, set TARGETOS=BOTH in your makefile. When TARGETOS is defined as BOTH, _WIN32_WINNT is not defined for the precompiler, and the only information parsed at compile time will be applicable to both Windows 95 and Windows NT.

If you do not include WIN32.MAK in your makefile, you need to explicitly define _WIN32_WINNT as 0x0400 to get some of the new Windows NT 4.0- specific material from the header files.

There are several API sets present in Windows 95, OEM Service Release 2 that are still guarded by (_WIN32_WINNT >= 0x0400), e.g. the Cryptography API. If you are writing an application specifically for Windows 95, OEM Service Release 2, and you want the header files to provide compile time access to these APIs, it is necessary to define _WIN32_WINNT as 0x0400. Notice that an application that uses these technologies will not run correctly on the retail release of Windows 95. The vast majority of application programs that are expected to run on Windows 95 should be built without defining _WIN32_WINNT.

The value of MB_SERVICE_NOTIFICATION has changed between releases of Windows NT 3.51 and Windows NT 4.0. See WINUSER.H for the old and new values. Windows NT 4.0 provides backward compatibility for pre-existing services by mapping the old value to the new value in the implementation of the MessageBox and MessageBoxEx functions. This mapping is performed only for executables that have a version number, as set by the linker, that is less than 4.0.

If you want to build a service that uses MB_SERVICE_NOTIFICATION, and that will run on both Windows NT 3.x and Windows NT 4.0, you have two choices:

      1.  At linktime, specify a version number less than 4.0; or
      2.  At linktime, specify a version number equal to 4.0, detect
          the version of the operating system at run time, and dynamically
          choose the correct value.  The sample code module
          \MSTOOLS\SAMPLES\MAPI\COMMON\MAPIDBG.C demonstrates this
          technique.

Previous releases of the Win32 SDK included definitions in WIN32.MAK to map structured exception handling keywords to their proper underscored names:

    try -> __try
    except -> __except
    finally -> __finally
    leave -> __leave

    SEHMAP = TRUE

4. OpenGL

The Windows NT 4.0 and Windows 95 releases of OpenGL includes new functionality and performance enhancements. These include:

1. A complete implementation of OpenGL 1.1. OpenGL 1.1 contains several

1. Overlay planes extensions. These Microsoft OpenGL extensions permit

1. Extended metafile support. Applications may encapsulate OpenGL calls and

1. Microsoft extensions. The Microsoft OpenGL implementation also supports

1. Performance. The software renderer has been tuned for this release.

1. OpenGL hardware acceleration. This release of OpenGL supports a simpler

OpenGL is provided for Windows 95, both as an ISV redistributable, and a built-in component of Windows 95 OEM Service Release 2.

For more information on OpenGL, see \MSTOOLS\SAMPLES\OPENGL\README.TXT.

5. Windows Sockets 2

Windows NT 4.0 includes the new Windows Sockets 2 programming interface. The complete Windows Sockets 2.2 specification is available on the Win32 SDK compact disc in the \DOC\SPEC\WINSOCK2 directory. The Win32 SDK online documentation (WIN32SDK.MVB and SPK.MVB) includes much of the material that is in the specification.

The new header files (WINSOCK2.H and WS2SPI.H) are in \MSTOOLS\INCLUDE, the library (WS2_32.LIB) is installed in \MSTOOLS\LIB, and there is new sample code. See MSTOOLS\SAMPLES\WIN32\WINSOCK2\README.TXT. The SPORDER.EXE tool is installed in \MSTOOLS\BIN and will allow you to order the service providers that you have installed on your system. A SPORDER.DLL makes the same functionality available programmatically. In this way your installation program can set the service provider order without requiring user input. See \LICENSE\REDIST.TXT for the terms under which SPORDER.DLL may be redistributed.

To rebuild your application with WinSock2 rather than WinSock1: If your makefile includes WIN32.MAK (as is recommended), and your source files include windows.h (as is recommended), you will get the correct winsock.h header and the correct ws2_32.lib library by default. If your code includes winsock.h directly, and you simply change this to include winsock2.h, you will get undefined externals in mswsock.h at compile time. Don't include winsock2.h directly; include windows.h instead. Notice that sample code in previous releases of the Win32 SDK occasionally included winsock.h rather than windows.h. It has now been fixed.

The Windows NT DDK includes sample code for a "Windows Sockets helper DLL." If your network service provider is written to TDI as the top level interface, you will find that providing a helper DLL is the quickest way to produce a Windows Sockets 2 service provider for Windows NT 4.0.

Run-Time Components

When you install Windows NT 4.0, Windows Sockets 2 is installed automatically with the operating system. The Microsoft network transport stacks in Windows NT 4.0 support quality of service only as "best effort." In other words, the XP1_QOS bit in the service flags is not set. The Microsoft network transport stacks in Windows NT 4.0 do not support "callee data" in the condition function of WSAAccept.

A beta release of the Windows Sockets 2 run-time components for Windows 95 is available on the internet. For the most recent updates, see the Microsoft and Intel FTP sites:

   ftp://ftp.microsoft.com/bussys/winsock/winsock2/ and
   ftp://ftp.intel.com/pub/winsock2/.

6. Windows Telephony (TAPI)

The TAPI 2.0 components included with Windows NT 4.0 are:

* Core TAPI Components (TAPISRV.EXE, TAPI.DLL, TAPI32.DLL). TAPISRV.EXE

   is now the core module of TAPI. TAPI.DLL (16-bit) and TAPI32.DLL
   (32-bit) load into the application process and communicate with
   TAPISRV.EXE. See the TAPI section of the Win32 SDK Documentation for
   further information.

   the Windows NT Performance Monitor to track items such as active lines,
   calls (incoming and outgoing), applications, and so on.

* Kernel-Mode Device Driver Service Provider (KMDDSP.TSP, NDISTAPI.SYS).

   Supports TAPI drivers that execute entirely in kernel mode, such as
   NDIS WAN miniport drivers (which support ISDN, Switched 56, and so on).

   several other associated components). This TSP has functionality
   equivalent to that of the Unimodem that shipped with Windows 95 (except
   that it does not support VoiceView). It also does not include the voice
   or DTMF handling features of Unimodem/V. It has been updated to the
   TAPI 2.0 32-bit architecture and enhanced to simplify the configuration
   of large numbers of modems.

In addition, the Dial-up Networking and HyperTerminal components included with Windows NT 4.0 use TAPI when placing or answering calls on modems and ISDN adapters.

The TAPI 2.0 components included with the Win32 SDK are:

* TAPICOMM sample. This sample demonstrates how to write a Win32-based

   TAPI application that makes datamodem calls.

   samples demonstrate basic functionality for an ACD Proxy application
   and an ACD Agent application.

   included with the samples.

   use a modem for speed dialing voice calls.

   is used for learning the response and return values to all TAPI
   function calls.  Before writing any TAPI code, learn to use TAPI
   Browser.

   component can be used to generate most TAPI messages and structure
   fields for testing TAPI applications. It is a simple PBX simulator, in
   that if you create multiple line devices in ESP, you can place calls
   between them, and the expected call states and messages will be
   automatically generated.

   and associated help file). Repeater is installed between TAPISRV and
   any other TSP, and stores in a log file all function calls and messages
   across the TSPI. This utility can be used for debugging, and,
   eventually, with a TSP emulator from Microsoft to enable the testing of
   applications in the absence of hardware that would be needed to test
   the "real" TSP.

* Documentation for TAPI and TSPI is included in the SDK help viewer

   databases (WIN32SDK.MVB and SPK.MVB).

Getting Started

Application developers will find that TAPI 2.0 is backward-compatible with earlier versions of TAPI. Applications written for Windows 3.x and Windows 95 will run without modification.

Service provider developers have a bit more work ahead. Service providers for Windows 3.x or Windows 95 have a 16-bit DLL as their top-most component, and these are not supported under TAPI 2.0 on Windows NT. If you are porting an existing service provider to Windows NT, your primary task is to redesign it as a Win32 DLL, multithread and multiprocessor safe, that compiles and runs on all RISC platforms as well as x86 platforms. You will also find that it is necessary to provide new UI functions in a DLL that can be loaded into the application process, while the main service provider DLL runs in TAPISRV's process (see the TAPI documentation for details). If your service provider currently launches a companion EXE for handling asynchronous events, you will likely find that this is no longer necessary; instead, you can create threads in TAPISRV's context. On Windows NT, all strings passed through the service provider interface are now Unicode. Refer to the documentation for more information.

If your service provider communicates with hardware using a serial interface on Windows 3.x or Windows 95, conversion to Win32 should be relatively straightforward using the built-in Windows NT serial drivers. If you directly access hardware on the local system, however, you will need to provide a Windows NT kernel-mode device driver. Porting a Windows 3.x or Windows 95 VxD to Windows NT is not a trivial task, but help is available through Microsoft Developer Support.

If you are developing a server service provider to control a PBX CTI link or other multiple-line device, you need to write the code to handle the protocol stack on the CTI link. This code needs to manage states for many devices and calls, and the communications over the link. This is true whether that is a LAN transport or something else.

Registry Information

TAPI configuration information can be found in the registry under the following key:

   \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony

Warning: No production (shipping) code should assume anything about what is in the registry, or that the location of any specific information will not change. Microsoft reserves the right to alter or remove any registry keys or values without notice. The information provided regarding registry keys and values is only intended to help during development and debugging.

Debugging

You can enable TAPI debug output by creating and changing DWORD values found under the registry key mentioned earlier from 0 (no debug output) to 4 (maximum debug output). Value names follow the convention "<ModuleName>DebugLevel", e.g., "Tapi32DebugLevel", "TapisrvDebugLevel", "esp32DebugLevel", and so on.

To debug TAPISRV.EXE (the process context in which service providers run), you can do one of the following:

 (1) Start REGEDT32.EXE and change the ImagePath value under

          \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tapisrv

     from "<path>\tapisrv.exe" to "ntsd -g -G -x <path>\tapisrv.exe"

     <path> is your Windows NT SYSTEM32 directory path).

     Then, open the Services control panel, select "Telephony Service,"
     click the Startup button, and check the "Allow Service to Interact
     with Desktop" check box. (Note that this step is also necessary
     in order to see the "User-specified request results" dialog box in
     ESP, if you use it, because ESP displays that dialog box in TAPISRV's
     context.)

 (2) Run PVIEW or TLIST to get a process identifier (PID) for TAPISRV.EXE,
     and then attach NTSD to TAPISRV as follows:

          start ntsd -g -G -x -p <pid>

     Note that NTSD requires <pid> to be in decimal format. You can start
     TAPISRV from the command line by typing "NET START TAPISRV".

     The "-g" and "-G" options prevent NTSD from breaking on startup and
     exit, respectively;  the "-x" option disables first-chance access
     violation exception handling/breaking in NTSD, allowing a module's
     exception handler to deal with the exception (if a handler is not
     found, Windows NT will break).

     ~*                Shows all the threads in a process
     ~Nk               Dump the stack of thread N
     u <addr>          Unassembles at address <addr>
     dc <addr>         Dumps memory at address <addr>
     bp <addr>         Sets a breakpoint at address <addr>
     ?                 Shows other NTSD commands

TAPI and Client-Server Telephony

Client-server telephony allows an application to send its call-control functions over the LAN to a remote telephony server, which in turn controls a switching fabric directly on behalf of that and other clients. Like all previous versions of TAPI, TAPI 2.0 also supports client-server telephony. Because TAPI is connection-model independent, you can develop Win32 telephony applications without regard to whether they will run against local hardware or over remote client-server connections.

To enable client-server telephony with TAPI, you need a TAPI service provider for each client that communicates with a telephony server. Client service providers and telephony servers are available from several third parties. Microsoft intends to ship a generic client service provider, telephony server, and related administration tools, as an add-on for Windows NT 4.0 and Windows 95, within a few months after the release of Windows NT 4.0 to manufacturing.

Known Issues with TAPI 2.0

* The CompletionMsgText field in LINEADDRESSCAPS is not being converted

   from Unicode to ANSI in lineGetAddressCapsA. The workaround is to
   either not use the CompletionMsgText, or to convert it to ANSI in the
   application, or to write the application as a Unicode application. This
   will be corrected in a future release.

   providers using an OEMSETUP.INF file; the "Have Disk" option in the
   "Add" dialog box does not work. Service providers will need to include
   either a Setup program or other installation tool that copies all files
   to the correct locations on disk, including placing the TSP file in
   \winnt\system32. Preferably, the Setup program will call the TAPI
   lineAddProvider function itself to get the service provider added to
   the TAPI environment, but if this is not done, the Telephony Control
   Panel "Add" function *can* be used to add the service provider after the
   files are copied to the correct locations. Microsoft strongly encourages
   service providers to include a complete setup program that handles all
   installation; the most likely resolution of this issue will be the
   elimination of OEMSETUP.INF setup capability, rather than fixing it
   (since this is a holdover from Windows 3.x and no longer a preferred
   installation method for Win32).