Dan Appleman's Visual Basic Programmer's Guide to the Win32 API

Charles Petzold's Programming Windows, The Definitive Guide to the Win32 API using C/C++

Jerry Lozano's The Windows 2000 Device Driver Book: A Programmer's Guide

Revision 3.08

Warning: This document is probably out of date by the time you read this, as are most other Windows programming documents on Web. The reason for this is simple: programmers are always too busy getting programs to work to worry about keeping the documentation to date.

1	Introduction: Win32
2	Getting Started
3	Development Tools
4	Win32 Platforms
5	Programming Questions
6	Internet Programming
7	DLLs: Dynamic Linked Libraries
8	Console Mode Applications
9	Services
10	Help! My Program does not Compile and Link!
11	Debugging -or 'help, my program doesn’t work'
12	Shipping -or 'help, my customers say my program doesn't work'
13	Miscellany

1. Introduction: Win32

1.1	What is Win32?
1.2	What is the Win32 API?
1.3	How does it differ from the Win16 API?
1.4	Why should I port my code to 32 bits?
1.5	Why shouldn't I port my code to 32 bits?
1.6	Can I write programs using NT's Posix API?
1.7	What is the history of the Win32 API?

1.1. What is Win32?

1.2. What is the Win32 API?

The core API divides into three sections:

• KERNEL
  All the low level kernel services
• GDI
  Graphics Device Interface: drawing and printing
• USER
  User Interface controls, windows and messaging services

Each is pretty much built on top of the other. In Windows 95 the services are provided by three DLLs -USER32, KERNEL32 and GDI32, which either implement the calls or pass them down to their 16 bit predecessors. In Windows NT many of the services are implemented in Kernel Mode and various forms of inter-process communication are used to manage this.

To C++ programmers this is known as "the raw API" as opposed to the API functions which are wrapped up by C++ classes. Beginners quite often have an unexplained fear of using this API, as though you shouldn't have to use it in an MFC or OWL program. This is not true: the C++ classes are there to provide a framework for applications, but the raw API covers a lot more functionality.

As well as the base "Platform API", the Win32 API has grown to provide many more features and function calls, from the games and entertainment related DirectX APIs to the high throughput networking and service related calls used on NT servers to provide minicomputer and mainframe like performance in commercial systems.
[Top of Section] [Index]

1.3. How does it differ from the Win16 API?

• Integers are 32 bits wide: sizeof(int)==sizeof(long)==4
  The 32 bit registers of the CPU (eax and siblings in the '386 and up) are used to manipulate these numbers, giving better performance.
• Different parameter packing on some windows messages (especially WM_COMMAND)
• lots of new API calls.
  Kernel: threads, lots of memory and asynchronous I/O stuff. Lots of new file handling routines, plus security built in.
  GDI: 32 bit co-ordinates, plus Co-ordinate Transform Matrices and paths (in NT)
  User: the Chicago common controls and shell extensions
• Console mode apps can use all the API, and even create windows. Window-based apps can create consoles too -great for debugging.
• Structured Exception handling can make your programs more robust, or at least allow them to tidy up after a crash.
• The header files are a lot larger and better structured.

1.4. Why should I port my code to 32 bits?

• To get the much coveted Designed for Windows logo
• To improve programmer productivity through state of the art development tools and a better API
• To take advantage of the new APIs and more stable execution environment
• To work with long file names. [NB: some workarounds here for MSDOS/win16 applications]
• To multitask properly, and be more robust.
• To take up more disk & RAM.
• To stop appearing like an old-fashioned program.
• To escape many of the 64k limits of 16 bit programs.
• To have a program which runs well on modern CPUs and under Windows NT
• So your code has a future, and an easily maintainable one at that.

In April 1997 it was estimated that there were 60 Million Win95 systems, increasing at 4M units/month, an 3 Million NT systems increasing at 300K units/month (source: Microsoft at WinHec). By September 1997 it was estimated that there were 100 Million Win32 systems, out of a total of 200 Million Windows platforms. There is clearly still merit and profit in supporting Win31. This can be done -sort of- with Win32s.
[Top of Section] [Index]

1.5. Why shouldn't I port my code to 32 bits?

• You've lost the source
• You depend on a third party DLL or VBX for which there is no 32 bit equivalent. Partial fix: thunking
• You don't need any of the new API features our UI improvements.
• Your users will not gain much from improved multitasking or mind suffering on a Pentium Pro CPU.
• You need to support legacy Windows 3.x systems.

If you choose not to upgrade your application to Win32, then you can still stamp the exe as requiring Windows 4.0, so that the OS will automatically clean up all resources it has allocated.
[Top of Section] [Index]

1.6. Can I write programs using NT's Posix API?

The win32 console API is close enough to Posix functionality that many Posix apps should be compilable within the win32 subsystem -this is what the Gnu/win32 project is trying to support.
[Top of Section] [Index]

1.7. What is the history of the Win32 API?

2. Getting Started

This sections answers questions important to anyone just starting to program for win32.

2.1	How do I write Win32 programs?
2.2	What is a suitable computer?
2.3	What is a suitable development tool?
2.4	What OS should I use?
2.5	Do I need the Win32 'Platform' SDK?
2.6	What important things should a newbie learn?
2.7	Are there any on line introductions to Windows programming?
2.8	Do I need MFC to write an application?
2.9	Are there alternative C++ class libraries to MFC?
2.10	How do I migrate from Unix?

2.1. How do I write Win32 programs?

1. Get a suitable computer.
2. Get a suitable development environment.
3. Get a decent book or two. Read them. And ideally an MSDN subscription
4. Start writing Win32 programs, keeping those books handy
5. Don't give up when things don’t work the way you intended.

2.2. What is a suitable computer?

Other desirable features of a development PC are -in approximate order of desirability

• Lots of hard disk: for tools and intermediate files. 4GB+ is nice. With 8 or more GB you can keep all 3 MSDN disks on a hard disk.
• A 1024x768 or larger display
• A fast CD-ROM drive for speedier document access
• Fast access to the Internet at sporadic intervals (tool updates)

For team development a team server with shared directories, web server (integrated with the shared directories) and source code management system is great for development and delivery. NT server or a Linux box with Samba both fit in here. Either way, this should really be a separate system from any server you are testing code on.

Anyone doing device driver work will need one -maybe two- target PCs.

The issue of a development PC is covered in more depth in a separate article.
[Top of Section] [Index]

2.3. What is a suitable development tool?

This includes not just the classic programmer tools of assemblers and C/C++ compilers, but rapid application development environments such as Visual Basic and Delphi, Database systems such as Access and many "office" applications which have been enhanced with programming languages.

Some versions of the Java programming language -specifically Microsoft J++- can also be used for Win32 programming.

Many of the RAD tools simplify programming by hiding the API, making it rather tortuous to perform some relatively simple tasks. This means that most serious Win32 coding is done in the classic programmer languages of C and C++, and to a lesser extent in x86 assembly or the Delphi variant of Pascal.
[Top of Section] [Index]

2.4. What OS should I use?

Windows NT is excellent for development, mainly because it is so robust and you can still use other applications during compiles. It does use a fair bit of RAM, even before you add the compiler's requirements. Developing 16 bit apps in NT is good too, simply because you can reboot the 16 bit subsystem so easily.

Windows 9x is not quite as robust as NT, but it runs better on a lower-end machine. If you want to use libraries for which there are no current NT equivalents then win9x is a must. [Or cheat and have two computers]. As more "consumer-class" functionality is added to NT the need for using win9x is lessening

Likewise, NT offers many features which are not available in Win95.

Win31 and Win32s is not really suited for application development. Borland C++ certainly can be used in this situation, but not Visual C++. Consider relegating this platform to a test environment if a Win32s version is required.

Windows CE is currently only a target platform, and not one to run on your primary development PC.
[Top of Section] [Index]

2.5. Do I need the Win32 'Platform' SDK?

2.6. What important things should a newbie learn?

1. The class libraries are only a foundation: there is nothing wrong in using the raw Win32 API.
2. Use the on-line help. Everyone else does.
3. Learn to write 32 bit applications without bothering to serve a 16 bit apprenticeship. And ignore dated books which cover 16 bit programming: there are some things programmers were not meant to know.
4. Look through the sample programs your compiler ships with: they are a good way of learning how to write windows applications and a source of code.
5. Resource files (.RC) are really text files and sometimes are best edited as such instead of with a resource editor.
6. Step into the source of the class libraries when debugging to find out what's really happening, but avoid modifying the source or making big assumptions about the implementation unless you have to -either of these tricks increase your maintenance costs. If you do have to modify the class libraries, cutting and pasting the source into your own classes first is usually better.
7. Sometimes there really are bugs in the OS, class libraries and compiler code generators. But usually, when a routine doesn't work the way you expected, the fault is yours. Either there is a defect in your code, or there is a defect in your assumptions. With experience, both of these situations will arise less often.
8. Allow about six months to become reasonably competent, but never think you can stop learning.

2.7. Are there any on line introductions to Windows programming?

• Developer Central This one of the the best sets of introductory tutorials for Windows, C++, MFCand VB programming to be found.
• A beginners guide to programming the Win32 SDK By Stephen Haunts
  Technically reasonably accurate, though a bit low on the spelling and grammar stakes. It stops before getting into very much detail, and is not a substitute for a good book.
• Reliable Software's code samples
  Some mildly opionated web pages and code samples covering Win32 coding in C++.

2.8. Do I need MFC to write an application?

The main justification for raw API code is usually size and performance -raw Win32 apps don't need MFC libraries, so can load faster and take up space. Anything intended primarily for background use -a little taskbar applet for example- should consider a raw implementation rather than MFC, which is a bit of overkill. For ActiveX controls downloaded from the net, download time is critical, and eliminating the need for MFC libraries helps there. With a really large program the gains of MFC are less clear -so much of the wheel gets reinvented that you end up with something almost as large but with worse documentation and more maintenance issues. You also lose all the performance gains the MFC code and the class wizards can deliver once you know how to make effective use of them.

Some things are very hard to write in raw Win32. OLE automation is a case in point, while database access needs a fair amount of support code whether the connectivity interface is ODCB, RDO, ADO or OLE DB. The ATL libraries are a halfway house -lighter weight than MFC, purer C++ than MFC, and utterly unreadable to the uninitiated. The STL (Standard Template Libraries) are also a good accessory to raw API and ATL coding, they give you the C++ standard string classes and semi decent vector and list structures. As for COM, if you use the "#import" pre-processor directive in VCC5 and up, the compiler makes COM calls in C++ workable, even for IDispatch derived interfaces.

Finally, if you do want to reinvent the wheel and build a better class library, go ahead. It is not impossible, just time consuming. Borland's OWL2.x library is still regarded by many as a better class library than MFC [this FAQ's author is one of them], and other people have done commercial class libraries (Metrowerks do a cross platform one, for example), or freeware (e.g. Sam Blackburn's WFC classes). An alternate trick is to write 'raw API' classes which can be used standalone or mixed in with MFC and ATL code, to fill in their gaps. For example a CDIBitmap class can provide bitmap access, while the core NT device hierarchy can be supported by a single header file's worth of classes with names like COSDevice, COSFile, COSSerialPort, COSWaitableTimer and so on. This lets you extend MFC where it is weak, yet not be tied to its use.
[Top of Section] [Index]

2.9. Are there alternative C++ class libraries to MFC?

However, one of the most valuable class libraries is free and comes in source form: Sam Blackburn's WFC class library . This library (as of release 39) includes a better XML parser than the IE5 one, and lots of really interesting goodies. It also provides an example of a) how a skilled programmer can build up a reusable library set to enhance their own productivity, and b) how a generous programmer can give away their work for the benefit of the entire community. Even if you choose not to use it, it can be used as a reference example of Win32 class library design and implementation.
[Top of Section] [Index]

2.10. How do I migrate from Unix?

It's inevitable that when learning the Win32 API you will discover a lot of things that don't make a lot of sense. For example, why are there so many slightly different APIs -TextOut, ExTextOut and TabbedTextOut and PolyTextOut? Historical reasons. Likewise the split between NT Executive objects and all those other objects in a system: GDI objects, Windows and sockets. As the platform evolved, the API grew to match. Legacy support and a rapid evolution has been key strengths of Windows, and this shows in an API that from a Unix developer perspective is an incoherent mess. Well, too bad. It's like the x86 - an ugly duckling that has grown up into a successful, but still ugly, duck. Resistance, as they say is futile.

Migration Tips

• Don't waste time developing for the Posix subsystem. Try and use the Win32 API with the C/C++ run time libraries to make things seem relatively similar.
• NT5's object model is not too different from Unix's 'everything is a file' world. Just use WaitForMultipleObjects() instead of select().
• For some reason message queues aren't waitable objects; MsgWaitForMultipleObjects() is a contrived way of including one of these in the selection.
• You can't wait on sockets in Win95, only NT and Win98 with Winsock 2. Use WSASelect() instead.
• When opening files with fopen(), don't forget the "b" argument to indicate binary mode. Otherwise crlf translation will catch you out.
• Beware of assuming case sensitivity in naming files. But using forward slashes in path names is usually ok.
• Your C++ compiler should support STL quite happily, although you may need some patches: the standard distributions are invariably inadequately tested.
• There is no fork(), and no real equivalent. Somewhere in the NT executive it -and a process heirarchy- are supported, but they don't make it as far as the Win32 subsystem. Threads and CreateProcess() is the best you can get.
• Don't expect signal() to work well either. It may be in the run time library, but that doesn't mean that it works the way you expect.
• If moving from a workstation environment, remember that the byte order for x86 CPUs is not that of the rest of the world: use htons() and htonl() and the inverses when doing socket work.
• There is no direct equivalent of a setuid bit for running programs.

3. Development Tools

This is a list of shipping products which can be used to generate Win32 code. This is also the section of the FAQ which dates the fastest, as many vendors update their products every 12-18 months, with bug fixes -"service packs"- available in the meantime.

Important Fact Number 1. No particular preference over development tools is being made here: purchase decisions need to made by individuals/groups based on their own needs, abilities, funds and long term plans.

Important Fact Number 2. There are no silver bullets in software engineering. Despite what the advertisments will tell you about application development at a click of a button, Windows programming requires skill, knowledge and hard work. Debug facilites and customer support can be as important as compilation speed or syntax highlighting.

As most products are available in "lite" editions, evaluating them all may cost time more than money. But it may prove a worthwhile investment.

NB: detailed but moderately opinionated product reviews are available nearby

3.1	Visual C++ /Visual Studio
3.2	Visual Basic
3.3	Borland/Inprise Delphi
3.4	Borland/Inprise C++5.x and C++ builder
3.5	Metrowerks CodeWarrior
3.6	Intel VTune
3.7	lcc-win32
3.8	Assemblers
3.9	Also Available
3.10	Watcom C++ 11
3.11	Microsoft Visual J++
3.12	Gnu for Win 32
3.13	Configuration Management Tools
3.14	What other tools are useful?
3.15	Books

3.1. Visual C++ /Visual Studio

The C and C++ compilers are probably the currently most popular compilers of these languages in the Win32 community. This means that many books and add-on tools focus exclusively on these tools. They are also invariably the first compilers to support new OS developments from Microsoft. Compilation speed and generated code performance are so-so, debugging facilities excellent once you get the hang of them.

One critique of these tools is that their development evolves for strategic reasons, rather than those of immediate benefit to the customers. For example the 32 bit IDE/compilers can not generate or debug 16 bit or DOS applications, and provide much more support for developing COM objects than displaying GIF and JPEG images. Likewise the Java tools may be great for 'DNA' use, but not for portable Java application development. But if you want to go where Wintel want to take you, these products can make the journey easier -especially if you prefer SQL server over Oracle.

Although single language options can be purchased separately, it may be cost effective to buy the complete set. A large hard disk is then obligatory. The Enterprise edition needs an even larger hard disk, but gives you a source code control tool (invaluable) and lots of back office integration toys (variable value). The amount of after sales support you get is still near zero.

Links: A more detailed review; the product's home page
[Top of Section] [Index]

3.2. Visual Basic

Although through VB many Win32 API calls can be made, it can be a rather tortuous process, as you need to cut and paste in every function declaration prior to usage. Some data structures and programming paradigms do not translate easily to the VB world. Tip: The reason you can't import a function such as ShellExecute() is that functions exported by the OS which take strings have an ASCII version -ending in 'A" and a UNICODE version ending in W: you need to import ShellExecuteA.

Visual Basic is a very fast way of getting an application up and running -and the built in setup kit is pretty good for distributing programs. (except that it always includes the version of CTL3D32.DLL used by your OS, and not theare separate versions required for NT and '9x). In particular it's very good at seamless OLE Automation and ActiveX integration -much better than Visual C++. This -and the fact that cut down versions come with MS Office programs means it is worth learning and using in the 'appropriate' parts of any major programming project. For example, it can be used to integrate your compiler, source code and project management tools with relative ease.

In terms of popularity, Visual Basic is probably the most widely used language on the planet, although it is not so common in commercial shrink-wrapped software products. It's good for quick and dirty development, database integration and the development of usable front ends. With the native compiler and a rudimentary object model, the language may even be usable for large or commercial performance applications.

For low level Windows hacking, it is not the tool of choice -unless backed up by DLLs, OCXs or even device drivers.

Link: review
[Top of Section] [Index]

3.3. Borland/Inprise Delphi

Like VB, it can be a fast development tool in the hands of a moderately experienced user, and there is enough of a developer community to ensure that support for new OS technologies -DirectX, IE4 Common Controls- comes out relatively rapidly. Many people love it, especially recreational programmers'. Once nice feature is that it is a reasonable language in software engineering terms.

It's worth noting that Delphi does seem to be popular for an in house development tool in many high salary financial organisations. Time to market and database integration are probable reasons for this.
[Top of Section] [Index]

3.4. Borland/Inprise C++5.x and C++ builder

Although apparently the system does support OCX creation and use, the lack of OCX support in the Resource Workshop, and the absence of any OCX Expert, means that it isn't really suitable for OCX development and use. It does still support VBXs in 32 bit apps though, which can be very useful for porting legacy apps.

The early 5.0 version had a reputation for leaks and bugs. Version 5.02 ships with the MFC source, so that MFC applications can also be built with the compiler.

C++ Builder is a newer Delphi-like interface to the compilation tools: it seems to be a nifty way of doing C++ coding. The Enterprise edition of this is particularly well rounded.

Links: Inprise home page
[Top of Section] [Index]

3.5. Metrowerks CodeWarrior

With MFC support now, and a resource editor due in summer '98, and too, this could become a reasonably productive Win32 development. Low cost editions are available. One major weakness: the resource editor is very primitive compared to modern Windows IDEs.

Link: Metrowerks
Link: review
[Top of Section] [Index]

3.6. Intel VTune

1. C++ and Fortran compiler that knows about Pentium III floating point registers and can generate code which makes use of them.
2. Other compiler switches to do RISC-style aggressive optimisation techniques such as loop unrolling and conditional moves instead of branching.
3. A very good graphical code profiler.

Link: review
[Top of Section] [Index]

3.7. lcc-win32

The IDE is not as full of 'wizards' and other clutter, and is relatively low level, but it is a good low cost introduction to Windows programming. A good install program is a nice feature, as it helps get you started easily.
[Top of Section] [Index]

3.8. Assemblers

There are freeware assemblers,in particular NASM . This can generate Pentium and MMX opcodes and output .obj files in Borland or Microsoft formats.

Links: Paul Hsieh's x86 Assembly page; Win32 coding in assembler
[Top of Section] [Index]

3.9. Also Available

• Symantec C++
• IBM Visual Age for C++

3.10. Watcom C++ 11

3.11. Microsoft Visual J++

Standard Java code should execute on all Java VMs, but the COM enhanced code requires a special JVM, which runs a far more limited set of devices.

For reliable code development fetch the updated compiler patches and the full Microsoft Java SDK, which contains the tools to turn a set of Java binaries into a standalone windows app. Because the MS JVC compiler is free for download it is a low cost way to start programming.

Visual J++ 6.0 is a Java 'variant' which produces code for Windows only. Given the current legal dispute the longevity of this product may be measurable in weeks rather than years: avoid it for anything other than a throwaway application.

Symantec Visual Cafe generates native Win32/x86 binaries, so could be used for developing applications, but you are restricted to the standard Java libraries (or manual imports).
[Top of Section] [Index]

3.12. Gnu for Win 32

There are four versions available, Cygnus's original Cygwin32 and Colin Peters' Mingw32 (Minimalist GNU Win32) version, each with either GCC 2.7.2 or EGCS 1.0 as the compiler. Mingw32 + EGCS is recommended as the best version for Win32 development.

The main difference between Cygwin32 and Mingw32 is that Mingw32 doesn't need the compatibility library (Cygwin32.dll and associated material) that Cygnus provides. This loses part of the Unix compatibility layer, but gives smaller and faster compiled binaries. The only reason to prefer Cygwin32 over Mingw32 would be for porting code from Unix.

Regardless of which version you intend to eventually use, you need to download the complete Cygwin32 development kit first; Mingw32 is distributed as a patch for Cygwin32. If you intend to use EGCS rather than GCC as your compiler, you only need the "user tools" version of Cygwin32, instead of the much larger "developer tools" version.

All versions come with the Win32 header files and link libraries (not quite complete and up to date, but close enough for most development requirements).

Installation can be a bit of a pain; coming as they do from the Unix world, these tools don't have the sophisticated automatic installers that Windows users expect. But if you follow the instructions and apply a bit of common sense, it's not too hard.

Relevant web sites:

1. Colin Peters' Mingw32 project . this is the best place to start; it has pointers to everything else you need)
2. Cygnus Solutions' GNU-Win32 project
3. The EGCS home page
4. Mumit Khan's port of EGCS to Win32

3.13. Configuration Management Tools

Some criteria which may be used to assess a product, depending on your current and future needs are:-

• Integration with development tools of choice (IDE, make files)
• Ease of archiving and retrieval of data.
• Integration with other parts of the development process: defect tracking, web based delivery, and testing.
• Scalability to big projects in file, staff or duration terms.
• Multi-project file sharing and branching
• Support for mobile and remote users.
• Administrative tools and facilities.
• Reporting tools to keep the management chain happy.

Financially constrained developers can make do with the freeware gnu RCS tools, or just use the copy of Visual SourceSafe which comes with every Enterprise edition of Visual Studio.

Popular products -usually with free trial editions for downloading- include:-

Merant PVCS

A full blown CM system with optional defect tracking and web integration. Its feature set seems comparable with MKS Source Integrity. Formally marketed by Intersolv.

Visual Source Safe

This comes for free with enterprise editions of Visual Studio. It's relatively easy to start using, and integrates well with the Visual Studio product line. It's weaknesses show up over time:-

• Branching isn't too successful as it's hard to break Studio's bindings to particular projects
• Lacks an integrated defect tracking system.
• The administrator can't override someone else's actions -such as undo a file checking out.
• Doesn't scale well to very large or distributed projects.
• Very slow on Samba servers -but good on NT. File locking is the problem, apparently.
• Web publishing only really works to NT/Windows servers.

MKS Source Integrity

This is an expensive but well proven product. A nice feature about this one is that you can define actions to to be invoked when certain triggers occur. For example, after every check in the project leader can be emailed with a summary message, or a recompilation can be forced to verify that the code being checked in doesn’t break the build.

The GNU implementation of RCS

The ci and co commands can be used to build up an RCS database, and integrated with make and batch files with some effort. For team development you need a file system with symbolic linking, so that each team member's RCS directory points to the same place. That effectively means a Unix file server has to be used as the source repository.

Reliable Software's Code Co-op

This is an interesting shareware tool: a CM system which can use email as the synchronisation mechanism. This makes it ideal for peer-peer and distributed development.

QVCS

A shareware CM tool, which looks reasonable for individual use.

NB: don’t just check it in - back it up. It's what tape drives and CD Writers are for. Most commercial products support OLE automation: with this it's an interesting exercise to write a script to get the entire heirachy into a directory tree and then tar/zip up for a vendor independent database snapshot.
[Top of Section] [Index]

3.14. What other tools are useful?

Code analysers

• Compuware NuMega sell the Bounds Checker tool which verifies all API calls, checks for invalid handles and memory and resource leaks. It's not cheap but very useful: someone in a project team should own a copy, and you shouldn't ship until the problems it reports have been dealt with. The company's Soft Ice product line is for serious hardware debugging.
• Rational Purify This is a competing product to Bounds Checker.
• lint for the PC. This is a static code analyser, which many Unix hackers will be familiar with. Reasonably priced.
• Autoduck. A great little piece of freeware to generate documentation from structured comments in your source -can be used to do HTML documents as well as standard windows formats. [Search for this; its home moves around]

• Win32 "Platform" SDK.
  Not a standalone compiler. But it does include some useful tools. Nowadays downloadable from Microsoft's site.
• NT and Win9x Device Driver Kits.
  You need these to write device drivers. A download from MS
• The appropriate resource kit for your OS
  Lots of handy utilities, including the essential "windiff" application.
• Useful shareware
  4NT, Hamilton C shell : new command shells to make life easier.
• Emacs
  Aficionados of this editor will need the NT Version
• Pencil and paper
  Great for UI design, application architecture design and note taking. Best backed up with a filing system and a routine of reviewing past notes to question documented design decisions.

3.15. Books

Some of the books which are highly regarded are listed below. The exact suitability of individual books depends on what you want to do and what your background knowledge is. Most of the books listed are by the Microsoft Press, as they are the publishers most interested in addressing the needs of Windows Programmers. Addison Wesley and Wrox press also have valuable and high quality titles. All of these books assume prior knowledge of C and C++. NB: DDJ maintains a good database of their book reviews, which is a good source of independent opinions on many of these titles as is this other site

One good strategy on choosing a book comes with experience: go into a bookshop and look for an explanation of something which caused you grief but you now understand -such as COM object thread safety or MFC message routing. Verify that a book which should cover this topic does so in way which you understand. If it doesn't, then you should question the book's value. Then go back to your desk and find the best value on line book store. In particular European developers will find that the cost of US editions is so much lower that they will save money on a US purchase, even once shipping costs have been included.

As well as books, there are some monthly magazines which cover Windows programming in detail:-

Microsoft Systems Journal.

A regular magazine, combining information with some evangelism for the company's latest API, tool or strategy. Often more up to date with operating systems and products than anything else.

Dr. Dobbs Journal.

Another regular magazine, good for reviews of various tools. More independent; less Windows focussed.

3.15.1. Introductory Windows Programming

Programming Windows, Petzold (and Yao), MS Press

Charles Petzold wrote the original Windows programming 'bible' -"Programming Windows" back in the mid eighties -everyone who started Windows programming in those days had -or needed- a copy of this book. Now updated for Win32, Petzold starts the basic paradigms of windows programming -Windows and message queues- and goes on to cover many advanced topics. The book uses C and assumes a prior knowledge of this language. Although the structure of the book does not match C++ and OWL or MFC applications, the chapters on advanced topics -such as drawing- are still invaluable reference material, while the introductory chapters provide an invaluable explanation as into how Windows applications work.
Critique: Some of it is -well- dated, and not really adequately updated to the new OS platforms. The OLE section looks like an afterthought.
March 99: The latest edition is fatter, drops the OLE/COM section in exchange for a music app and adds a rudimentary Internet chapter containing a time synchronisation sample which would never work on Windows NT. There are better alternatives.

Programming Visual C++ , David Kruglinski, Shepherd and Wingo , MS Press, ISBN 1-57231-857-0

This is the successor to Kruglinski's Inside Visual C++ series. In it the authors explain how to write professional looking applications in VCC, covering areas such as the Wizards, OLE, databases, document/view models dialog boxes and basic Internet and ATL programming. For low level Win32 programming this is not the book of choice -but if you need to use MFC as the framework for your app, this is a good starting off point and a reference tome to return to.
Critique: The early editions of this book used to contain an appendix with a reasonable introduction to C++, but this is now absent. Cut and Paste is about the only code reuse strategy covered.

Win32 Programming Rector and Newcomer, Addison Wesley

An excellent alternative to Petzold. Thick and thorough, and without any reminiscing about the old days of Win16. Good value.

Programming Windows 95 with MFC, Jeff Prosise, MS Press

Covering much the same ground as Petzold, Jeff assumes you have a copy of Visual C++ and want to use the MFC classes as the framework for your applications. Knowledge of C++ or C & the Windows API is a prerequisite. This is not your average "how to use the wizards" book.

The Windows 32 API Reference

You should get an on line copy of this. The overview chapters may be worthwhile having on paper and reading, but they date so fast it's hard to justify.

3.15.2. Advanced Programming Topics

Advanced Windows, Jeffery Richter

This is the definitive guide to the new features of the Win32 API -especially on NT. Jeff covers advanced topics such as processes and threads, Overlapped IO, Completion Ports, Structured Exception Handling and UNICODE. Through a skilful use of Dialogs, he manages to demonstrate all these features without appearing to write full scale applications. Application structure and the user interface and graphical aspects of windows are not covered. [Buy this book and then write your name on it in big letters to stop it going for a walk].
A new version is due in late '99

MFC Internals, Scott Wingo

If you use MFC and want to know how it works -or why your code doesn’t behave as expected- this is a good book. It assumes you are already experienced with Win32 and MFC. One of the best adjucts to the on line documents competent MFC programmer needs. This book is not recommended as an introduction to MFC programming.

Inside Windows NT, Second Edition, David Solomon, ISBN 1-57231-677-2

The original edition by Helen Custer was mindnumbingly dull, but after a near complete rewrite the book can now be read from cover to cover. Not only that, it is full of valuable snippets of information and little experiments you can run on your own NT box to peek behind the scenes.
Worthwhile if you're getting into device drivers or want to know what the OS is really up to. Applications should not have to know all this nitty gritty, but the section on scheduling is useful are other chapters on subjects such as file I/O and memory management.
Critique: it lives in an ideal world, in which Blue Screens never happen, NTFS corruption never occurs and NT's security model is both comprehensible and comprehensive.

Programmer's Guide to Windows 95, ISBN 1-55615-834-3

Covers all the new Win95 features and differences with NT. Fairly readable. Part of the MSDN/Win32 on line documentation, so not worth shelling out for on paper. Clearly due for an upgrade.

Inside COM, Dale Rogerson

A book which covers the fundamentals of the component interface model without covering the specifics of the OLE linking and embedding interfaces. Vaguely useful for anyone using COM within or between applications. NB: sequels to this book -Inside COM+ and Inside Distributed COM are in the pipeline.

Inside OLE, Kraig Brockschmidt,

This was the original OLE and COM book -and was never an easy read, even if the second edition is much better than the first. Nowadays it has less appeal: other books cover COM better, so this one is only of interest to people with the unwelcome task of implementing OLE2 in raw C/C++. Flicking though this book, you will realise why this is best left to suppliers of libraries such as MFC, OWL and ATL.

Essential COM, Don Box, ISBN 0-201-63446-5

This is a good book -good enough to supplant Inside COM as the definitive bible for COM development. Don's experience broad experience in COM and CORBA, and critical insights into COMs failings give the book more value than MS press offerings. Also it's reasonably up to date, and covers NT5 to an extent. Some chapters are on MSDN. As is common with all COM books, you may get a headache reading it.

Professional ATL and COM, Richard Grimes, Wrox Press

This book fills a niche: how to really make use of ATL, and is a practical counterpart to Don's book. It seems overpriced, the ATL3.0 version costing 50% more than the ATL2.0 book. But if ATL is your chosen class library, $60 is a trivial investment, and if you look round the online booksellers you can get down to a more reasonable price. And it is reasonably readable, full of practical examples and relatively error free.

Win32 System Programming, Johnson M. Hart, ISBN 0-201-63465-1

This is quite a good follow on book to Richter's, focusing on low level synchronisation and communication with a definate Unix like flavour. J.M. Hart is pretty rigorous when it comes to thread safety, so this book may come in handy if you are writing low level or server applications.

Visual Basic, Bruce McKinney ,ISBN 1-57231-422-2

If you really must insist on doing Win32 coding in VB, then read this book -it's on the MSDN CD, albeit without the sample apps. It's actually stricter on coding practices than many of the C++ books, which is as good a reason as any for VB programmers to read this book. And in a world with ubiquitous VBA, all windows Programmers benefit from acquiring VB skills. This book will let you write moderately serious Win32 apps without having to take on the MFC Wizard.

3.15.3. Low level hacking

Inner Loops, Ralph Brown, ISBN 0-201-47960-5

An introduction to x86 assembler for anyone interested in tuning the core of their apps. It's probably due for an upgrade in the 'Katmai timeframe', as it doesn't cover all the subtleties of programming for the latest generations of Intel processors or AMD/Cyrix cores.

Windows Assembly Language and Systems Programming, Barry Kauler, ISBN-0-87930-474-X

Apparently the only book on Windows programming in assembler there is.

Computer Architecture: A Quantitive Approach, Patterson and Hennessy, ISBN 1-55860-329-8

This isn't really an x86 or Windows programming book, but its sections on Pipelining and Instruction Level Parallelism provide the underpinnings of how P6 generation cores work. The memory-hierarchy chapter explains everything you need to know about uniprocessor caches, while the multiprocessing section is the definitive reference of 'relaxed consistency models' for multiprocessing. These are where different CPUs get to see memory writes in different orders: exactly the behaviour you see on a multiway P6/PII box. After reading this book and inner loops you may be able to write code to extract maximum performance from these systems -although for ease of maintenance you may well conclude that is not the route you wish to follow.

Intel Processor Documentation, Intel

PDF files you can download from Intel's developer web site. Get the Intel Architecture Optimisation Manual at the very least.

Developing Windows NT Device Drivers Dekker and Newcomer, Addison Wesley, ISBN 0-201-69590-1

A gentle introduction to device drivers which is as up to date as you can hope (Win98 and NT5 beta 1) with NT and WDM drivers. Readable and with an appendix of common kernel mode API calls. A valuable counterpart to the OSR book, especially if you are just starting out. The list of hardware tasks to run away from is particularly amusing, perhaps even poignant.

Windows NT Device Drivers Mason and Viscarola, OSR

This is the new bible of Device Driver hacking -best value when bought direct from OSR. After reading it you still will be a long way off from writing production quality device drivers, but at least you will have a vague idea of the effort involved. A lot less of an entertaining read than Dekker and Newcomer

3.15.4. Software Engineering and other topics

Recommended reading here includes:-

Code Complete, Steve McConnell, MS press

This is a great book on learning how to write high quality code -and how to debug the bits that aren't so good. It predates C++, COM and interfaces, so some of it's strictures have to be taken with a pinch of salt. However, it is still one of the best books to get 'programmers' on the path to becoming 'software engineers'. Mandatory Reading for software professionals.

Rapid Development, Steve McConnell, MS press

This covers many of the process and organisational issues of team software development. If you are developing by yourself, for yourself, then you can skip this book. Otherwise, it's great. The 'classic mistakes' page is worth photocopying and pinning up on your wall -and the 'what to do when things go wrong' chapter is an excellent rarity in methodology books which always assume that processes are followed and disasters never happen.

Design Patterns, Gamma et al

This is a good book during application design, although in the MFC world half the design is given to you, whether you want it or not.

About Face, Alan Cooper

This book deserves a mention as a classic book on UI design which anyone who designs applications ought to own. It's getting a bit dated these days, as it predates a ubiquitous web.

The Art of Software Testing, Glenn Myers.

There are seemingly no books which cover testing of Windows applications. Instead you have to resort to books such as this 1979 volume, which covers the basics of testing software. It hasn't dated much, although you can help laughing when it describes a thousand line program as 'large'. NB: if testing is important, download our Win32 app walkthrough checklist

4. Win32 Platforms

This section covers the various platforms which support Win32, and the differences between them.

4.1	What Win32 Platforms are there?
4.2	What's in Windows 95?
4.3	What's in Windows NT?
4.4	What about Win32s?
4.5	And WinCE?
4.6	What's in Windows 98?
4.7	What's coming in Windows 2000 Professional?
4.8	Do I need to worry about Win64?

4.1. What Win32 Platforms are there?

Although Win32 is a single programming "interface", there are multiple implementations of this interface, each with their own strengths and weaknesses.

The most widespread platform is Windows95, although Win98 will eventually replace this. Because these two OS versions are often similar, "Win9x" and "Windows 9x" is often used to refer to both of them. The Win9x implementation of Win32 is the most common one found in households and laptops. Because it has evolved from DOS and Win31, its legacy application and hardware support the best, but the overall performance and functionality is hampered by the all the legacy code it both contains and supports.

Windows NT is the heavyweight implementation of Win32, offering much more functionality. Because of its heavy system requirements (realistically a P5/133 and 32+MB RAM), it is normally only used in office desktop and server environments, although corporate laptop use of NT4 is quite high despite its lack of mobile user support.

A well written application can usually run on Windows 9x and NT, possibly changing its functionality at run time. Tip: GetVersionEx is the API call to distinguish between platforms and versions.

Windows CE is the latest addition to the Windows Family. It contains a very cut down kernel and is intended for consumer products and embedded systems. Although an experienced Windows programmer can be programming for CE within a matter of days, the hardware for CE platforms is so radically different from that of classic PCs that designing a single application to run across Win9x, NT and CE is not currently a common practice.

It has long been Microsoft's stated objective to replace the Windows9x kernel with NT. This will be a slow process, as it will not happen until the majority of PCs in regular use are up to running a consumer variant of NT, and all applications and hardware support the OS. Application and hardware developers need to bear this long term strategy in mind, and design for both desktop operating systems.

The future of WinCE is unclear. Its current rate of evolution is immense, and is appearing in some interesting products -especially the Sega games console. It has the potential to become the most widespread Windows platform of all: used almost everywhere a 32 bit embedded CPU is found. It may also fail to justify the current levels of investment, and become another "whatever happened to…?" story in the computing press.

Also deserving a mention is "Win32s", a subset of the Win32 API which can be supported on Windows 3.1 if the appropriate drivers are installed. Use of Win32s is not advised by Microsoft, and recent products (Visual C++ since version 4.2, VB5) can not be used to generate Win32s executables. It was originally intended to serve as a transitional API between Win31 and Nt/Win95, and it is generally now felt that people should really have upgraded to one of these operating systems by now. In the corporate world, support for Win31 may still be a requirement, in which case Win32s is one way of doing so. The platform has also been making a comeback with web browsers for Windows 3.1.
[Top of Section] [Index]

4.2. What's in Windows 95?

• Has many consumer oriented extensions to the basic API.
• Only LOWORD of GDI co-ordinates are used, and many new GDI calls are not implemented.
  This is a side effect of the need to support legacy graphics cards, printers and their associated 16 bit device drivers
• Client side named pipes only.
• No security APIs.
• Port I/O (_in() and _out()) works. For now; this may not hold in later versions builton the NT kernel.
• Threads can block on win16mutex.
  This means while one app is busy in the parts of the OS, the rest will get suspended when they make OS calls. This isn't usually too noticeable, except in high performance/low latency programming problems.
• Different file mapping semantics: all mapped files share the same address in all processes.
• FreeResource() must* be called for every resource loaded with LoadResource().
  NB: OWL2.5 TDib class doesn't do this.
• 32 bit apps can thunk down to a 16 bit DLL.
• BeginUpdateResource() and related calls do not work: you can not modify EXE/DLL resources through API calls.
• Socket handles can not be used as file/system handles (in calls such as WaitForMultipleObjects) (Winsock 2 removes this restriction)

4.3. What's in Windows NT?

• Full 32 bit GDI with clipping paths, and Coordinate Transform Matrices.
• Overlapped I/O
• Services API (like Unix Daemons)
• Can create server side named pipes
• No port I/O allowed from an application [you need a driver]
• Unicode support.
• Support for multiple processors.
• 32 bit apps can not call 16 bit DLLs.
• Real time threads and no app blocking on window resize/move
• Separate WOW subsystems means 16 bit apps can not assume that other 16 bit apps share the same address space.
• Toolhelp32 is not supported.
• DirectX (DirectX 3.0 in NT4.0 onwards, Direct3D in software only with service pack 3)
• NT4 adds "Waitable Timers" for better thread scheduling.

4.4. What about Win32s?

• No thread support or pre-emptive multitasking: explicit Yield(), PeekMessage() and GetMessage() calls are needed to give other applications a chance to run
• Comms, multimedia only through thunking down to the Win16 API
• VB4/32 , VB5 and VC5 applications do not run under Win32s.
• No console support
• Many thunked down functions have the old 16 bit semantics and not any win32 extensions.
• All the restrictions of the win95 implementation also apply

The most up to date version of Win32s is version 1.3: this came out with Win95 and supports the common controls such as tree and list views. Future development is unlikely, as MS do not want anyone to run Win31 any more.

Versions of Visual C++ after -and including- 4.2 do not support Win32s; version 4.1 is the most modern one to do so. The apps you build with VCC4.1 must link dynamically (not statically) to the RTL and class libraries. Look under win32s\redist and win32s\debug on the CD for these DLLs.
[Top of Section] [Index]

4.5. And WinCE?

Some features of the current (CE 2.x) versions of the OS are:-

• Unicode APIs only.
• New UI controls to make efficient use of the display
• In-process COM support (not in version 1)
• No MoveTo() or LineTo. Use PolyLine.

BOOL  InWinNT() //test for NT nature
{
	OSVERSIONINFO osv;
	osv.dwOSVersionInfoSize=sizeof(osv);
	GetVersionEx(&osv);
	return osv.dwPlatformId==VER_PLATFORM_WIN32_NT;
}

BOOL GetFormattedError(LPTSTR dest,int size)
{
	DWORD dwLastError=GetLastError();
	if(!dwLastError)
		return 0;
	BYTE width=0;
	DWORD flags;
	flags  = FORMAT_MESSAGE_MAX_WIDTH_MASK &width;
	flags |= FORMAT_MESSAGE_FROM_SYSTEM|FORMAT_MESSAGE_IGNORE_INSERTS;
	return 0 != FormatMessage(flags,
			NULL,
			dwLastError,
			MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
			dest,
			size,
			NULL);
}

                 //open COM1 for read and write
hPort=CreateFile( "COM1",
                  GENERIC_READ | GENERIC_WRITE, //bidirectional
                  0, 
                 NULL, //no security
                 OPEN_EXISTING,  //this must be set; the ports are already created
                 FILE_ATTRIBUTE_NORMAL, // maybe with | FILE_FLAG_OVERLAPPED  
                 NULL );