Microsoft® Windows'·
`
`Version 3.1
`
`Device Driver Adaptation
`Guide
`
`For the Microsoft Windows Operating System
`
`Microsoft Corporation
`
`Page 1 of 239
`
`

`

`lnfonnation in this document is subject to change without notice and does not represent a commit(cid:173)
`men[ on the part of Microsoft Corporation. The software, which includes infonnation contained in any
`databases, described in this document is fumished under a license agreement or nondisclosure agrec(cid:173)
`men! and may be used or copied only in accordance with the terms of that agreement. It is against the
`law to copy the software except as specifically allowed in the license or nondisclosure agreement. No
`pM of this manual may be reproduced in any form or by any means, eleclronic or mechanical , includ(cid:173)
`ing photocopying and recording, for any purpose without the express written permission of Microsoft
`Corporation.
`
`© 1987- 1992 Microsoft Corporation. All rights reserved.
`Printed in the United States of America.
`
`Copyright © 1991 Linotype AG and/or its subsidiaries. All rights reserved. Helvetica, Palatino, N"ew
`Century Schoolbook, Times, and Times Roman typefonl data is the property of Linotype or its
`licensors.
`Arial, Courier New, and Times New Roman fonts. Copyright © 1991 Monotype Corporation PLC.
`All rights reserved.
`
`Microsoft, MS, MS-DOS, and CodeView are registered trademarks, and Windows and Windows/386
`are trademarks of Microsoft Corporation.
`
`U.S. Patenl No. 49741.59
`
`Adobe and PostScript are registered trademarks of Adobe Systems, Lnc .
`The Symbol fonts provided with Windows version 3. I are based on the CG Times font, a product of
`AGFA Compugraphic Division of Agfa Corporation.
`Apple and TrueType are registered trademarks of Apple Computer, fnc.
`AT&T is a registered trademark of American Telephone and Telegraph Company.
`Compaq is a registered trademark of Compaq Corporation.
`Epson is a registered trademark of Seiko Epson Corporation, Inc.
`Hercules is a registered trademark of Hercules ComputerTechoology.
`Hewlett-Packard, HP, LaserJet, and pel are registered trademarks of Hewlett-Packard Company.
`IBM and OS/2 are registered trademarks of International Business Machines Corporation.
`Helvetica, New Century Schoolbook, PaJatino, Times, and Times Roman are registered trademarks of
`Linotype AG and/or it>; subsidiaries.
`Arial, Courier New, and Times New Roman are registered trademarks of the Monotype
`Corporation PLC.
`Nokia is a registered trademark of Nokia Corporation. (Finland)
`Olivetti is a registered trademark of lng. C. Olivetti.
`Paintbrush is a trademark of ZSoft Corporation.
`VINES is a registered trademark of Banyan Systems, Inc .
`
`Document No. PC29 I 32-0392
`
`Page 2 of 239
`
`

`

`Contents
`
`Introduction ............................................................................................................ ix
`
`How to Use This ManuaL......... ............................................................................ ix
`Document Conventions ...................... .. ..................... _.... .... ......... ..................... ....... x
`
`Part 1 Windows Device Drivers
`
`Chapter 1 Overview 01 Windows Drivers ............................................................................... 3
`1.1 What Is a Device Driver? ................... .............................. ............................ 5
`1.2
`Creating a Device Driver.............................................................................. 7
`1.3
`Guidelines for Designing and Writing a Driver........................................... 8
`1.4 Windows Calling Conventions ....................... ................................ ............. 8
`1.5
`Header Files ....................................................................................... ........... 9
`
`Chapter 2 Display Drivers ..................................................................................................... 11
`2.1 About the Display Driver .............................................................. ............. 15
`2.1.1
`Display-Driver Initialization ...... ....................................................... 15
`GDI Information Structure ............................. .................................. 16
`2.1.2
`Enabling and Disabling the Physical Device ......... ... ....................... 16
`2.1.3
`2.1.4
`Hardware Initialization ..................................................................... 18
`Physical Objects..................................................................... ........... 19
`2.1.5
`2.1.6
`Physical Colors ... ...... .... ........... ...... ... ........................... .......... ....... .... 21
`2.1.7
`Screen Metrics ........... ............... ......... ...... ..................... .......... ....... ... 21
`Lines, Curves, and Polygons ............................................................ 23
`2.1.8
`2.1.9
`Text ................................................................................................... 26
`2.1.10
`Fonts .................................................................................................. 30
`2.1.1 1
`Clipping ............................................................................................ 34
`2.1.12
`Bitmaps ........ ...... ...... ..... ..... .............. ...... ......... ... .... .................. ......... 35
`Device-Independent Bitmaps ........................................................... 37
`2.1.1.3
`DeviceBitmaps ................................................................................. 39
`2.1.14
`Color Palettes ............ ..... ..... ..... .......... ..... .................. .... ......... ... ........ 40
`2.1.15
`2.1.16
`DlBs with Color-Palette Management ............................................. 43
`Stub Functions .. ...... .... ....... ... .................... ..... ..... ..... ....... ....... ........... 44
`2.1.17
`Cursors ............................................................................ .................. 44
`2.1.18
`2. 1.19
`Display-Driver Escapes .................................................... ................ 45
`
`Page 3 of 239
`
`

`

`iv
`
`MicrosoH Windows Device Driver Adaptation Guide
`
`2.1.20 Mouse Trails ... .................................................................................. 45
`2.1.21 Multiple-Resolution Drivers ............................................................. 46
`2.1.22 Microsoft Windows for Pen-Computing Extensions ....................... 48
`About Display-Driver Resources ............................................................... 49
`2.2
`2.2.1
`Stock-Fonts Resource ....................................................................... 50
`Configuration Resource .................................................................... 51
`2.2.2
`2.2.3
`Color-Table Resource .................................... .. ................................. 51
`2.2.4
`Icon, Cursor, and Bitmap Resources ................................................ 51
`2.2.5
`Large Icons and Cursors ................................................................... 54
`2.2.6
`Optimizing Performance................................................................... 54
`Function Reference ............... ...................................................................... 55
`2.3
`2.4 Windows for Pen Computing Function Reference .............................. ...... 62
`File-Fonnat Reference.......... ...................................................................... 64
`2.5
`
`D i sp lay G ra b b ers ",,,,,,,,,,,, .••.......... ,,,,.,,,,.,,.,, •....•....•..•...........•. " .•. " ••. ".""."""."" 69
`About the Standard-Mode Display Grabber .............................................. 71
`3.1
`3.1.1
`Standard and Extended Functions .................................................... 72
`3.1.2
`Standard-Function Dispatch Table ................................... ................ 73
`3.1.3
`Extended·Function Dispatch Table .................................................. 73
`3.1.4
`Coordinate System ............................................................... ............. 74
`3.1.5
`Buffer·Size Calculations................................................................... 75
`Binary-Image File ............................................................................. 75
`3.1.6
`3.2
`About the 386 Enhanced-Mode Grabber ................... ... ....... ...................... 75
`3.2. 1
`Initialization ........ .............................................................................. 75
`3.2.2 Window Painting and Updating ....................................................... 76
`Virtual-Display Device Services ...................................................... 76
`3.2.3
`On-Screen Selection ......................................................................... 77
`3.2.4
`Screen Captures ..................... ............ .......... ..................................... 78
`3.2.5
`3.3
`Standard-Mode Function Reference........... ................................................ 78
`Standard-Mode Structure Reference ............................ .............................. 85
`3.4
`3.5
`386 Enhanced-Mode Function Reference ................................ .................. 92
`3.6
`386 Enhanced-Mode Structure Reference ............................................... 105
`
`P ri nle r D rive rs """""""""""""""""""" """""""" """"""""""" """"" """ """ 1 0 7
`About the Printer Driver........................................................................... 109
`4.1
`Printer-Driver Initialization ................................................... . ,....... 109
`4.1 .1
`GDI Information Structure ............................................................. 110
`4.1.2
`Enabling and Disabling Physical Devices ............................ .......... 110
`4. 1.3
`Device-Context Management....... .................................. ................ III
`4.1.4
`4.1.5
`Dimensions and Mapping Modes ....... ............................ ...... ..... ..... 112
`
`Chapler 3
`
`Chapler 4
`
`Page 4 of 239
`
`

`

`Contents
`
`v
`
`Printer-Dri ver E nvironment................................................. ........... 113
`4.1.6
`Device-Mode Dialog Boxes ........................................................... 114
`4.1.7
`4.1.8
`Printer-Device Modes..................................................................... 115
`I 17
`Per-Page Printer Settings ................................................................
`4.1.9
`4.1.J 0
`I 18
`Printer-Model Names .....................................................................
`Standard Print Dialogs.................................................................... 118
`4.1.1l
`4.1.12
`Printer Entries in the WIN .lNI File ................................................ 119
`Physical Objects.............................................................................. 119
`4.1.13
`4.1.14
`Device Pens and Brushes................................................................ 120
`4.1.15
`Device Fonts ............... ........... .................. ...... ........... ...................... 120
`4.1.16
`Color ............................................................................................... 121
`4.1.17
`Output ............................................................................................. 121
`4.1.18
`Text .......................................................................... ....................... 122
`4.1.19
`Fonts ............................ ............... ..... ................................................ 122
`4.1.20
`Device-Independent Bitmaps ......................................................... 124
`4. 1.21
`Print Jobs........................................ ................................................. 125
`4.1.22
`Banding Drivers .............................................................................. L27
`4.1.23
`Other Escapes ........... ................ .............................................. ........ 129
`4.1.24
`Print Manager Support.................................................................... 130
`4.1.25
`The Bmte Functions ....................................................................... 130
`4.1.26
`GOT Priority Queues ....................................................................... 133
`4.1.27
`Stub Functions ....................................................... .... ..................... L34
`4.1.28
`Install ing Over Previous Versions...... ....................................... ..... 134
`4.2
`Function Reference...... ...................... ....................................................... 134
`4.3
`Printer Environment Function Reference .......................... ...................... 142
`4.4
`Priority-Queue Function Reference ......................................................... 145
`4.5
`Print Manager Function Reference .......... ................................................ 148
`4.6
`TmeType StmclUre Reference ................................................................. 155
`4.7
`File-Format Reference. ............................................................................. 157
`
`Chapter 5 Network Drivers .................................................................................................. 159
`5.1
`About the Network Dri ver ........................................................................ 16L
`5.l.!
`InitiaLizing the Driver ..................................................................... 161
`5.1.2
`Enabling and Disabling the Driver ................................................. 16.1
`5.L.3
`Network Capabilities ............................................. ......................... 162
`5.L.4
`Connection Functions ..................................................................... 162
`5.1.5
`Printing Functions ........................................................................... 163
`5.1.6
`Dialog Functions............................................................................. 164
`5.1.7
`Administrative Functions ............................................................... 165
`Long-Filename Functions .................... .. ......................................... 165
`5.1.8
`
`Page 5 of 239
`
`

`

`vi
`
`Microso" Windows Device Driver Adaptation Guide
`
`Error-Handli ng Functions .............. ................................................. 166
`5.1.9
`5.1.10 User Functions ................................................................................ 166
`5.2
`About the Network-Driver Support Software ................ .......................... 167
`5.2.1
`Network Support for 386 Enhanced-Mode Windows.................... 167
`5.2.2
`Networks in Standard-Mode Windows ........... ............................... 17l
`5.2.3
`Exported Functions ......................................................................... 172
`5.2.4
`Reserved Ordinals ........................................................................... 173
`5.2.5
`String Handling ...................................................... ......................... 173
`5.2.6
`Passing Buffers ............................................................................... 173
`5.2.7
`Data Structures ................................................................................ 173
`5.3
`Function Reference .............................................. ..................................... 174
`5.4
`Long-Filename Function Reference................................ ......................... 208
`5.5
`Structure Reference ........ .......................................................................... 220
`5.6
`Return Values ........................................................................................... 226
`
`Chapler 6 Keyboard Drivers ................................................................................................ 229
`6.1
`About the Keyboard Driver ...................................................................... 231
`6.1.1
`Initializing the Driver. ..................................................................... 231
`6.1.2
`Enabling and Disabling the Driver ................................................. 232
`6.1.3
`Keyboard-Interrupt Handler ...................................... ..................... 233
`6.1.4
`Keyboard-Event Callback Function ............................................... 234
`6.1.5
`Initialization File Entries for Keyboard .......................................... 235
`6.1 .6
`Translations ........... .................. ..... .................... .......... ....... ..... ......... 235
`6.1.7
`Virtual-Key Codes .......................................................................... 236
`6.1.8
`ANSI Characters ............................................................................. 243
`6.1.9
`OEM Characters .... ......................................................................... 243
`6.1 .10
`Scan Codes ................................................ ....... ............................... 244
`6.1.11 Key-Translation Tables......... .......................................................... 244
`6.1 .12
`Language-Specific Libraries........................................................... 245
`6.1.13 Miscellaneous Keyboard Services .................................................. 246
`6.2
`Function Reference.. ......................................................... ........................ 246
`6.3
`Structure Reference .................................................................................. 264
`6.4
`Keyboard-Initialization Setting Reference .................. ...................... ....... 266
`
`Chapler 7 Communication Drivers ..................................................................................... 269
`7.1
`About the Communications Driver .......................................................... 271
`7.1.1
`Base Address and IRQ Selection .................................................... 271
`7.1.2
`16550a UART FIFO Buffer ........................................................... 271
`7.1.3
`CommWriteString and EnableNotification Functions ................... 272
`
`Page 6 of 239
`
`

`

`Contents
`
`vii
`
`Communication Escapes ................................................................. 272
`7.1.4
`Baud-Rate Indexes ... ....... .... ......... .... ......... ....... .......... .... ..... ... ......... 272
`7 .l.5
`7.2
`Function Reference ........... ........................................................................ 273
`7.3
`Structure Reference .... ...... ................................................ ....... ......... ..... ... 288
`
`Chapter 8 Mouse Drivers .................................................................................................... 295
`8.1
`About the Mouse Driver ........................................................................... 297
`Mouse Initialization and the Interrupt Handler .............................. 297
`8.1.1
`8.1.2
`Serial Port Usage ............................................................................ 298
`8.1.3
`Customizing the Mouse Dialog Box in Control Panel.. ................. 298
`8.1.4 Windows for Pen Computing Compatibility.. ................ ................ 303
`8.1.5
`Mouse Support for Non-Windows Applications ............................ 304
`8.2
`Function Reference.... ....... .......... .............................................................. 306
`Structure Reference .... ..................... ............ ................ ..... ................ ........ 31 J
`8.3
`
`Chapter 9 Miscellaneous Drivers ....................................................................................... 313
`9.1
`About the Audio Drivers .......................................................................... 315
`9.2
`About the Language Libraries .................................................................. 315
`9.3
`About the Installable-Driver Interface ..................................................... 315
`
`Part 2 General Reference
`
`Chapter 10 Graphics Function Directory .............................................................................. 319
`
`Chapter 11 Graphics-Driver Escapes ................................................................................... 395
`11.1 About the Graphics-Driver Escapes......................................................... 397
`J 1.2 Obsolete Escapes .... ..... .......... .......... .......... ........ ....... ...................... .......... 397
`11.3 Escape Reference. ..................................................................................... 398
`
`Chapter 12 Graphics-Driver Types and Structures ............................................................. 453
`12.1 Types .............. ....... ............................................................................. ...... 455
`12.2 Structures .................................................................................................. 456
`
`Chapter 13 Font Files ............................................................................................................. 515
`13.1 Font Files .................................................................................................. 517
`13.2 RasterGlyphs ............................................................ ................. .............. 518
`13.3 Vector Glyphs ........................................................................................... 519
`
`Page 7 of 239
`
`

`

`viii
`
`Microsoft Windows Device Driver Adaptation Guide
`
`Chapter 14 Setup Information Files ..................................................................................... 521
`14. 1 About the Infonnation Files ..... ......... ............................ ........................... 523
`14.1.1
`Infonnation-File Syntax ................. ....... ... ....................................... 524
`14.1.2
`Information Files for Display Dri vers ............................................ 525
`14. 1.3
`Information Files for Printer Drivers .................................. ............ 525
`Information Files for Network Installation..................................... 526
`14. I A
`14.2
`Information-File Section Reference ......................................................... 526
`
`Part 3 Appendixes
`
`Appendix A Binary and Ternary Raster-Operation Codes ................................................... 551
`A. I Binary Raster Operations ............. ............................................................ 551
`A.2
`Ternary Raster Operations............................ .............. .............................. 554
`
`Appendix B Character Sets .................................................................................................... 563
`B.I
`ANSI Character Set ................................................................................. 564
`B.2
`Symbol Character Set ..................................................................... ......... 565
`B.3 OEM Character Set .......................................................... ................ ........ 566
`
`Appendix C Windows Interrupt2Fh Services and Notifications ......................................... 567
`C I About the Services and Notifications ....................................................... 567
`C. I.I
`Service Functions .............................................................. .............. 568
`C 1.2
`Noti ficati on Functions .................................................................... 569
`C I.3
`Critical Section Handling........................ ........................................ 569
`C IA
`Releasing the Time Slice ........................................................ ........ 570
`C I.5
`Virtual -Display Device Services and Notifications ....................... 570
`C2
`Service and Notification Function Reference .......................................... 571
`C3 Virtual-Display Device Function Reference ............................................ 586
`C.4
`Structure Reference .................... ................. ................................... .......... 592
`
`Page 8 of 239
`
`

`

`Overview of Windows Drivers
`
`Chapter 1
`
`l.l Whal Is a Device Driver? ............................................................................ 5
`1.2
`Creating a Device Driver ............................ ................................................. 7
`1.3
`Guidelines for Designing and Writing a Driver ..................... ..................... 8
`1.4 Windows Calling Conventions ........... ................................ ......................... 8
`1.5
`Header Files ........... ...... ..... ....... ................. ...... .............. ........... .... ................ 9
`
`Page 9 of 239
`
`

`

`Chapter 1 Overview of Windows Drivers
`
`5
`
`This chapter describes the purpose and function of Microsoft Windows 3.1 device
`drivers. You should create a Windows device driver for your device if it is not 100
`percent compatible with the devices suppot1ed by the Windows 3.1 retail device
`drivers, or if you want to offer Windows users access to unique features of your
`device.
`
`1.1 What Is a Device Driver?
`A Windows device driver is a dynamic-link library (DLL) that Windows uses to
`interact with a hardware device such as a display or a keyboard. Rather than
`access devices directly, Windows loads device drivers and calls functions in the
`drivers to carry out actions on the device. Each device driver exports a set of func(cid:173)
`tions; Windows calls these functions to complete an action, such as drawing a
`circle or translating a keyboard scan code. The driver functions also contain the
`device-specific code needed to carry out actions on the device.
`
`Windows requires device drivers for the di splay, keyboard, and communication
`ports. Mouse, network, and printer drivers are required if the user adds these op(cid:173)
`tional devices to the system. The following is a brief description of each type of
`driver.
`
`Driver
`
`Description
`
`Communications
`
`Display
`
`Supports serial and parallel device communications. Windows
`loads and enables this driver, checking the COMM.DRV setting
`in the SYSTEM.INI file to determine the filename of the driver
`to load. The conununications driver must provide function s to
`enable and disable the communication device, to get and set the
`device status, and read and write data through the device. The
`USER module provides a general interface for Windows applica(cid:173)
`tions to call, and translates these calls into appropriate cails to the
`driver. The module name for the conununications driver is
`COMM.
`Supports the system display and cursor for pointing devices.
`Windows loads and enables the display driver, checking the
`DlSPLAYDRY setting in the SYSTEM.lNI file to detennine the
`filename of the driver to load . The display driver must provide
`functions to enable and disable the device, get infonnation about
`the capabilities of the device, carry out graphics operations such
`as drawing lines and transferring bitmaps, and to show and hide a
`cursor. Windows and Windows-based applications call functions
`in the GDI module to carry out graphics operations on the display,
`and GDI translates these calls into corresponding calls to the
`driver. Depending on the capabilities of the display device, GDI
`may generate many calls [Q the driver from a single call from an
`application. The module name for the display driver is DISPLAY.
`
`-
`
`Page 10 of 239
`
`

`

`6
`
`Microsoft Windows Device Driver Adaptation Guide
`
`Driver
`
`Grabber
`
`Keyboard
`
`Mouse
`
`Network
`
`Description
`
`Supports the management of non-Windows applications. Al(cid:173)
`though not technically a driver, a display grabber plays a s imilar
`role as a device driver in helping the WINOLDAP module man(cid:173)
`age non-Windows applications. A display grabber provides the
`support Windows needs to share the display device with 0011-
`Windows applications. WINOLDAP loads the display grabbers
`and calls grabber functions to carry out tasks such as capturing the
`contents of the screen, or managing output from a non-Windows
`application. Windows requires unique display grabbers for stan(cid:173)
`dard and 386 enhanced modes.
`Supports keyboard input. Windows loads and enables the key(cid:173)
`board driver, checIGng the KEYBOARD. DRY setting in the
`SYSTEM.IN! file to determine the filename of the driver to load.
`The keyboard driver must provide functions to enable and disable
`the keyboard, and to translate keyboard scan codes into character
`values and virtual-key codes. A keyboard driver also re places the
`MS-DOS keyboard-interrupt handler with its own. When the
`driver is enabled, the USER module provides the address of a call(cid:173)
`back function thallhe driver calls whenever an event occurs, such
`a keystroke. The module name for the keyboard driver is
`KEYBOARD.
`Supports mouse or other pointing device input. Because a mouse
`is optional, Windows checks the MOUSEDRY serting in the
`SYSTEM.INl fi le to detennjne whether to load a driver. A mouse
`driver must provide function s to enable and disable the mouse, rc(cid:173)
`uieve information about the mouse, and allow users to mooify the
`operation of the mouse through Control Panel . When the driver is
`enabled, the USER module provides the address of a callback
`function that the driver calls whenever an event occurs, such as a
`mouse movement. The module name for the mouse driver is
`MOUSE.
`Supports networks. Because a network is optional. Windows
`checks tile NETWORKDRY setting in the SYSTEM.IN1 file to
`determjne whether to 10ad a driver. A network driver must provide
`functions to retrieve information about the network, redirect local
`drives, and add jobs to a network print queue. The network driver
`may usc MS-DOS functions , NetBJOS routines, and network soft(cid:173)
`ware to complete these network requests. Windows does not re(cid:173)
`quire a specific module name for the network driver.
`
`Page 11 of 239
`
`

`

`Driver
`
`Primer
`
`Chapter 1 Overview of Windows Drivers
`
`7
`
`Description
`
`Supports printer output. Windows applications indirectly load
`printer drivers by csUing the CreateDC function in the GDI mod(cid:173)
`ule. A printer driver must provide functions to enable and disable
`the printer, to get information about the capabilities of the printer,
`to carry out graphics operations such as drawing lines and trans(cid:173)
`ferring bitmaps, and to display dialog boxes to let lhe user change
`printer settings. Windows and Windows-balicd applications caU
`functions in the GD! module to carry out graphics operations on
`the printer, and GO! translates these calls into corresponding calls
`to t.he driver. Windows does not require a specific module name
`for a printer driver.
`
`Since the network and printer dri vers are optional, their module names are not re(cid:173)
`served. However, you should name your driver to represent your device appro(cid:173)
`priately. For example, you could use PSCRIPT for a PostScript® printer driver or
`MSNET for an MS®-Network driver.
`
`1.2 Creating a Device Driver
`
`You create a device driver either by adapting a sample driver, or writing a driver
`from scratch . You can write Windows device drivers in assembly language or in a
`high-level language such as the C language. Assembly language programmers can
`use the CMACROS assembly-language macro package.
`
`To create a device driver, you need to:
`
`1. Read the chapter in this manual that describes the driver for your type of device.
`2. Write the required driver function s.
`3. Create and compile the required resources.
`Every device driver must have at least a VERSIONINFO resource that
`contains the version stamp for the driver. Setup and Control Panel both
`look for this resource when installing drivers . For more information about
`VERSIONINFO and other resources, see the Microsoft Windows
`Programmer 's Reference.
`4. Create a module-definition file that identifies the appropriate module name for
`your driver, and exports the required functions.
`5. Assemble and link your driver.
`6. Test your driver using the debugging version of Windows.
`7. Create an installation file (OEMSETUP.INF) for your driver and related files.
`8. Create your final di stribution disk or disks .
`
`-
`
`Page 12 of 239
`
`

`

`8
`
`Microsoft Windows Device Driver Adaptation Guide
`
`1.3 Guidelines for Designing and Writing a Driver
`When designing and writing your device driver, follow these guidelines:
`
`• Make every effort to make your device driver as small as possible; reserve
`system memory for applications.
`• Use multiple, discardable code segments to