Microsoft KB Archive/167799

-

The information in this article applies to:


 * 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 CFGMGR32.DLL provided in the SDK that may be used for Windows 95. The CFGMGR32.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.

NOTE: If you are using the Platform SDK (released after the Win32 SDK), the CFGMGR32.DLL is not automatically installed. You can find the file on the Platform SDK disc in the \cabs\i386 directory. The default install directory for the Platform SDK is now \mssdk instead of \mstools.

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

is implemented only in Windows NT version 4.0 and later. It is not implemented in Windows 95. This precompiler guard allows you to do compile- time checking for platform differences.

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.

In version 4.1 of the Microsoft Visual C++ compiler, "bool" has become a reserved token. This conflicts with the OAIDL.H and OBJIDL.H header files where "bool" is used as a field name, and it will cause the following warning: "C4237: nonstandard extension used : 'bool' keyword is reserved for future use." It is possible to turn off this warning message by using
 * 1) pragma warning( disable : 4237).

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

This caused problems for developers who chose to use C++ structure exception handling where "try" is supposed to be "try" and not "__try". For this reason, by default, the mapping has been removed from WIN32.MAK. This may cause build-time errors for your applications. To get the old behavior add

SEHMAP = TRUE

to your makefile before including WIN32.MAK.

- 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 functions, including vertex array, polygon offset, logic ops, and several new functions for handling textures. The vertex array and texture calls are particularly significant, as they may enable order of magnitude performance improvements in some applications.

2. Overlay planes extensions. These Microsoft OpenGL extensions permit applications to manage and render into overlay planes, where supported in the graphics hardware. This permits applications to display dialog boxes and other UI features without overwriting 3-D renderings.

3. Extended metafile support. Applications may encapsulate OpenGL calls and data in GDI extended metafiles. This, together with Windows NT 4.0 print spooler enhancements for remote metafile rendering, makes it possible to print OpenGL graphics at high resolution on the print server. This feature is limited to the Windows NT release.

4. Microsoft extensions. The Microsoft OpenGL implementation also supports these performance extensions: GL_WIN_swap_hint, GL_EXT_bgra, and GL_EXT_paletted_texture. They improve the performance of some applications significantly.

5. Performance. The software renderer has been tuned for this release. Performance tuning has been carried out for the front end of the OpenGL pipeline as well as for rendering particular primitives, especially anti- aliased lines and texturing. Software rendering is generally two to four times faster.

6. OpenGL hardware acceleration. This release of OpenGL supports a simpler mini-client driver (MCD) model to accelerate 3-D graphics operations. In particular, Windows NT 4.0 includes a Matrox Millennium mini-client driver that accelerates OpenGL functions. A corresponding driver for Windows 95 is expected to be available later in 1996.

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:

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.
 * Core TAPI Components (TAPISRV.EXE, TAPI.DLL, TAPI32.DLL). TAPISRV.EXE

the Windows NT Performance Monitor to track items such as active lines, calls (incoming and outgoing), applications, and so on.
 * Telephony Service performance monitoring add-in (TAPIPERF.DLL). Allows


 * Telephony Control Panel (TELEPHON.CPL) and its associated help file.

Supports TAPI drivers that execute entirely in kernel mode, such as  NDIS WAN miniport drivers (which support ISDN, Switched 56, and so on).
 * Kernel-Mode Device Driver Service Provider (KMDDSP.TSP, NDISTAPI.SYS).

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.
 * Universal Modem Driver Service Provider (UNIMDM.TSP, MODEM.SYS and


 * Phone Dialer accessory (DIALER.EXE) and its associated help file.

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:

TAPI application that makes datamodem calls.
 * TAPICOMM sample. This sample demonstrates how to write a Win32-based

samples demonstrate basic functionality for an ACD Proxy application and an ACD Agent application.
 * ACD (Automatic Call Distribution) samples ACDSMPL and ACDCLNT. These

included with the samples.
 * DIALER sample. The source code of the 32-bit Phone Dialer accessory is

use a modem for speed dialing voice calls.
 * ATSP32 sample. a sample Telephony Service Provider that shows how to

is used for learning the response and return values to all TAPI function calls. Before writing any TAPI code, learn to use TAPI Browser.
 * TAPI Browser (TB20.EXE). This is the primary tool for TAPI testing. It

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.
 * A Test Service Provider (ESP32.TSP, ESPUI.DLL, ESPEXE.EXE). This

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.
 * The Repeater Service Provider (REPEATER.TSP, REPAPP.EXE, REPSETUP.EXE,


 * Libraries and headers (TAPI32.LIB, TAPI.H, TSPI.H).

databases (WIN32SDK.MVB and SPK.MVB).
 * Documentation for TAPI and TSPI is included in the SDK help viewer

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

During initial testing, you can use REGEDT32.EXE to edit the \Providers section under this key to add or remove providers. Or you can use the Telephony Control Panel when you have implemented TSPI_providerInstall.

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 "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 " \tapisrv.exe" to "ntsd -g -G -x \tapisrv.exe" (where    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

Note that NTSD requires 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).

Some useful NTSD commands are:

~*               Shows all the threads in a process ~Nk              Dump the stack of thread N     u          Unassembles at address dc        Dumps memory at address bp        Sets a breakpoint at address ?                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 --

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.
 * The CompletionMsgText field in LINEADDRESSCAPS is not being converted

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). Please see "README for Win32 Software Development Kit, Part 2 of 2" for sections 7, 8 and 9 of the Win32 SDK readme.
 * The Telephony Control Panel does not support installation of service

Additional query words: sdk win32sdk win32prg

Keywords         : kbprg Version          : 5.0 Platform         : NT WINDOWS Issue type       : Last Reviewed: June 25, 1999