INFO: README for Win32 Software Development Kit, Part 1 of 2ID: Q167799
|
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
#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:
* 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.
* Telephony Service performance monitoring add-in (TAPIPERF.DLL). Allows
the Windows NT Performance Monitor to track items such as active lines,
calls (incoming and outgoing), applications, and so on.
* Telephony Control Panel (TELEPHON.CPL) and its associated help file.
* 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).
* Universal Modem Driver Service Provider (UNIMDM.TSP, MODEM.SYS and
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.
* 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:
* TAPICOMM sample. This sample demonstrates how to write a Win32-based
TAPI application that makes datamodem calls.
* ACD (Automatic Call Distribution) samples ACDSMPL and ACDCLNT. These
samples demonstrate basic functionality for an ACD Proxy application
and an ACD Agent application.
* DIALER sample. The source code of the 32-bit Phone Dialer accessory is
included with the samples.
* ATSP32 sample. a sample Telephony Service Provider that shows how to
use a modem for speed dialing voice calls.
* TAPI Browser (TB20.EXE). This is the primary tool for TAPI testing. It
is used for learning the response and return values to all TAPI
function calls. Before writing any TAPI code, learn to use TAPI
Browser.
* A Test Service Provider (ESP32.TSP, ESPUI.DLL, ESPEXE.EXE). This
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.
* The Repeater Service Provider (REPEATER.TSP, REPAPP.EXE, REPSETUP.EXE,
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.
* Libraries and headers (TAPI32.LIB, TAPI.H, TSPI.H).
* 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
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
"<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"
(where
<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).
Some useful NTSD commands are:
~* 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.
* The Telephony Control Panel does not support installation of service
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). Additional query words: sdk win32sdk win32prg
Keywords : kbprg
Version : 5.0
Platform : NT WINDOWS
Issue type : Last Reviewed: June 25, 1999