Introduction

The Microsoft(R) Windows(TM) 3.1 operating system is a single-user system
for personal computers. Windows interacts with the hardware devices of a
personal computer through device drivers. This manual describes Windows
device drivers, and provides detailed information about the operation and
interfaces that Windows requires from each type of driver.


How to Use This Manual

Part 1, Windows Device Drivers, consists of nine chapters that provide
information on writing or modifying specific Windows 3.1 device drivers.
Chapter 1, Overview of Windows Drivers, provides information about creating
device drivers. Chapters 2 through 9 contain information about specific
drivers, such as display, printer, network, keyboard, communication, and
mouse drivers.

Part 2, General Reference, consists of five chapters that provide detailed
information about the interfaces and file formats used by device drivers.
Chapters 10 through 13 provide detailed information for display and printer
drivers. Chapter 14, Setup Information Files, provides information about
the format of the OEMSETUP.INF file, which is used by Windows to install
your device drivers.

The appendixes provide tables containing information about raster operation
codes and characters sets. Appendix C, Windows Interrupt 2Fh Services and
Notifications, provides detailed descriptions of the Interrupt 2Fh
interface supported by Windows. Device drivers and MS-DOS(R) programs can
use this interface to communicate with Windows.


Document Conventions

The following conventions are used throughout this manual to define syntax.

Convention    Meaning
---------------------------------------------------------------------------

Bold text     Denotes a term or character to be typed literally, such as a
              function name (BitBlt) or a statement keyword (DESCRIPTION).
              You must type these terms exactly as shown.

Italic text   Denotes a placeholder or variable: You must provide the
              actual value. For example, the statement
              MoveCursor(wAbsX,wAbsY) requires you to substitute values for
              the wAbsX and wAbsY parameters.

[ ]           Enclose optional parameters.

|             Separates an either/or choice.

...           Specifies that the preceding item may be repeated.

               BEGIN
               .
               .
               .
               END
              Represents an omitted portion of a sample application.

In addition, certain text conventions are used to help you understand this
material.

Convention       Meaning
---------------------------------------------------------------------------

SMALL CAPITALS   Indicate the names of keys, key sequences, and key
                 combinations--for example, ALT+SPACEBAR.

FULL CAPITALS    Indicate filenames and paths, most type and structure
                 names (which are also bold), and constants.

monospace        Sets off code examples and shows syntax spacing.

Chapter 1  Overview of Windows Drivers

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 supported 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 functions; 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 display, keyboard, and
communication ports. Mouse, network, and printer drivers are required if
the user adds these optional devices to the system. The following is a
brief description of each type of driver.

Driver           Description
---------------------------------------------------------------------------

Communications   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 communications driver
                 must provide functions 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
                 applications to call, and translates these calls into
                 appropriate calls to the driver. The module name for the
                 communications driver is COMM.

Display          Supports the system display and cursor for pointing
                 devices. Windows loads and enables the display driver,
                 checking the DISPLAY.DRV setting in the SYSTEM.INI file to
                 determine the filename of the driver to load. The display
                 driver must provide functions to enable and disable the
                 device, get information 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 to the driver from a single call from an
                 application. The module name for the display driver is
                 DISPLAY.

Grabber          Supports the management of non-Windows applications.
                 Although not technically a driver, a display grabber plays
                 a similar role as a device driver in helping the WINOLDAP
                 module manage non-Windows applications. A display grabber
                 provides the support Windows needs to share the display
                 device with non-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 standard and 386
                 enhanced modes.

Keyboard         Supports keyboard input. Windows loads and enables the
                 keyboard driver, checking the KEYBOARD.DRV setting in the
                 SYSTEM.INI 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 replaces the MS-DOS
                 keyboard-interrupt handler with its own. When the driver
                 is enabled, the USER module provides the address of a
                 callback function that the driver calls whenever an event
                 occurs, such a keystroke. The module name for the keyboard
                 driver is KEYBOARD.

Mouse            Supports mouse or other pointing device input. Because a
                 mouse is optional, Windows checks the MOUSE.DRV setting in
                 the SYSTEM.INI file to determine whether to load a driver.
                 A mouse driver must provide functions to enable and
                 disable the mouse, retrieve information about the mouse,
                 and allow users to modify 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.

Network          Supports networks. Because a network is optional, Windows
                 checks the NETWORK.DRV setting in the SYSTEM.INI file to
                 determine whether to load 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 use MS-DOS functions,
                 NetBIOS routines, and network software to complete these
                 network requests. Windows does not require a specific
                 module name for the network driver.

Printer          Supports printer output. Windows applications indirectly
                 load printer drivers by calling the CreateDC function in
                 the GDI module. 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 transferring bitmaps,
                 and to display dialog boxes to let the user change printer
                 settings. Windows and Windows-based applications call
                 functions in the GDI module to carry out graphics
                 operations on the printer, and GDI translates these calls
                 into corresponding calls to the driver. Windows does not
                 require a specific module name for a printer driver.

Since the network and printer drivers are optional, their module names are
not reserved. However, you should name your driver to represent your device
appropriately. For example, you could use PSCRIPT for a PostScript(R)
printer driver or MSNET for an MS(R)-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 functions.

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 distribution disk or disks.


1.3 Guidelines for Designing and Writing a Driver

When designing and writing your device driver, follow these guidelines:

o   Make every effort to make your device driver as small as possible;
    reserve system memory for applications.

o   Use multiple, discardable code segments to help reduce the amount of
    driver code needed in memory at any given time.

o   Use an automatic data segment only if necessary.

o   Make resources discardable, and lock them in memory only when needed.

o   Use the stack sparingly. Because device drivers use the stack of the
    application that initiated the call to the driver, there is no way for
    the driver to determine how much available space is on the stack.

o   Check for NULL pointers to avoid a general protection faults from using
    an invalid selector.

o   Check the segment limits when reading from or writing to allocated
    segments to avoid a general protection fault from attempting to access
    data beyond the end of a segment.

o   Use the __ahincr constant when creating selectors for huge memory
    (allocated memory greater than 64 kilobytes). Other methods of selector
    arithmetic can create invalid selectors and cause general protection
    faults.

o   Create code-segment aliases for any code to be executed from data
    segments. Attempting to call or jump to a data segment address
    generates a general protection fault.


1.4 Windows Calling Conventions

This manual presents the syntax of most functions in C-language notation.
All such functions are assumed to be declared as FAR PASCAL functions, and
Windows will call these functions as such. In general, exported functions
in a device driver must execute the standard Windows prolog on entry and
epilog on exit. For more information about the prolog and epilog, see the
Microsoft Windows Programmer's Reference.

The following list highlights the calling conventions:

o   Set the DS register to the selector of the driver's automatic data
    segment.

o   Save and restore the following registers if used: SS, SP, BP, SI, DI,
    and DS.

o   Clear the direction flag if it has been set or modified.

o   Place 16-bit return values in the AX register; 32-bit values in the
    DX:AX register pair.

o   Execute a FAR return.

Windows pushes all parameters on the stack in a left to right order (the
last parameter shown in the function syntax is closest to the stack
pointer). Windows also passes pointers parameters as 32-bit quantities,
pushing the selector first then the offset. This allows exported functions
to use the lds or les instructions to retrieve pointers from the stack.


1.5 Header Files

When writing assembly-language drivers, you may need to use the following
header files.

File          Description
---------------------------------------------------------------------------

CMACROS.INC   Contains a set of assembly-language macros that provide a
              simplified interface to the function and segment conventions
              of high-level languages, such as C and Pascal.

GDIDEFS.INC   Contains definitions for symbolic constants and structures.
              To shorten the assembly time and cross-reference lists, you
              can selectively include parts of GDIDEFS.INC by defining
              equates that tell the assembler which parts to include.

           Equate              Description
           ----------------------------------------------------------------

           incLogical equ 1    Includes logical pen, brush, and font
                               definitions.

           incDevice equ 1     Includes the symbolic names for GDIINFO
                               definitions.

           incFont equ 1       Includes the FONTINFO and TEXTXFORM
                               definitions.

           incDrawMode equ 1   Includes the DRAWMODE data structure
                               definitions.

           incOutput equ 1     Includes the output style constants.

           incControl equ 1    Includes the escape number definitions.

WINDEFS.INC   Contains definitions for symbolic constants and structures
              used with Windows functions.

Chapter 2  Display Drivers

The Microsoft Windows display driver manages all screen output for Windows
applications. A display driver provides a set of functions that Windows
uses to enable the display hardware, retrieve information about the
display, and draw text and graphics.


2.1 About the Display Driver

The display driver is a dynamic-link library that consist of a set of
graphics functions for a particular display device. These functions
translate device-independent graphics commands from the graphic-device
interface (GDI) into the commands and actions the display device needs to
draw graphics on the screen. The functions also give information to Windows
and Windows applications about color resolution, screen size and
resolution, graphics capabilities, and other advanced features that may be
available on the hardware. Applications use this information to create the
desired screen output.

Although Windows requires only a few functions to start, each Windows
application the user starts can potentially use any GDI functions. This
means a display driver should provide as complete support for GDI as
possible.


2.1.1 Display-Driver Initialization

Display-driver initialization occurs when Windows creates the
original-device context for the Windows desktop. To create the device
context, Windows loads the display driver and calls the driver's
initialization routine.

Although the initialization routine can carry out any task, many drivers do
the following:

o   Determine whether 386 enhanced-mode Windows screen switching is required

o   Initialize display hardware

o   Determine whether mouse trails support is required

o   Install any modal functions

Modal functions have implementations based on CPU type, hardware
configuration, or Windows mode of operation. For example, the ExtTextOut
function for a 80386 CPU may use 32-bit registers but the same function for
a 80826 uses 16-bit registers. In another example, a driver may install
cursor functions for a hardware cursor in one hardware configuration and
install functions for a software cursor in another.

Although a display driver may carry out some hardware initialization in its
initialization routine, it should wait until GDI calls the driver's Enable
function for a second time before fully initializing the video hardware.

The initialization routine returns to Windows if the initialization was
successful. Otherwise, it returns zero and Windows immediately terminates.


2.1.2 GDI Information Structure

Every display driver has a GDIINFO structure that specifies the display's
capabilities and characteristics. GDI uses this information to determine
what the display driver can do and what GDI must simulate. The GDI
information can be classified as follows:

o   Driver management

o   Driver capabilities

o   Device dimensions

The driver-management information specifies the version of Windows for
which the driver was written, and the type of technology the display uses
to generate output. Additionally, the driver-management information also
specifies the size in bytes of the PDEVICE structure, and number of device
contexts the driver can manage at the same time. The version number
specifies a Windows version (not the display driver version). For example,
a display driver written for Windows 3.1 should set the dpVersion member to
0x30A.

The driver-capabilities information specifies the capabilities of the
display device, such as whether the display hardware can draw polygons and
ellipses, scale text, or clip output. Driver capabilities also specify the
number of brushes, pens, fonts, and colors available on the display and
whether the display can handle bitmaps and color palettes.

The device-dimension information specifies the maximum width and height of
the screen in both millimeters and device units, the number of color bits
or planes, the aspect ratio, the minimum length of a dot in a styled line,
and the number of device units (or pixels per inch).

The subsequent sections of this chapter describe the GDIINFO structure more
fully. Each section describes the capabilities associated with given
members and explains how to determine what capabilities a display driver
can support.


2.1.3 Enabling and Disabling the Physical Device

GDI enables the display driver by calling the Enable function and directing
the driver to initialize a physical device for subsequent graphics output.
A physical device is a PDEVICE structure that represents the display and
its current operating state. A display driver uses the physical device
information to determine how to carry out specific tasks, such as which
display mode to use. The display driver initializes the physical device by
copying information to the PDEVICE structure.

In 386 enhanced-mode Windows, GDI calls the Enable function only when the
display driver is first loaded. In standard-mode Windows, GDI calls the
Enable function when first loaded and whenever the user switches back to
Windows from a non-Windows application.

GDI calls Enable twice: Once to retrieve a copy of the driver's GDIINFO
structure, and a second time to initialize the PDEVICE structure. After the
first call, GDI uses the dpDEVICEsize member in the GDIINFO structure to
determine the size of the driver's PDEVICE structure. GDI then allocates
memory for the structure and calls Enable for the second time, passing a
pointer to structure. At this point, the driver initializes the display
hardware and the structure.

When Windows switches back from a non-Windows application, GDI calls Enable
once. The driver reinitializes the display hardware and the PDEVICE
structure, reinitializing any screen data that may have been discarded when
Windows switched to the non-Windows application.

Although only the display driver initializes and uses the PDEVICE
structure, it is GDI that allocates memory for the structure, determines
when to pass it to the driver's output functions, and deletes the structure
when it is no longer needed. Except for the first two bytes (16 bits) of
the PDEVICE structure, the content and format of the structure depends
entirely on the display driver. Typically, the driver includes all the
information that the output functions need to generate appropriate graphics
commands. The first two bytes, on the other hand, must be set to a nonzero
value. GDI reserves zero to indicate a PBITMAP structure. GDI creates and
uses PBITMAP structures in place of PDEVICE structures when an application
creates a memory-device context.

GDI disables the display driver by calling the Disable function when
Windows quits. GDI expects the driver to free any resources associated with
the physical device and to restore the display hardware to the state before
Windows started. After the driver returns from the Disable function, GDI
frees the memory it allocated for the PDEVICE structure and frees the
driver, removing any driver code and data from memory.

In standard-mode Windows, GDI also calls Disable when the user switches to
a non-Windows application. In this case, GDI temporarily disables the
physical device, expecting the driver to select a text mode for the display
hardware so that the non-Windows application has a nongraphics mode in
which to start. Although Windows saves the display driver's data segment
when it switches, it discards all other segments. Therefore, the display
driver should save any data that may be discarded so that the data can be
restored when Windows switches back from the non-Windows application.


2.1.4 Hardware Initialization

A display driver sets the display mode and registers for the display
hardware whenever GDI calls the Enable and Disable functions. When running
under 386 enhanced-mode Windows (or other operating systems featuring
pre-emptive multitasking), the driver is also responsible for saving and
restoring the display mode and registers whenever Windows is switching
between Windows applications and non-Windows applications.


2.1.4.1 Enabling and Disabling the Display Hardware

A display driver prepares the display hardware for Windows whenever GDI
calls the Enable function. To prepare the hardware, the display driver
saves the current display mode, then sets the display hardware to graphics
mode, initializing hardware registers as needed. Although GDI calls the
BitBlt function to clear the screen as Windows starts, many display drivers
eliminate the possibility of the user seeing any random data by also
clearing the screen as they initialize the display hardware.

A display driver restores the display hardware to its original state
whenever GDI calls the Disable function. To restore the display hardware,
the driver sets the display hardware to a text mode, and restores the
original number of lines. If possible, the driver should use the same text
mode as before Windows started.


2.1.4.2 Screen Switching

In a pre-emptive multitasking environment, such as 386 enhanced-mode
Windows, the display driver should save and restore the display hardware
whenever the environment switches Windows to or from the foreground. 386
enhanced-mode Windows switches Windows to and from the foreground whenever
the user switches to or from non-Windows applications. Saving and restoring
the display hardware ensures that the display driver is not affected by
changes non-Windows applications make to the display hardware.

To detect screen switches, the display driver hooks Interrupt 2Fh and
checks for the Notify Background Switch and Notify Foreground Switch
functions (Interrupt 2Fh Functions 4001h and 4002h). When the driver
detects one of these functions, it either saves or restores the display
mode and registers accordingly. When the driver detects a switch to the
foreground, the driver also calls the RepaintScreen function (USER.275) to
direct Windows to restore the entire contents of the screen by repainting
it.

The display driver should hook Interrupt 2Fh whenever GDI calls the Enable
function. The driver hooks the interrupt by using the MS-DOS functions Get
Interrupt Vector (Interrupt 21h Function 35h) and Set Interrupt Vector
(Interrupt 21h Function 25h).

A display driver can temporarily disable screen switching by calling the
Enter Critical Section function (Interrupt 2Fh Function 4003h). This
function prevents 386 enhanced-mode Windows from proceeding with a switch
until the display driver calls Exit Critical Section (Interrupt 2Fh
Function 4004h).

If a display driver uses portions of video memory that are not used by the
current display mode (for example, the driver uses extra video RAM for
saving screen bitmaps), the driver should call the Enable VM-Assisted
Save/Restore function (Interrupt 2Fh Function 4000h) to pass 386
enhanced-mode Windows the address of save and restore flags. Windows sets
or clears these flags depending on whether it used the extra video memory
while a non-Windows application was in the foreground. In such cases, the
driver must call the Disable VM-Assisted Save/Restore function (Interrupt
2Fh Function 4007h) to disable this feature whenever GDI calls the Disable
function.

Although the display driver is responsible for repainting the screen when
Windows is switched to the foreground, occasionally the driver must
postpone repainting because Windows is in a critical section and is not
ready to process the repainting. In such cases, Windows calls the
UserRepaintDisable function in the display driver directing the driver to
postpone repainting. Windows will call UserRepaintDisable a second time
when it completes the critical section.


2.1.5 Physical Objects

Physical objects define the attributes (such as color, width, and style) of
lines, patterns, and characters drawn by a display driver. Physical objects
correspond to the logical pens, brushes, and fonts that Windows
applications create but contain device-dependent information that the
display driver needs to generate output. A display driver creates physical
objects when GDI calls the RealizeObject function. The driver uses physical
objects when GDI calls output functions such as Output, BitBlt, and
ExtTextOut.

The dpNumPens, dpNumBrushes, and dpNumFonts members in the GDIINFO
structure specify the number of pens, brushes, and fonts a display driver
supports. A display driver must supply information about these objects
whenever GDI requests it. GDI calls the EnumObj function to request
information about pens and brushes; it calls the EnumDFonts function to
request information about device fonts. For each pen, brush, or font, the
display driver calls the callback function. GDI pass a LPEN, LBRUSH, or
LFONT structure to the callback function. These structures specify the
attributes of the object.

Although a display driver can use display hardware to support objects, the
driver must be able to generate the same output both on the screen and in
memory bitmaps.


2.1.5.1 Physical Pens

A physical pen specifies the color, style, and width of polylines and
borders drawn by a display driver. A display driver realizes a physical pen
by filling a PPEN structure with information about the pen. The content and
format of the PPEN structure depends entirely on the display driver. In
general, the driver copies all the information the Output function need to
draw lines.

A display driver should support the standard GDI pen styles: Solid, dashed,
dotted, dot-dashed, dash-dot-dotted, and empty. A display driver must
support the empty style although it is not required to supply information
about it when GDI calls EnumObj. When drawing with a empty pen, the pen
itself does not contribute to the output, but the driver may still draw a
line if, for example, the raster operation combines the destination with
itself using the XOR operator (DDx) or inverts the destination (Dn).

A display driver that supports wide and styled lines must use the same
drawing algorithms for lines drawn on the screen and in memory bitmaps.
Because GDI efficiently synthesizes both wide and styled lines, some
display drivers do not support them.

Under certain conditions, GDI may pass the display driver a request to
realize a wide or styled line even though the display driver has specified
that it does not support them. In such cases, the driver should realize a
solid, one-pixel wide (or nominal) pen. GDI will use this pen to simulate
styled and wide lines.


2.1.5.2 Physical Brushes

A physical brush specifies the color and style of patterns used to fill
figures drawn by the Output function and to combine with bitmaps drawn by
the BitBlt function. A display driver realizes a physical brush by filling
a PBRUSH structure with information about the brush. The content and format
of the PBRUSH structure depends entirely on the display driver.

A display driver should support the standard GDI brush styles: solid,
hatched, patterned, and hollow. A display driver must support hollow
brushes although it is not required to provide information about it when
GDI calls the EnumObj function. When drawing with a hollow brush, the brush
itself does not contribute to the output, but other factors, such as a
raster operation that combines the destination with itself or inverts the
destination, can cause the driver to generate output.

The display driver can dither solid brushes if the specified color does not
exactly match a physical color. Otherwise, it should choose the closest
available color for the brush.

The display driver should support the standard hatched brush styles:
horizontal, vertical, forward diagonal, backward diagonal, cross, and
diagonal crosshatch. On raster displays, a driver typically implements
these styles as predefined, 8-by-8 bit patterns.

On color displays, the display driver should support both monochrome and
color bitmaps for patterned brushes. When drawing monochrome bitmaps, the
driver sets 1 bit to the current text color and 0 bits to the current
background color. The text and background colors are specified in the
DRAWMODE structure passed to these functions. A display driver is not
required to provide information about patterned brushes when GDI calls the
EnumObj function.


2.1.6 Physical Colors

A display driver is responsible for translating logical colors (RGB values)
into physical colors that are appropriate to the display hardware.
Similarly, it must translate physical colors to logical colors. GDI calls
the ColorInfo function whenever it needs a translated color.

If the display device provides a color palette, the driver converts colors
to palette indexes. To indicate a palette index, the driver always sets the
high byte of the index to 0xFF.

To indicate an RGB color value, the display driver sets the high byte to
zero.


2.1.7 Screen Metrics

The screen metrics, specified by the GDIINFO structure, define such items
as width and height in millimeters, screen resolution, aspect ratio, and
mapping modes. GDI uses screen metrics to generate coordinate data that is
appropriate for the display hardware.


2.1.7.1 Logical Pixels Per Inch

A display driver sets the dpLogPixelsX and dpLogPixelsY members to specify
the number of pixels per logical inch along horizontal and vertical lines
on the screen. A display driver uses logical inches (about 40 percent
larger than physical inches) for readability reasons.

The GDI font mapper uses these values to determine which screen fonts to
use with the display. The display driver should make sure the dpLogPixelsX
and dpLogPixelsY members match an existing font. If these members do not
match one of the default screen fonts, an appropriate font must be provided
with the display driver.


2.1.7.2 Screen Resolution and Size

A display driver sets the dpHorzRes and dpVertRes members to specify the
width and height of the screen in pixels, and sets the dpHorzSize and
dpVertSize members to specify the width and height of the screen in
millimeters. These values must have the following relationships:

    dpHorzSize = (dpHorzRes/dpLogPixelsX) * 25.4

    dpVertSize = (dpVertRes/dpLogPixelsY) * 25.4
In these equations, 25.4 represents the number of millimeters per inch.


2.1.7.3 Aspect Ratios

The aspect ratio defines the relative dimensions of the display's pixels.
The ratio consists of three values: an x-, y-, and an xy-aspect. These
represent the relative width, height, and diagonal length (or hypotenuse)
of a pixel. GDI uses the aspect ratio to determine how to draw squares and
circles as well as drawing lines at an angle.

The aspect values have the following relationship:

    dpAspectXY ** 2 == (dpAspectX ** 2) + (dpAspectY ** 2)
Since the dimensions are given as relative values, they may be scaled as
needed to get accurate integer values. They should be kept under 1000 for
numerical stability in GDI calculations. For example, a device with a 1:1
aspect ratio (such as a VGA) can use 100 for dpAspectX and dpAspectY and
141 (100 * 1.41421...) for dpAspectXY.


2.1.7.4 Styled-Line Length

The styled-line length (dpStyleLen) specifies the length of the smallest
line segment the display driver uses to build the dots and dashes of a
styled line. GDI uses this number when it draws into bitmaps and on
displays. To ensure consistency between displays and printers, the styled
line segment length is always two times the value of the dpAspectXY member.


2.1.7.5 Standard Mapping Modes

Some Windows application programs rely on standard mapping modes to produce
printer output with spacing that is proportional to the screen. By using
the standard mapping modes, an application can show a border or graphic
picture that is proportionately the same size on the printer as it is on
the screen.

All standard mapping-mode ratios must be the same because it might be
preferable for an application to use the metric system rather than the
inches/feet (English) system for its calculations. For example, Windows
Write allows the user to choose whether to express the border widths in
millimeters or inches. Therefore, it is up to the display driver to provide
the correct numbers.

Standard mapping modes are expressed as two coordinate pairs: the width and
height (in logical units) of a window and the width and height (in physical
units, that is, pixels) of a viewport that maps onto that window. The
driver for a VGA adapter, for example, might set the coordinates pairs for
the low-resolution metric mapping mode (tenths-of-millimeters) to (254,254)
and (96,96). These coordinates map an 1-inch by 1-inch window (25.4
millimeters equals 1 inch) to a 96-pixel by 96-pixel viewport. These
coordinate pairs define a set of equations that specify how coordinates in
logical space are transformed to coordinates in device space.

The standard mapping-mode members in the GDIINFO structure can be set as
follows:

    dpMLoWin.x = dpHorzSize*10;    dpMLoWin.y = dpVertSize *10;
    dpMLoVpt.x = dpHorzRes;        dpMLoVpt.y = -dpVertRes;

    dpMHiWin.x = dpHorzSize*100;   dpMHiWin.y = dpVertSize *100;
    dpMHiVpt.x = dpHorzRes;        dpMHiVpt.y = -dpVertRes;

    dpELoWin.x = dpHorzSize*1000;  dpELoWin.y = dpVertSize *1000;
    dpELoVpt.x = dpHorzRes * 254;  dpELoVpt.y = -dpVertRes * 254;

    dpEHiWin.x = dpHorzSize*10000; dpEHiWin.y = dpVertSize *10000;
    dpEHiVpt.x = dpHorzRes * 254;  dpEHiVpt.y = -dpVertRes * 254;

    dpTwpWin.x = dpHorzSize*14400; dpTwpWin.y = dpVertSize *14400;
    dpTwpVpt.x = dpHorzRes * 254;  dpTwpVpt.y = -dpVertRes * 254;

A twip is 1/20th of a printer's point (1/72 of an inch).

Windows performs 16-bit, signed calculations on these values, so the
numbers must not be greater than 32,768. However, if the screen is larger
than just a few inches wide, the values will exceed this limit when
calculating the English mapping modes and may even exceed it on the metric
mapping modes. Fortunately, the values can be scaled down by dividing by
some fixed amount.


2.1.8 Lines, Curves, and Polygons

GDI requires all display drivers to provide an Output function that
supports a minimum set of line, curve, and polygon drawing capabilities. In
particular, a display driver must be able to draw scan lines and polylines.
A scan line is a solid or styled, horizontal line that is exactly one pixel
wide. A polyline is a sequence of solid lines, each one pixel wide and each
connected at an endpoint to the next line in the sequence.

GDI may call the Output function whenever an application calls a function
that draws lines, curves, or polygons. If the display driver supports all
capabilities, GDI calls the Output function for each request. Otherwise,
GDI simulates output that the driver does not support by combining scan
lines and polylines.

Since GDI can use scan lines and polylines to simulate all other line,
curve, and polygon output, many display drivers do not support additional
capabilities unless the display hardware can produce faster and
higher-quality results than GDI. The only drawback to using display
hardware is that the display driver must be able to produce the same
results in memory bitmaps as on the screen.

GDI checks the dpCurve, dpLines, and dpPolygonals members of the GDIINFO
structure to determine what line, curve, and polygon capability the display
driver has.


2.1.8.1 Curves

GDI checks the dpCurve member to determine whether the display driver
supports circles, ellipses, pie wedges, and chord arcs. This member also
specifies whether the display driver can draw wide or styled borders for
curves and fill the interiors of curves.

If a display driver does not support circles, GDI can use an ellipse to
draw a circle. If the display hardware can fill ellipses, the display
driver should set the interiors bit. GDI can use an alternate-fill polygon
to draw wide borders (both solid and styled) just as efficiently as if the
driver supported them correctly.


2.1.8.2 Polylines

GDI checks the dpLines member to determine whether the display driver
support polylines. This member also specifies whether the display driver
can draw wide or styled lines and fill the interiors of wide lines. A
display driver must support polylines.

If a display driver supports styled lines, the line segments drawn by the
display hardware must be as specified by the dpStyleLen member. Although
wide, styled lines are used infrequently, the display driver should support
them if the display hardware can draw them and the effort to support memory
bitmaps is not too great. If necessary, GDI can simulate wide, styled
lines.


2.1.8.3 Polygons

GDI checks the dpPolygonals member to determine whether the display driver
supports rectangles, scan lines, alternate-fill polygons, and
winding-number-fill polygons. This member also specifies whether the
display driver can draw wide or style borders for polygons, and fill the
interiors of polygons. The display driver must support scan lines.

If the display driver does not draw its own wide borders, GDI simulates
wide borders using alternate-fill polygons. Some display drivers
intentionally take advantage of this by supporting alternate-fill polygons,
but not wide borders.

If the display hardware provides support for styled borders, the driver
should use the hardware to draw the borders. Although GDI can simulate
styled borders, such simulations are always slower than using hardware.


2.1.8.4 Hardware Capabilities

The hardware for some displays supports many of the line, curve, and
polygon capabilities that Windows itself supports or expects the display
driver to support. A display driver should take advantage of display
hardware whenever possible because it often dramatically improves
performance.

The only disadvantage to using display hardware is if the hardware cannot
produce its output both on the screen and in memory bitmaps. Windows
requires that for any figure drawn on the screen, the display driver must
also be able to draw it in a memory bitmap. If the hardware cannot access
memory bitmaps, the display driver must include code that emulates the
algorithms used by the display hardware. Depending on the complexity of the
hardware code, this may be a difficult and costly task.

One alternative to emulating the display hardware is to use video memory as
a temporary bitmap. The driver copies the memory bitmap from system memory
to unused video memory, uses the display hardware to carry out the
requested graphic operations, and then copies the results back to system
memory. The efficiency of this method depends on the relative speed of the
graphics hardware, and the size of the bitmap. This method is not
appropriate under 386 enhanced-mode Windows if the display driver does not
have full access to the hardware capabilities or to offscreen video memory
while running in the background, that is, while the user is running a
non-Windows application in text mode. This method is not appropriate if the
display driver cannot support monochrome bitmaps. (All display drivers must
support output to monochrome bitmaps regardless of whether the display
adapter is color or monochrome.) Finally, this method is not appropriate
for device-independent bitmaps (DIBs).


2.1.8.5 Partial Support for Capabilities

A display driver does not have to provide complete support for a given
capability. Instead, a driver's Ouput function can provide support for a
few specific cases and return all others to GDI for simulation. In such
cases, the display driver sets bits in the GDIINFO structure as if it
provided complete support, but the driver's Output function returns -1 to
GDI for all cases that need simulation.

For example, if display hardware can draw polygons with 256 vertices but
not with 257, the Output function can use the display hardware to draw the
smaller polygons and return -1 to let GDI simulate the rest.

GDI does not simulate styled lines. If the display driver specifies support
for styled lines, it must provide complete support.


2.1.9 Text

GDI requires all display drivers to provide an ExtTextOut function that
provides a minimum set of text-drawing capabilities. At the very least, a
driver must be able to draw a string of characters at a specified location
on the screen and clip any portion of a character that extends beyond the
bounding box for the string.

GDI calls the ExtTextOut function whenever an application calls a function
that draws text or computes text widths. The ExtTextOut function receives a
string of character values, a count of characters in the string, a starting
position, a physical font, and a DRAWMODE structure. The function uses
these values to create the individual glyph images on the screen.

GDI checks the RC_GDI20_OUTPUT value in the dpRaster member of the GDIINFO
structure to determine whether the driver supports this function. In
earlier versions of Windows, the StrBlt function supported text drawing,
but StrBlt is now obsolete. For compatibility with early versions of
Windows applications, however, the display driver must provide the StrBlt
function. In most drivers, StrBlt does nothing more than call or fall
through to ExtTextOut.

GDI checks the dpText member of the GDIINFO structure to determine which
text capabilities the display driver supports. Although Windows requires
few text capabilities for a display driver, all display drivers should
support as many capabilities as possible so that Windows applications have
the greatest flexibility when drawing text. The following are the text
capabilities.

Capability         Description
---------------------------------------------------------------------------

Clipping           Specifies whether the display driver can clip whole or
                   partial characters.

Cosmetics          Specifies whether the display driver can generate bold,
                   italic, underlined, or strikethrough characters from
                   existing characters.

Fonts              Specifies whether the display driver supports raster and
                   vector fonts.

Output precision   Specifies which font attributes the display driver uses
                   when drawing text.

Rotation           Specifies whether the display driver can rotate
                   characters.

Scaling            Specifies whether the display driver can generate new
                   sizes by scaling an existing size.

Scaling freedom    Specifies whether the display driver can scale
                   independently along the x- and y-axes.


2.1.9.1 Output Precision

GDI checks the TC_OP_CHARACTER and TC_OP_STROKE values in the dpText member
to determine the output precision of the driver. Output precision specifies
which font attributes the ExtTextOut function must use when it draws text.
Font attributes include width, height, intercharacter spacing, interword
spacing, escapement, orientation, and other attributes specified in the
TEXTXFORM and DRAWMODE structures. These structures are passed to the
ExtTextOut function.

A display driver sets the TC_OP_STROKE value if it can draw characters as a
set of line segments. When drawing with stroke precision, the driver must
adhere to all font attributes, and use the current transformations to
compute the starting point of the string.

A display driver sets the TC_OP_CHARACTER value if it can draw characters
at any given escapement. Character precision ensures the placement of
individual characters without guaranteeing the exact size requested. With
character precision, the driver must:

o   Use the width and height to determine a best-fit character size. If no
    font matches exactly, the driver should use either the largest font
    that does not exceed the requested size or the smallest available font.

o   Use the current transformations to compute the starting point of the
    string.

o   Use the current intercharacter and interword spacing to position the
    individual characters in the string.

o   Use the current escapement.

The driver can ignore all other attributes. If possible, the display driver
should use the display's character generation hardware to draw individual
characters.

If a display driver does not set the TC_OP_STROKE and TC_OP_CHARACTER
values, GDI requires the driver to support string precision. String
precision is identical to character precision except that the current
escapement can be ignored.

Output precision does not affect the bold, italic, underline, or
strikethrough capabilities. If a driver registers these abilities, it must
perform them when requested.


2.1.9.2 Clipping

GDI checks the TC_CP_STROKE value in the dpText member to determine the
clip precision of the driver. A display driver sets the TC_CP_STROKE value
if it can clip any portion of a character that is outside the clip region
and draw the rest of the character. If the driver does not set this value,
GDI requires that the driver clips the entire character if any portion of
the character is outside the clip region.

A display driver must support stroke clip precision.


2.1.9.3 Rotation

GDI checks the TC_CR_90 and TC_CR_ANY values in the dpText member to
determine whether the display driver can rotate characters. A display
driver sets the TC_CR_ANY value if it can rotate characters to any angle.
The driver sets the TC_CR_90 value it can rotate characters at 90 degree
increments only. If a display driver does not set either bit, GDI assumes
that the driver cannot rotate characters.


2.1.9.4 Scaling and Scaling Freedom

GDI checks the TC_SA_DOUBLE, TC_SA_INTEGER, and TC_SA_CONTIN values to
determine whether the display driver can scale characters. GDI also checks
the TC_SF_X_YINDEP value to determine whether the driver can scale
characters independently on the x- and y-axes.

A display driver sets the TC_SA_CONTIN value if it can scale existing
characters to any size, sets the TC_SA_INTEGER value if it can scale
characters by any integer multiple, or sets the TC_SA_DOUBLE value if it
can double the size of existing characters. If a display driver sets none
of these values, GDI assumes that the driver can not scale characters.

A display driver sets the TC_SF_X_YINDEP value if the driver can scale
characters independently in each direction. If this bit is not set but the
driver specifies that it can scale characters, GDI assumes that the driver
always scales characters the same amount in the each direction.

Whenever a display driver cannot match a requested size exactly, GDI
requires the driver to use the largest size available that will not exceed
the requested size in either direction.


2.1.9.5 Cosmetics

GDI checks the TC_EA_DOUBLE, TC_IA_ABLE, TC_UA_ABLE, and TC_SO_ABLE values
to determine whether the display driver can generate bold, italic,
underlined, or strikethrough characters from existing characters.

A display driver sets TC_EA_DOUBLE if it can generate a bold character by
doubling the existing character's weight. A typical method is to overstrike
the existing character after moving one device unit to the right.

A display driver sets the TC_IA_ABLE value if it can generate italic
characters. A typical method is to skew the gylph information, drawing the
the character as if it were contained by a parallelogram rather than a
rectangle.

A display driver sets the TC_UA_ABLE value if it can generate underlined
characters, and sets the TC_SO_ABLE value if it can generate strikethrough
characters.


2.1.9.6 Raster and Vector Fonts

GDI checks the TC_RA_ABLE and TC_VA_ABLE values in the dpText member to
determine whether the display driver supports raster and vector fonts,
respectively. A display driver must set at least one of these bits.


2.1.9.7 Orientation and Escapement

Whenever either the character orientation or the difference between the
character orientation and the escapement angle is a multiple of 90 degrees,
the intercharacter and interword spacing will be the standard
intercharacter spacing used for bounding boxes plus the spacing specified
by the CharacterExtra and BreakExtra members in the DRAWMODE structure.

The standard intercharacter spacing at a given escapement angle and
character orientation is defined as the minimum spacing along the
escapement vector, such that the character origins are on the escapement
vector, and the character bounding boxes touch. Variable pitch fonts are
achieved by using variable width bounding boxes. This model applies to all
attribute values. When the sides of the bounding boxes touch, extra space
is added in x and, when the tops touch, it is added in y.

In all other escapement and orientation cases, the standard intercharacter
spacing is device dependent. The preferred implementation is for the
90-degree cases. In all cases, it is required that all character origins
lie on the escapement vector.

It is assumed that arbitrary escapement angles can be achieved, if by no
other means than, by placing each character as a separate entity. Many
devices are able to do arbitrary character rotation only if the character
orientation matches the escapement angle. For such devices, it is assumed
that the driver will place each character individually at the proper
orientation and escapement, when escapement and character orientation do
not match.


2.1.10 Fonts

A font is a collection of glyphs that define the size and appearance of
individual characters in a character set. A display driver uses physical
fonts when it draws text. A physical font is a structure that contains all
the information the driver needs to draw the glyphs on the screen. GDI
supplies these physical fonts whenever it calls the ExtTextOut function.

GDI supports a variety of font types but lets each display driver determine
which fonts it supports. A display driver can choose to support any
combination of the fonts.

Type       Description
---------------------------------------------------------------------------

Device     A font supplied by the display device. The display driver must
           provide complete support for device fonts, including realizing
           the fonts and using display hardware to draw the fonts.

Raster     A font containing glyph bitmaps that is intended to be used by
           raster device. GDI supplies a variety of raster fonts, but
           Windows applications and even display drivers can supply
           additional fonts. GDI realizes raster fonts as needed, but
           display drivers that support the fonts must be able to draw the
           fonts using the data in the physical font format.

TrueType   A font containing sophisticated glyph definitions that is
           intended to be used in conjunction with a rasterizer to produce
           a corresponding raster font. GDI supplies a variety of TrueType
           fonts as well as the TrueType rasterizer.

Vector     A font containing glyph definitions that is intended to be used
           by a vector device. GDI supplies a variety of vector fonts, but
           Windows applications and even display drivers can supply
           additional fonts. GDI realizes vector fonts as needed, but
           display drivers that support the fonts must be able to draw the
           fonts using the data in the physical font.

NOTE  Display drivers that support raster fonts can also use TrueType
fonts.

Although display drivers generally do not use device fonts, a display
driver can realize device fonts if the display hardware support them. Most
display drivers return zero when GDI calls the RealizeObject function
requesting a realized font. Returning zero directs GDI to realize the font
using existing raster or vector fonts.

Fonts, like other graphics objects, must be realized before the display
driver can use them. The format of the realized font depends on the font
type. For more information about raster- and vector-font format, see
Chapter 13, Font Files.

For more information about characters within a specific character set, see
Appendix B, Character Tables.


2.1.10.1 Raster Fonts

GDI checks the TC_RA_ABLE value in the dpText member to determine whether a
display driver supports raster fonts. A raster font is a set of glyph
bitmaps, each defining the size and appearance of a character in the font.
A display driver that supports raster fonts uses the glyph bitmap to
generate the character image on the screen.

Windows provides the following raster fonts.

Font            Description
---------------------------------------------------------------------------

Courier(R)      A fixed-width font with serifs in the ANSI character set.

Fixedsys        The Windows 2.x fixed-width system font in the ANSI
                character set.

MS Sans Serif   A proportional-width font without (sans) serifs in the ANSI
                character set.

MS Serif        A proportional-width font with serifs in the ANSI character
                set.

Symbol          A representation of math symbols in the Symbol character
                set.

System          A proportional-width font without serifs in the ANSI
                character set.

Small           A set of raster fonts used for displaying characters of 8
                points or below with greater readability.

Terminal        A fixed-width font with serifs in the OEM character set.


2.1.10.2 Vector Fonts

GDI checks the TC_VA_ABLE value in the dpText member to determine whether a
display driver supports vector fonts. A vector font is a set of glyph
definitions, each containing a sequence of points respresenting the start
and endpoints of the line segments that define the appearance of a
character in the font. A display driver that supports vector fonts uses the
glyph definitions to generate the character image on the screen.


2.1.10.3 Big Fonts

GDI checks the RC_BIGFONT value in the dpRaster member to determine whether
the display driver supports big fonts (also called Windows 3.x fonts). A
big font is any font in which the font and glyph information can exceed 64K
bytes. Big fonts are primarily designed for use on systems with more than
average memory and a microprocessor (such as an 80386) that has
instructions that use 32-bit address offsets.

When GDI realizes a font for a driver supporting big fonts, GDI includes
additional members (dfFlags through dfReserved1) in the the physical font's
FONTINFO structure. Furthermore, since font and glyph information may
exceed 64K, the display driver must use 32-bit offsets to access this
information. This means the driver should make use of the extended
registers of the 80386, such as ESI and EDI.

All display drivers must support standard fonts whether or not they support
big fonts.

For big fonts, GDI sets the dfVersion member in the font structure to
0x0300. Standard fonts are set to 0x0200. Also, GDI never mixes fonts for a
device. If the display driver registers RC_BIGFONT capability, GDI will
always give the driver big fonts--not a mixture of standard and big fonts.


2.1.10.4 TrueType Fonts

Display drivers that handle raster fonts can also handle TrueType fonts
without modification. GDI supports TrueType in display drivers by building
FONTINFO structures that contain rasterized glyph bitmaps. GDI passes a
pointer to this structure to the driver's ExtTextOut or StrBlt function
along with the string to be displayed.

An important difference between TrueType and standard fonts is that
TrueType fonts are sparse in their glyph definitions, that is, the FONTINFO
structure may only contain those characters in the string to be displayed.
For this reason, display drivers cannot cache the font in private memory
and later reference glyphs not previously displayed. The display driver,
however, can build up a cache of glyphs as they are displayed. Such a glyph
cache can boost performance on some display adapters that have hardware
text and blit support.


2.1.10.4.1 Overlapping Glyphs

Display drivers can handle text in TrueType fonts almost identically to
text in regular raster fonts. One important difference, however, is that
TrueType glyphs are designed to be more readable by minimizing the gaps
between glyphs--in fact, some glyphs overlap. To take full advantage of the
design and maintain performance, display drivers may need some modification
to allow for overlapping glyphs.

TrueType fonts may affect the performance of display drivers since many
TrueType glyphs are designed to overlap neighboring glyphs. Overlapping
makes text more readable, but complicates the process used by a display
driver to draw the text. A display driver can improve its performance by
handling overlapping glyphs using the technique described in this section.

The most important performance improvement is to revise a driver's code to
handle background opaquing (in the case of opaque text) and overlapping
glyphs in a single pass. If a display driver sets the RC_OP_DX_OUTPUT value
in the dpRaster member of the GDIINFO structure, GDI assumes that the
ExtTextOut function can do background opaquing at the same time the glyphs
are drawn. If this value is not set, GDI will split the text output
operation into two steps, with the first step being an opaque rectangle
that fills the text bounding box. The second operation will then draw the
text transparently on top of the previously filled rectangle.

GDI passes the text string and a width array to either the ExtTextOut or
StrBlt function in the driver. The width array contains n-1 entries for a
string of n characters. Each entry contains a pixel offset from the origin
of one character to the origin of the next character. For example, if the
third width element is 20, the fourth character should be drawn 20 pixels
to the right of the third character.

Handling kerning (glyph overlap) efficiently can be a problem on display
adapters with relatively slow video memory access times (such as the EGA
and VGA). The algorithm described below is appropriate for such displays. A
different approach may be necessary for other display architectures.

The idea behind this algorithm is to never access a video memory location
more than once, and, where possible, do word-aligned, 16-bit memory
accesses. Ideally, this algorithm should be small, simple, and efficient
for text strings with or without kerning.

NOTE The following discussion assumes some familiarity with the
implementation of the ExtTextOut function in the sample EGA/VGA driver
provided with the DDK. For complete details, please see the EGA/VGA source
code.

For each character that is partially or completely within the string's
clipping rectangle, the stack builder pushes a phase, width, and glyph
pointer onto the stack. If kerning occurs in the text string, the stack
builder will recognize this and push a backup sentinel along with a word
that contains the number of pixels to backup before rendering subsequent
stack entries. When the entire string has been processed, the stack builder
pushes a sentinel word on the stack to mark the end of the entries.

The format of a stack entry is a word containing the phase of the bit
pattern (high byte) and the width of the bit pattern (low byte). Following
this word, a pointer to a glyph pattern is stored on the stack. For fonts
that are less than 64K bytes in size, this is a word value representing an
offset from the base of the font segment to the bit patterns for a given
glyph. For fonts greater than 64K bytes, this glyph pointer is 2 words
which forms a 32-bit offset from the current font segment base.

As an example:

    Stack Entries     Meaning
    --------------    ------
    0308, Glyph_ptr   8-bit wide column, starting 3 bits into a byte.
    0308, Glyph_ptr   Next column, 8 bits wide, phase is again 3.
    8000, FFFE        Backup by 2 pixels.
    0108, Glyph_ptr   Next column (overlaps previous column), phase is 1.
    FFFF              End of stack entries.
After the stack has been built, control is passed to a routine which
unstacks each entry and composes an image of the string into a memory
buffer. This string image is called a SuperGlyph because the format of the
memory buffer is identical to the glyph format in the raster font (that is,
column major ordering). Each stack entry is processed by fetching up to 4
bytes worth of glyph bit pattern from the font structure, phase aligning
with respect to the final destination, and ORing into the compose buffer.
This process continues until all stack entries have been processed.

Once complete, the SuperGlyph is then passed to a destination specific
output routine which copies the SuperGlyph to the final destination (either
video memory, a color bitmap or a monochrome bitmap). Each output routine
is optimized for word-aligned, 16-bit accesses to the final destination.

In some cases, the size of the compose buffer may not be big enough to hold
a complete image of the string. The VGA/EGA code handles this case with
restart logic that composes as much of the SuperGlyph as possible, and then
outputs it to the destination. The compose buffer is then cleared and the
process repeats until the entire string has been rendered.


2.1.10.4.2 Font Caching for TrueType Fonts

Display drivers that do their own font caching may encounter conflicts with
the new TrueType font technology provided with Windows 3.1. Display drivers
that use glyph caching rather than caching the entire character set should
work without problems.


2.1.11 Clipping

A display driver or display hardware can clip if it can discard output that
would be outside of a specified rectangle or region if drawn on the screen.
GDI checks the dpClip member in the GDIINFO structure to determine whether
the display driver can clip output generated by the Output function. If a
display driver can clip, it should set the bits in this member to specify
clipping for rectangles or regions. If the display driver does not support
clipping, GDI will simulate clipping.

Although dpClip only applies to output generated by the driver's Output
function, other members in the GDIINFO structure specify clipping for other
graphics output. For example, the dpText member specifies whether the
display driver clips text.


2.1.12 Bitmaps

GDI requires a display driver to support bit-block transfers by providing
the BitBlt and related bitmap functions. At the very least, a display
driver should provide a BitBlt function that can carry out bitmap
operations on the screen and in monochrome bitmaps. The brute functions
provided by GDI and used by many printer drivers require monochrome bitmap
support.

GDI checks the dpRaster member in the GDIINFO structure to determine
whether the display driver supports bitmaps. If the driver does, GDI checks
the dpBitsPixel and dpPlanes members to determine the format of the screen
bitmap.


2.1.12.1 Bitmap Format

Most display devices are either planar or packed-pixel devices. A planar
device stores screen bits in separate bitmap planes, each representing a
distinct color. A packed-pixel device stores screen bits in a single plane,
but each pixel on the screen has a set of two or more corresponding bits
that define the pixel color.

A display driver specifies the type of display device by setting the
dpBitsPixel and dpPlanes members to appropriate values. For a planar
device, dpBitsPixel is 1 and dpPlanes specifies the number of planes. For a
packed-pixel device, dpPlanes is 1 and dpBitsPixel specifies the number of
bits per pixel.

These values also help determine the number of nondithered colors available
for the screen. A device with 4 planes is capable of 16 colors. A device
with 8 bits per pixel is capable of 256 colors. However, the exact color
specified by a combination of bits depends on whether the device supports a
color palette.


2.1.12.2 Pixel Output

A display driver must support setting and getting individual pixels by
providing the Pixel function. GDI uses Pixel to support a variety of
simulations. It also calls the function whenever an application calls
SetPixel (GDI.31) and GetPixel (GDI.83).


2.1.12.3 Bit-Block Transfers

A display driver can support bit-block transfers by providing a BitBlt
function. GDI uses BitBlt to copy a rectangular block of bits from bitmap
to bitmap, possibly applying a raster operation to the source and
destination bits as it copies. GDI checks the RC_BITBLT value in the
dpRaster member to determine whether the display driver supports the
function. If it does, GDI calls BitBlt whenever an application calls GDI
functions such as BitBlt (GDI.34) and PatBlt (GDI.29).

A display driver can provide additional bit-block transfers by providing a
StretchBlt function. GDI uses StretchBlt to stretch or compress a block of
bits to fit a given rectangle in a bitmap. Stretching and compressing
requires either adding or removing bits as defined by a stretching mode.
GDI checks the RC_STRETCHBLT value in dpRaster to determine whether the
driver provides the StretchBlt function. GDI calls the function whenever an
application calls StretchBlt (GDI.35).

If a display driver can carry out bit-block transfers on bitmaps that are
larger than 64K, it should set the RC_BITMAP64 value in the dpRaster
member. GDI checks this bit to determine whether large bitmaps are
permitted.


2.1.12.4 Transparent-Block Transfers

In Windows 3.1, display drivers can indicate that they support
transparent-block transfers by setting the C1_TRANSPARENT value in the
dpCaps1 member of the GDIINFO structure. In a transparent-block transfer, a
driver excludes source and brush pixels from a BitBlt or StretchBlt
operation if those pixels have the same color as the current background
color for the destination device.

If a display driver supports transparent block transfers, the BitBlt
function must check the bkMode member of the DRAWMODE structure as well as
the Rop3 parameter of the BitBlt function to determine how to carry out the
transfer. If the bkMode member specifies the background mode TRANSPARENT1,
BitBlt must not transfer source and brush bits that have the same color as
the destination's background color (as specified by the bkColor member of
the DRAWMODE structure pointed to by the lpDrawMode parameter). In other
words, the corresponding destination bits must be left unchanged. Other
background modes do not affect the transfer.

Although a display driver may support transparent-block transfers, GDI does
not currently provide access to this support for Windows applications.


2.1.12.5 Fast Borders

A display driver can support fast-border drawing by providing a FastBorder
function. Windows uses the function to quickly draw borders for windows and
dialog boxes. GDI checks the RC_GDI20_OUTPUT value in the dpRaster member
to determine whether a display driver provides the FastBorder function. If
it does, GDI calls the function to draw the borders. Otherwise, it returns
an error value to direct Windows to use some other means to draw the
borders.

A display driver also uses the RC_GDI20_OUTPUT value to specify whether it
supports the ExtTextOut function. In some cases, a display driver may
support ExtTextOut but not FastBorder. To account for this, the display
driver must provide a FastBorder function, but the function can immediately
return an error value to direct Windows to use some other means to draw
borders.


2.1.12.6 Saved Bitmaps

A display driver can permit Windows to temporarily save bitmaps in
off-screen video memory by providing the SaveScreenBitmap function. This
function allows the driver to take advantage of unused video memory and to
speed up drawing operations that require restoring a portion of the screen
that was previously overwritten.

GDI checks the RC_SAVEBITMAP value in the dpRaster member to determine
whether the driver supports SaveScreenBitmap.


2.1.12.7 Flood Fill

A display driver can support flood-fill operations by providing a FloodFill
function. GDI uses the function to quickly fill a region on the screen or
in a bitmap with a specified color. GDI calls the function whenever an
application calls FloodFill (GDI.25).

GDI checks the RC_FLOODFILL value in dpRaster to determine whether the
driver provides the function.


2.1.13 Device-Independent Bitmaps

A device-independent bitmap (DIB) is a color bitmap in a format that
eliminates the problems that occur when transferring device-dependent
bitmaps to devices having difference bitmap formats. DIBs provide color and
bitmap information that any display or printer driver can translate into
the proper format for its corresponding device.

A display driver can support DIBs by providing the following
device-independent bitmap functions.

Function            Description
---------------------------------------------------------------------------

DeviceBitmapBits    Copies a DIB to a device-dependent bitmap or a
                    device-dependent bitmap to a DIB.

SetDIBitsToDevice   Copies any portion of a DIB to the screen. This
                    function copies the bits directly without applying a
                    raster operation.

StretchDIBits       Moves a source rectangle into a destination rectangle,
                    stretching or compressing the bitmap if necessary to
                    fit the dimensions of the destination rectangle.

These functions receive and operate on BITMAPINFO, BITMAPINFOHEADER, and
RGBQUAD structures.

A display driver that supports DIBs must provide the CreateDIBitmap
function as well. The function should do nothing more than return zero
indicating that the creation of a DIB is not supported at the driver level.

If a display driver supports DIBs, it must set one or more of the
RC_DI_BITMAP, RC_DIBTODEV, and RC_STRETCHDIB values in the dpRaster member
of the GDIINFO structure. If a driver does not set the RC_DI_BITMAP value,
GDI simulates DIB conversions using monochrome bitmaps.


2.1.13.1 Logical-Color Tables

A display driver creates a logical-color table when translating a
device-specific bitmap into a DIB. The table resides in the DIB header
block. The device driver, if it is not a palette device, can fill up the
table with whatever color it supports and then, use the corresponding
indexes in the bitmap. The driver must also set the number of colors it is
using in the biClrUsed member of the header block.

Consider an example in which the display device is a 4-plane EGA device,
and in which the DIB has 8 bits-per-pixel. The logical color table for the
DIB has provisions for 256 colors, but the 4-plane driver can deal with
only 16 colors. The driver would prepare a color table for the DIB that
looked like the following:

    RGBQUAD ColorTable[] = {
        {0,     0,   0, 0},
        {128,   0,   0, 0},
        {0,   128,   0, 0},
        {128, 128,   0, 0},
        {0,     0, 128, 0},
        {128,   0, 128, 0},
        {0,   128, 128, 0},
        {128, 128, 128, 0},
    #ifdef VGA
        {196, 196, 196, 0},
    #else /* EGA */
        {64,   64,  64, 0},
    #endif
        {255,   0,   0, 0},
        {0,   255,   0, 0},
        {255, 255,   0, 0},
        {0,     0, 255, 0},
        {255,   0, 255, 0},
        {0,   255, 255, 0},
        {255, 255, 255, 0}};
The device driver may fill in just 16 colors and set biClrUsed to 16, or it
may fill up entries 16 through 255 with zeros and set biClrUsed to 0.

The color-mapping tables for each of the DIB formats can be predefined for
a particular driver and should be copied into the DIB header during the
format-specific initialization.


2.1.13.2 DIB to Device

A display driver can copy a DIB directly to the screen using the
SetDIBitsToDevice function. This function saves the trouble of first
converting the DIB into the device-dependent format and then, transferring
it onto the screen. However, only a direct copy of the DIB is provided. For
other raster operations that BitBlt supports, the driver must first convert
the DIB into the internal format. Moreover, only one direction of copy (DIB
to screen) is provided.

The process of copying the bits is similar to the one adopted in the
SetDeviceBitmapBits function except that for some devices, such as the
EGA/VGA, the nature of the hardware might make it advantageous to copy one
pixel at a time. The concept of having a color-translation table and
format-specific initialization remains the same.


2.1.14 Device Bitmaps

A device bitmap is any bitmap whose bitmap bits are stored in device memory
(such as RAM on a display adapter) instead of main memory. Device bitmaps
can significantly increase the performance of a graphics driver as well as
free main memory for other uses. To realize these benefits, the
corresponding graphics device must have ample video memory in addition to
the video memory used to generate the current display. The device should
also have efficient routines for copying bits to video memory.

Graphics drivers that set the RC_DEVBITS value in the dpRaster member of
the GDIINFO structure support device bitmaps. GDI checks this bit to
determine how to carry out requests to create and select bitmaps. If a
driver sets the RC_DEVBITS value, it must export the following functions:

o   BitmapBits

o   RealizeObject

o   SelectBitmap

BitmapBits copies bitmap data to and from device bitmaps. GDI calls this
function when initializing the bitmap bits after creating the bitmap. It
also calls the function when an application calls the functions such as
GetBitmapBits (GDI.74) and SetBitmapBits (GDI.106).

RealizeObject creates or deletes a device bitmap. GDI calls this function
when creating the bitmap, specifying the OBJ_BITMAP style. RealizeObject is
responsible for allocating memory to the device as well as filling a
physical PBITMAP structure that GDI will use to identify the device bitmap.
If the bitmap is to be deleted, RealizeObject must free the device memory.

SelectBitmap associates a device bitmap with the given PDEVICE structure.
GDI passes the physical PBITMAP structures of both the currently selected
bitmap and the new bitmap so that SelectBitmap can carry out any special
processing to enable or disable access to the device bitmaps.

Device bitmaps cannot be monochrome bitmaps. GDI intercepts all requests to
create monochrome bitmaps and creates main memory bitmaps instead. This
means a graphics driver that supports device bitmaps must also be able to
support main memory bitmaps.

NOTE If the display driver supports device bitmaps, it must not fail any
calls to the SelectBitmap, BitmapBits, or RealizeObject functions. If the
driver cannot allocate more video memory for a requested bitmap, it must
use GlobalAlloc to allocate system memory instead.


2.1.15 Color Palettes

Display devices that are capable of displaying 256 or more simultaneous
colors using a palette need to provide support for color palettes. A
display driver specifies that it has palette support by setting the
RC_PALETTE value in the dpRaster member in the GDIINFO structure. The
display driver also must set the dpPalColors, dpPalReserved, and
dpPalResolution members.

The number of reserved colors on the palette is always 20, with 16
corresponding to the VGA colors and 4 special colors. Half of the reserved
palette colors are placed at the beginning and half at the end of the
palette.

If a display driver supports color palettes, it must export the SetPalette,
GetPalette, SetPalTrans, and GetPalTrans functions.


2.1.15.1 Hardware-Palette Initialization

A display driver should initialize the hardware palette when the driver
initializes the rest of the display hardware. The driver initializes the
palette for static and nonstatic colors.

Static colors are system colors that remain in the palette at all times and
are used for old-style RGB support. The number of static colors to be used
is specified in the dpPalReserved member in the GDIINFO structure. This
number must always be even. The colors are placed in the hardware palette
so that the first half is in the lowest entries, and the second half is in
the highest entries.

For Windows 3.x, 20 static colors should be set as follows:

    ; Lowest ten palette entries

    db      0,   0,   0,   0        ; 0
    db      080h,0,   0,   0        ; 1
    db      0,   080h,0,   0        ; 2
    db      080h,080h,0,   0        ; 3
    db      0,   0,   080h,0        ; 4
    db      080h,0,   080h,0        ; 5
    db      0,   080h,080h,0        ; 6
    db      0C0h,0C0h,0C0h,0        ; 7
    db      192, 220, 192, 0        ; 8
    db      166, 202, 240, 0        ; 9

    ; Highest ten palette entries

    db      255, 251, 240, 0        ; 10
    db      160, 160, 164, 0        ; 11
    db      080h,080h,080h,0        ; 12
    db      0FFh,0,   0,   0        ; 13
    db      0,   0FFh,0,   0        ; 14
    db      0FFh,0FFh,0,   0        ; 15
    db      0,   0,   0FFh,0        ; 16
    db      0FFh,0,   0FFh,0        ; 17
    db      0,   0FFh,0FFh,0        ; 18
    db      0FFh,0FFh,0FFh,0        ; 19
These colors consist of the 16 standard VGA colors and four other special
colors used by Windows.

The nonstatic colors included in the hardware palette need not be
initialized. GDI manages these and initializes them when needed.

The RGBs for an 8bpp system palette should exactly match those reported to
GDI by the 8514/a driver. Using these RGBs ensures that colors will be
preserved when an image created with solid colors is viewed on a 4bpp
display.

An 8bpp display driver should not necessarily program the DAC with the
exact RGBs as in the GDI system palette. Instead, DAC values should be used
that result in on-screen system colors reasonably close to those shown by
the Windows 8514/a display driver. This accounts for differences in color
representation by DACs on different display adapters.


2.1.15.2 Palette-Translation Table

The driver has to maintain a palette-translation table to translate the
logical color indexes, passed to it by GDI, into the actual physical color
indexes. The translation has to occur before any raster operation (ROP) is
performed. ROPs are always applied to physical colors.

Whenever a display driver function receives a DRAWMODE, LPEN, PBRUSH, or
PBITMAP structure, the driver may need to translate the logical colors in
these structures to physical colors before using the colors.

An application has to perform color translation only when the physical
device is involved. In other words, if a line is drawn into a memory bitmap
or a bitmap is block transferred into another memory device, no color
translation is required. On the other hand, if a bitmap is transfered to or
from the screen into a memory bitmap or a line is drawn directly onto the
screen, color translation is required. In the case of a block transfer from
the screen to the screen (where the physical device is both the source and
destination of the block transfer), color translation is not needed since
all the color indexes are already translated into physical indexes.

Color specifications are passed to display drivers as either color indexes
or RGB values. A color index is a 32-bit value in which the high 16-bits is
set to 0xFF00 and the low 16-bits is the actual index. An RGB value is a
32-bit value as specified by the RBGQUAD structure. When an RGB value is
specified, it should match this color as closely as possible among the 20
reserved colors. In the case of a brush, the color may be dithered with the
16 VGA colors.

A palette-translation table is an array of 16-bit indexes, each mapping a
logical color index to a physical color index. A display driver uses the
translation table to translate color indexes in physical pens and brushes
and in the DRAWMODE structure to the actual color indexes used by the
hardware palette.

GDI calls the GetPalTrans and SetPalTrans functions to get and set the
translation table. The translation table has the number of elements
specified by the dpPalColors member. In constructing the inverse table, the
driver may come across ambiguities because different logical colors can map
to the same physical color. It is up to the driver to decide how to resolve
these cases since the result will look the same no matter how such
ambiguities have been resolved. The driver can also set accelerator bits to
bypass the various translations. For BitBlt, bypassing color translation
results in substantial performance improvements.


2.1.15.3 UpdateColors Function

If a display driver supports color palettes, it must include the
UpdateColors function. GDI calls this function to direct the driver to
redraw a region on screen using the translation table passed to the
function. For each pixel in the region, the function retrieves the pixel's
color index, translates the index, and writes the translated index back to
the given pixel.


2.1.15.4 Black-and-White Palette Entries

Display drivers that support color palettes must make sure that the index
for the palette entry that corresponds to black must be the one's
complement of the index for the palette entry for white. Black and white
must be static palette entries, meaning the driver sets the indexes for
these colors during initialization and does not change the indexes.


2.1.16 DIBs with Color-Palette Management

The color table for a device-independent bitmap (DIB) consists of 16-bit
indexes used as the colors for the bitmap. For the SetDIBitsToDevice
function, they are physical indexes; for the DeviceBitmapBits function,
they are logical indexes.

In the DeviceBitmapBits and SetDIBitsToDevice functions, the final
parameter, lpTranslate, provides information that is useful only for
palette-capable devices. However, all devices need to include this
parameter.

When DeviceBitmapBits is retrieving bits on a 256-color device, lpTranslate
is a pointer to a translation table with the following results.

Bitcount   Result
---------------------------------------------------------------------------

1          A palette-sized array of bytes, each one either 0x00H or 0xFFH.
           The array is used to determine if the index in the bitmap
           corresponds to a zero or a 1 in the DIB.

4          A palette-sized array of bytes, each one containing a value
           between 0x00H and 0xFFH. Each index in the bitmap will map to
           the corresponding 4-bit values in the DIB.

8          lpTranslate will equal an identity table that can be ignored.

24         A palette-sized array of 32-bit values, each one containing the
           RGB value (and unused high byte) corresponding to the index in
           the bitmap.

On a palette-capable device when the source bitmap is a monochrome bitmap,
DeviceBitmapBits passes in a translation table that has only two entries,
instead of 256. Entry 0 has the color-table index for black and entry 1 has
the color table index for white.

When DeviceBitmapBits sets bitmap bits, GDI passes a pointer only if the
bitcount is 24. The parameter points to data maintained by GDI. For every
RGB value in the DIB, the display driver calls the DeviceColorMatch
function (GDI.449) to match an RGB value with an index. This function
returns an index to represent that color in the device-dependent bitmap.


2.1.17 Stub Functions

Although the SetAttribute and DeviceBitmap functions are not currently
supported in GDI, a display driver must provide these functions. In all
drivers, these functions are implemented as stub functions that do nothing
more than always return a -1.


2.1.18 Cursors

The USER module requires all display drivers to provide cursor support. A
display driver must provide the following functions.

Function        Description
---------------------------------------------------------------------------

CheckCursor     Draws the cursor if drawing is not disabled.

InquireCursor   Retrieves information about the cursor.

MoveCursor      Moves the cursor to a specified position on the display.

SetCursor       Sets the cursor shape.

When Windows first starts, USER calls the InquireCursor function to
retrieve information about the cursor. It then sets a system timer to call
the CheckCursor function on each timer interrupt and enables the mouse
driver, allowing the Windows mouse-event routine to call MoveCursor at each
mouse interrupt occurrence. USER and Windows applications subsequently set
the shape of the cursor using SetCursor.

Because USER calls MoveCursor on each mouse interrupt, MoveCursor should
set a semaphore to prevent the function from being called before it can
complete the current call. The function should set the semaphore using a
noninterruptable instruction such as the xchg instruction. Once the
semaphore is set, MoveCursor should retrieve the x and y coordinates of the
current call, set a flag to indicate that the cursor is being redrawn, and
clear the semaphore. Whenever MoveCursor is called, it should check this
flag before continuing the request.

The CheckCursor function is called on each timer interrupt. The function
should determine whether the cursor needs redrawing and whether drawing is
enabled. If so, the function should redraw the cursor.

For displays that do not have hardware cursor, the display driver should
exclude the cursor from the screen before carrying out drawing operations
in functions such as BitBlt, Output, and ExtTextOut. The driver should
check the current x and y coordinates and exclude the cursor if any part of
the cursor lies within the drawing region as specified in the following.

Operation            Region
---------------------------------------------------------------------------

Bit-block transfer   Destination rectangle

Ellipse              Bounding rectangle

Other line drawing   Bounding rectangle

Polygon              Clip rectangle

Polyline             Clip rectangle

Scan line            Whole scan line

Text                 Bounding rectangle and/or opaquing rectangle


2.1.19 Display-Driver Escapes

A display driver provides the Control function to give applications direct
access the display driver. Most display drivers only provide support for
the following escapes:

o   GETCOLORTABLE

o   MOUSETRAILS

o   QUERYESCSUPPORT

Applications call the QUERYESCSUPPORT escape to determine whether the
display driver supports a given escape.


2.1.20 Mouse Trails

In Windows 3.1, display drivers can improve mouse cursor visibility
(especially on liquid crystal displays (LCD)) by supporting mouse trails. A
mouse trail is a sequence of two or more cursor images that mark current
and previous mouse cursor positions. A display driver creates a mouse trail
by drawing a cursor at each new mouse position and leaving additional
cursors at previous positions. The driver delays erasing the previous
cursors until a specified number of cursors are visible.

A display driver provides support for mouse trails by processing the
MOUSETRAILS escape in its Control function. The MOUSETRAILS escape enables
or disables mouse trails. It also sets the maximum number of cursors to be
displayed in the trail. The display driver must also process the
QUERYESCSUPPORT escape, returning the status of the mouse trails if the
requested escape is MOUSETRAILS.

The display driver draws the mouse trail when it processes the MoveCursor
function. Any trailing cursors must have the same shape as the current
cursor. The display driver should provide mouse trails for system cursors,
such as the pointer and hourglass, and for application-specific cursors as
well. Currently, support is not provided for mouse trails for XOR-only
cursors, such as the I-beam and the cross-hair cursor used by PaintBrush.

The display driver is responsible for recording the mouse trail status by
maintaining the MouseTrails setting in the [Windows] section of the WIN.INI
file. The driver switches this setting to a positive value to indicate that
mouse trails capability is enabled. The value also specifies the number of
cursors to display. The driver switches this setting to a zero or a
negative value when mouse trails capability is disabled. The absolute value
specifies the number of cursors to display prior to being disabled.

Users can turn mouse trails on or off by using Windows 3.1 Control Panel.
The mouse settings dialog box displays a Mouse Trails option.

Applications should not enable or disable mouse trails. However,
third-party mouse configuration programs should.


2.1.21 Multiple-Resolution Drivers

A multiple-resolution display driver provides the code and resources needed
to support all resolutions of a given display device. In previous versions
of Windows, separate display drivers were required for each resolution. In
Windows 3.1, a single display driver can handle all resolutions.

A multiple-resolution driver must provide the following:

o   GetDriverResourceID function

o   Icons and cursors for each supported resolution

o   Installation information


2.1.21.1 Resources and Resource Mapping

In many cases, the only difference for the driver between the device
resolutions is the size of the resources and the horizontal and vertical
dimensions. A driver can support multiple resolutions as long as it can
determine which resolution Windows expects it to use.

To support multiple resolutions in a single display driver, Windows checks
for the GetDriverResourceID function in the driver and calls it before
loading the driver's resources and dimensions. This gives the driver a
chance to check the SYSTEM.INI file using the GetPrivateProfileInt
(KERNEL.127) or GetPrivateProfileString (KERNEL.128) functions for
information specifying the desired resolution. The GetDriverResourceID
function can then map the request resource identifier to the identifier of
the corresponding resource for the desired resolution. In this way, the
driver makes sure Windows loads the appropriate resources for the
resolution to be used.

When Windows calls the GetDriverResourceID function, the driver should at
least check for the aspect entry in the [Boot.description] section of the
SYSTEM.INI file. This entry specifies the resolution (in dots-per-inch) of
the display. Drivers use this value to determine which fonts to use as well
as to determine other resource that depend on the number of dots-per-inch
the display generates.

Display drivers that support multiple resolutions must export the
GetDriverResourceID function and provide a set of appropriate resources for
each resolution.


2.1.21.2 Installation Information

Users select the desired resolution for the display using the Setup
program. To display each screen resolution, Setup checks the [Display]
section in the SETUP.INF or OEMSETUP.INF file. There must be one line for
each resolution. For example, if a video adapter named ZGA has three
resolutions (640x480, 800x600, and 1024x768), the [Display] section should
look something like this:

    [display]
    zga1=1:zga.drv,"ZGA(640x480)","100,96,96",3:zgacolor.2gr,... ,zgalo
    zga2=1:zga.drv,"ZGA(800x600)","100,96,96",3:zgacolor.2gr,... ,zgamed
    zga3=1:zga.drv,"ZGA(1024x768)","100,120,120",3:zgacolor.2gr,... ,zgahi
Setup installs the same driver (ZGA.DRV), grabbers, virtual-display device,
and other related components. However, the last field in the line specifies
an additional section in the SETUP.INF or OEMSETUP.INF file that contains
resolution-specific information.

The resolution-specific information allows Windows Setup to copy files and
write profile data for later use by the display driver. Setup can write the
information to the SYSTEM.INI file in the section and format the driver
understands. When a display driver is initialized, it can use the Windows
functions GetPrivateProfileInt or GetPrivateProfileString to read the
user-specified screen resolution from the appropriate section of
SYSTEM.INI. This will let the driver decide what resource ID to return to
Windows by the GetDriverResourceID function.

The following examples show how resolution-specific information sections
might look in the SETUP.INF or OEMSETUP.INF file:

    [zgalo]
    4:zgalo.dll,0:system,,,,

    [zgamed]
    ,,system.ini,zga.drv,,"ZGAres=800x600"

    [zgahi]
    4:zgahi.dll,0:system,system.ini,zga.drv,"ZGAres=800x600","ZGAMode=Hi"
For more information about the resolution-specific information sections,
see the [Display] section.


2.1.22 Microsoft Windows for Pen-Computing Extensions

Display drivers that support Pen Extensions provide a set of functions and
resources that permit the display drivers to carry out inking. Pen Windows
is a version of Windows in which character-recognition software
(Recognition Context (RC) Manager) allows a pen device to be used in place
of a keyboard. Inking is drawing done by a display driver in response to
input from the RC Manager.


2.1.22.1 Inking Functions

Display drivers that support inking must be prepared to process inking
requests whenever pen input generates an interrupt. The drivers must export
the GetLPDevice and InkReady functions.

If the RC Manager requires inking, it calls the GetLPDevice function to
retrieve a pointer to the display driver's PDEVICE structure. The RC
Manager uses this pointer in subsequent calls to the display driver's
Output function to complete the inking. The color and width of the ink is
set by the RC Manager.

Before calling Output, the RC Manager calls the InkReady function to notify
the display driver that it is ready to ink. The display driver must
determine whether any other drawing operation is under way. If so, the
display driver must wait until the current operation is complete before
completing the inking. In any case, the display driver calls a callback
function supplied with the call to InkReady to complete the inking.


2.1.22.2 Inking Resources

Display drivers that support inking must provide the following cursor
resources.

Value               Meaning
---------------------------------------------------------------------------

IDC_NEPEN (32630)   Pen points to northeast.

IDC_NWPEN (32631)   Pen points to northwest.

IDC_SEPEN (32632)   Pen points to southeast.

IDC_PEN (32633)     Default pen is same as IDC_SWPEN.

IDC_SWPEN (32633)   Pen points to southwest.

The pen cursors must be added to the driver in the same way as the standard
Windows cursors.


2.2 About Display-Driver Resources

Display drivers contain most of the cursors, icons, and bitmaps that use
Windows. They are supplied by the display driver to account for the aspect
ratio and resolution of the display adapter. Also, the definitions of
certain system parameters (for example, default colors and border widths)
are supplied by the display driver. All of this information is supplied as
resources that are added to the driver by the resource compiler (RC.EXE).

A display driver requires the following resources.

Resource                  Description
---------------------------------------------------------------------------

Stock fonts               The stock-font resource defines the
                          characteristics of the stock-font objects used by
                          Windows.

Configuration             The configuration resource contains information
                          about default system colors, line widths, cursor
                          sizes, icon sizes, and so on.

Color table               The color table resource contains the color table
                          for Control Panel's Color dialog box.

Icons, cursors, bitmaps   The icon, cursor, and bitmap resources define the
                          shape and appearance of various elements of the
                          Windows desktop.


2.2.1 Stock-Fonts Resource

The stock-font resource (defined by the FONTS.BIN file) defines the
characteristics of the stock-font objects used by Windows. Windows requires
three stock fonts:

o   OEM font (the Terminal font)

o   ANSI fixed-pitch font

o   ANSI variable-pitch font

Windows supplies a wide variety of stock-font files at various aspect
ratios, so most display drivers do not have to provide the actual font
files to support these stock fonts. Windows provides the following screen
and system fonts.

---------------------------------------------------------------------------
Font name   Aspect ratio     Logical pixels per inch X   Logical pixels per
                                                         inch Y
---------------------------------------------------------------------------

COURB       EGA, 1.33 to 1   96                          72

EGASYS      EGA, 1.33 to 1   96                          72

SERIFB      EGA, 1.33 to 1   96                          72

SMALLB      EGA, 1.33 to 1   96                          72

SSERIFB     EGA, 1.33 to 1   96                          72

COURE       VGA, 1 to 1      96                          96

SERIFE      VGA, 1 to 1      96                          96

SMALLE      VGA, 1 to 1      96                          96

SSERIFE     VGA, 1 to 1      96                          96

VGAFIX      VGA, 1 to 1      96                          96

VGASYS      VGA, 1 to 1      96                          96

8514FIX     8514/A, 1 to 1   120                         120

8514SYS     8514/A, 1 to 1   120                         120

COURF       8514/A, 1 to 1   120                         120

SERIFF      8514/A, 1 to 1   120                         120

SMALLF      8514/A, 1 to 1   120                         120

SSERIFF     8514/A, 1 to 1   120                         120

---------------------------------------------------------------------------

All the filenames have the same .FON extension.


2.2.2 Configuration Resource

The configuration resource (defined by the CONFIG.BIN file) contains
information about default system values, such as, desktop colors,
horizontal and vertical line widths, scroll bar thumb sizes, and cursor and
icon compression ratios.


2.2.3 Color-Table Resource

The color-table resource (defined by the COLORTAB.BIN file which contains
the COLORTABLE structure) contains a list of the colors that are to appear
in the Control Panel's Color dialog box. This table should contain all the
solid colors that are representable as RGB values as well any patterned
colors that are reasonably close to the colors of the 8514/a display under
Windows 3.1. The table may contain up to 48 RGB values. It is not necessary
for RGBs to be exact across all drivers, but it is important for color
representations to be similar. This accounts for variations in dithering
algorithms of different display drivers.

For Windows 3.1, the recommended default system color values for 16- and
256-color displays are new. In particular, several system colors that were
patterned (dithered) in Windows 3.0 have been changed to solids to improve
performance and visibility on interlaced displays. For color drivers
intended for use on general purpose color displays, the default desktop
colors should always be solid colors. For 4bpp drivers, the default colors
should be the same as used by the Windows 3.1 VGA driver. For 8bpp drivers,
the default colors should be the same as used by the Windows 3.1 8514/a
driver. See CONFIG.BIN for a list of these default colors.

In Windows 3.1, the CONFIG.BIN resource has been expanded to include the
clrInactiveCaptionText member. This member specifies the color of the text
in the title bar of an inactive window.

For a complete description of the default system colors and the
clrInactiveCaptionText member, see the CONFIG.BIN resource.


2.2.4 Icon, Cursor, and Bitmap Resources

The icon, cursor, and bitmap resources define the appearance of elements of
the Windows desktop, such as the minimize and maximum buttons, scroll
boxes, menu icons, and others. The USER module extracts these resources
from the display driver when Windows starts, then uses BitBlt to copy the
resources to the screen when drawing windows. Windows provides a wide
variety of icon, cursor, and bitmap resources at various resolutions and
aspect ratios.


2.2.4.1 Cursors

The following table provides a list of required cursor resources. The last
four cursors in the list are no longer used by Windows, but must be
provided for compatibility with existing Windows applications.

Resource       Appearance
---------------------------------------------------------------------------

CROSS.CUR      An upright cross used as a selection marker.*

IBEAM.CUR      An I-beam shaped cursor used in edit control windows.

ICON.CUR       An empty box formerly used when the mouse was in the icon
               area.*

NORMAL.CUR     An upward diagonal arrow used as the default mouse cursor.

SIZE.CUR       A box shape formerly used when sizing tiled windows.*

SIZENESW.CUR   A two-headed arrow used when sizing windows. Arrows point
               northeast and southwest.

SIZENS.CUR     A two-headed arrow used when sizing windows. Arrows point
               north and south.

SIZEWE.CUR     A two-headed arrow used when sizing windows. Arrows point
               west and east.

SIZENWSE.CUR   A two-headed arrow used when sizing windows. Arrows point
               northwest and southeast.

UP.CUR         An upward arrow.*

WAIT.CUR       An hourglass that is used while carrying out lengthy
               operations.

* These resources are only for compatibility for versions of Windows prior
to 3.0.


2.2.4.2 Icons

The following table provides a list of required icons resources.

Resource     Appearance
---------------------------------------------------------------------------

BANG.ICO     An exclamation mark used to emphasize the consequences of an
             operation.

HAND.ICO     A stop sign used to indicate an error condition that halts
             operation.

NOTE.ICO     An asterisk used to indicate noncritical situations.

QUES.ICO     A question mark used when querying for a reply.

SAMPLE.ICO   The default icon used when no other icon to an operation can
             be found.


2.2.4.3 Bitmaps

The following table provides a list of required bitmap resources. The first
seven bitmaps have two forms (up and down) used to create a 3-D effect when
pushing in a button. The last eleven bitmaps are no longer used by Windows,
but must be supplied for compatibility with applications that expect them
to be available.

Resource       Appearance
---------------------------------------------------------------------------

COMBO.BMP      An arrow used in combo boxes.

DOWN.BMP       Up down-pointing arrow for scroll bars.

DOWND.BMP      Down down-pointing arrow for scroll bars.

LEFT.BMP       Up left-pointing arrow for scroll bars.

LEFTD.BMP      Down left-pointing arrow for scroll bars.

MAX.BMP        Up maximize button on the title bar.

MAXD.BMP       Down maximize button on the title bar.

MIN.BMP        Up minimize button on the title bar.

MIND.BMP       Down minimize button on the title bar.

MNARROW.BMP    An arrow used in multilevel menus.

OBTNCORN.BMP   A circle formerly used to draw round-cornered buttons.

OBTSIZE.BMP    A size box used at the intersection of vertical and
               horizontal scroll bars.*

OBUTTON.BMP    A box used for check boxes in dialog boxes.

OCHECK.BMP     A check mark used to check menu items.

OCLOSE.BMP     The system-menu bitmaps used for Windows 2.x.*

ODOWN.BMP      A down-arrow bitmap used for Windows 2.x.*

OLEFT.BMP      A left-arrow bitmap used for Windows 2.x.*

ORED.BMP       This resource minimizes the bitmap used for Windows 2.x.*

OREST.BMP      Restores the bitmap used for Windows 2.x.*

ORIGHT.BMP     A right-arrow bitmap used for Windows 2.x.*

OSIZE.BMP      A size box formerly used on tiled windows.*

OUP.BMP        An up-arrow bitmap used for Windows 2.x.*

OZOOM.BMP      Maximizes the bitmap used for Windows 2.x.*

RESTORE.BMP    Up restore button on the title bar.

RESTORED.BMP   Down restore button on the title bar.

RIGHT.BMP      Up right-pointing arrow for scroll bars.

RIGHTD.BMP     Down right-pointing arrow for scroll bars.

SYSMENU.BMP    A double-wide image that contains system menu shapes for
               both main windows and multiple document interface (MDI)
               windows.

UP.BMP         Up up-pointing arrow for scroll bars.

UPD.BMP        Down up-pointing arrow for scroll bars.

* These resources are only for compatibility for versions of Windows prior
to 3.0.


2.2.5 Large Icons and Cursors

In Windows 3.1, display drivers can use icons larger than 64-by-64 bits and
cursors larger than 32-by-32 bits. Large icons and cursors can improve
screen readability for high-resolution graphics adapters.

Display drivers specify icon and cursor size in the CONFIG_BIN structure in
the IconXRatio, IconYRatio, CurXRatio, and CurYRatio members of the
CONFIG.BIN resource (that is, the resource having identifier 1 and type
OEMBIN). In Windows 3.1, these members specify either a width and height in
pixels or a compression ratio. In Windows 3.0, these members only specify
compression ratios. For a complete description of the members, see the
CONFIG.BIN resource.

In all cases, each icon or cursor must have the same width and height in
pixels.

Display drivers which specify actual widths and heights in the OEMBIN
resource can not be used with Windows 3.0. Drivers which specify
compression factors work with both Windows 3.0 and 3.1. However, drivers
cannot simultaneously specify compression factors and icons or cursors
larger than 32-by-32.


2.2.6 Optimizing Performance

Whenever possible, display drivers should use the features of the CPU to
optimize their performance. This is particularly important for drivers when
used in multimedia versions of Windows.

A display driver can determine what CPU is present and what mode Windows is
operating in by examining the __WinFlags variable or by calling the
GetWinFlags function. If the CPU is at least a 386, the display driver
should take advantage of the CPU's 32-bit registers to manipulate data and
to index huge arrays.


2.2.6.1 Tips for Writing Transparent Text

Drivers generating VGA text output can make two significant speedups for
transparent text: don't draw empty bytes or words and use write mode 3.

While drawing the character to video memory, avoid copying the empty part
of a glyph's bitmap. For example, there is no need to copy the space
character to video memory or the ascender on letters like the lowercase
'p'. Since accessing video memory is nearly 5 times slower than accessing
system memory, it is cheaper to check for and ignore empty bytes or words
in a glyph bitmap, than it is to store nothing to video memory. In the
following example, the code gives a significant performance increase for
many video adapters:

          mov  ax,glyphbits
          or   ax,ax
          jz   around_it
          xchg es:[di],ax
      around_it:
Use write mode 3 on VGA hardware. This mode simplifies the output of
transparent text by eliminating the extra step of setting the bitmask
register for each store to video memory. For example, the VGA portion of
the following EGA/VGA code uses write mode 3 for the VGA adapter and is
considerably faster than the equivalent EGA code.

            mov     ax,glyphbits
    if _EGA
            push    dx
            mov     dx,3cfh
            out     dx,al
            xchg    es:[di],al              ;write ax to screen.
            mov     al,ah
            out     dx,al
            xchg    es:[di+1],ah            ;write ax to screen.
            pop     dx
    else
            xchg    es:[di],al              ;write ax to screen.
            xchg    es:[di+1],ah            ;write ax to screen.
    endif

2.2.6.2 Tips for Using the Interrupt Flag

Display drivers should avoid needless clearing and setting of the interrupt
flag using the cli and sti instructions. Since 386 enhanced-mode Windows
traps these instructions as part of its management of the CPU's virtual
mode, these instructions each take about 600 CPU clocks to execute.


2.3 Function Reference

The following is an alphabetical listing of graphics functions that are
specific to display drivers. For a complete description of the graphics
functions that are common to other graphics drivers, see Chapter 10,
Graphics-Driver Functions.

CheckCursor

    void CheckCursor(void)

The CheckCursor function is called on every timer interrupt. It allows the
cursor to be displayed if it is no longer excluded.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 104.



FastBorder

    WORD FastBorder(lpRect, wHorizBorderThick, wVertBorderThick, dwRasterOp,
        lpDestDev, lpPBrush, lpDrawMode, lpClipRect)
    LPRECT lpRect;
    WORD wHorizBorderThick;
    WORD wVertBorderThick;
    DWORD dwRasterOp;
    LPDEVICE lpDestDev;
    LPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The FastBorder function draws a rectangle with a border on the screen.
However, the size is subject to the limits imposed by the specified
clipping rectangle. The border is drawn within the boundaries of the
specified rectangle.


Parameters

   lpRect
   Points to a RECT structure specifying the rectangle to be framed.

   wHorizBorderThick
   Specifies the width in pixels of the left and right borders.

   wVertBorderThick
   Specifies the width in pixels of the top and bottom borders.

   dwRasterOp
   Specifies the raster operation to be used.

   lpDestDev
   Points to a PDEVICE structure that identifies the device to receive the
   output.

   lpPBrush
   Points to a PBRUSH structure.

   lpDrawMode
   Points to a DRAWMODE structure that includes the current text color,
   background mode, background color, text justification, and character
   spacing. See the DRAWMODE data structure description in Chapter 12,
   Graphics-Driver Types and Structures, for a description of text
   justification and character spacing.

   lpClipRect
   Points to a RECT structure specifying the clipping rectangle.


Return Value

The return value is AX = 1 if successful. Otherwise, AX = 0.


Comments

The export ordinal for this function is 17.

The specified rectangle should be given as (UpperLeftCorner,
LowerRightCorner). If it is specified incorrectly, the sample function will
draw the borders outside of the specified rectangle, instead of correctly
drawing them inside.

The function is optional for display drivers. It is required at the GDI
level but not at the display level.

The raster operation to be used will never have a source operand within it.

The lpDrawMode parameter is simply a long pointer to the DRAWMODE data
structure. It is included only for compatibility with earlier versions and
is not crucial. The only field that you may use from there is
BackgroundColor.



Inquire

    WORD Inquire(lpCursorInfo)
    LPCURSORINFO lpCursorInfo;

The Inquire function returns the mouse's mickey-to-pixel ratio for your
screen.


Parameters

   lpCursorInfo
   Points to a CURSORINFO structure containing a device information that is
   filled in by the device driver. The first word is the X mickey-to-pixel
   ratio, and the second word is the Y mickey-to-pixel ratio.


Return Value

The return value is the number of bytes (4) in the AX register actually
written into the data structure.


Comments

The export ordinal for this function is 101.

This function is called once per initialization before the Enable function.



MOUSETRAILS

    #define MOUSETRAILS 39

    WORD Control(lpDestDevice, MOUSETRAILS, lpTrailSize, NULL)
    LPPDEVICE lpDestDevice;
    LPINT lpTrailSize;

The MOUSETRAILS escape enables or disables mouse trails for the display
driver.


Parameters

   lpDestDevice
   Points to a PDEVICE structure specifying the destination device.

   lpTrailSize
   Points to a 16-bit variable containing a value specifying the action to
   take, and the number of mouse cursor images to display (trail size). The
   variable can be one of the following values.

            Value         Meaning
            ---------------------------------------------------------------

            1 through 7   Enables mouse trails and sets the trail size to
                          the specified number. A value of 1 requests a
                          single mouse cursor; 2 requests that one extra
                          mouse cursor be drawn behind the current mouse
                          cursor, and so on, up to a maximum of 7 total
                          cursor images. The function sets the MouseTrails
                          setting in the WIN.INI file to the given value.
                          The function then returns the new trail size.

            0             Disables mouse trails. The function sets the
                          MouseTrails setting to the negative value of the
                          current trail size (if positive). The function
                          then returns the negative value.

            -1            Enables mouse trails. The display driver reads
                          the MouseTrails setting from the [Windows]
                          section of the WIN.INI file. If the setting value
                          is positive, the function sets the trail size to
                          the given value. If the setting value is
                          negative, the function sets trail size to the
                          setting's absolute value and writes the positive
                          value back to WIN.INI. If the MouseTrails setting
                          is not found, the function sets the trail size to
                          7 and writes a new MouseTrails setting to the
                          WIN.INI file, setting its value to 7. The
                          function then returns the new trail size.

            -2            Disables mouse trails but does not cause the
                          driver to update the WIN.INI file.

            -3            Enables mouse trails but does not cause the
                          driver to update the WIN.INI file.


Return Value

The return value specifies the size of the escape if successful. Otherwise,
it is zero if the escape is not supported.


Comments

An application can retrieve the current trail size by calling the
QUERYESCSUPPORT escape as shown in the following example:

    Escape(hDC, QUERYESCSUPPORT, sizeof(int), MOUSETRAILS, NULL);
The QUERYESCSUPPORT escape returns the current trail size without changing
to the current setting. If the escape returns zero, mouse trails are not
supported by the display driver. If the escape returns a positive value,
mouse trails are enabled and the value specifies the current trail size. If
the escape returns a negative value, mouse trails are currently disabled
and the value is the same as the negative MouseTrails value specified in
the WIN.INI file.



MoveCursor

    void MoveCursor(wAbsX, wAbsY)
    WORD wAbsX;
    WORD wAbsY;

The MoveCursor function moves the cursor to the given screen coordinates.
If the cursor is a composite of screen and cursor bitmaps (that is, not a
hardware cursor), this function must ensure that screen bits under the
current cursor position are restored and the bits under the new position
are saved. The function must move the cursor, even if the cursor is not
currently displayed.


Parameters

   wAbsX
   Specifies the absolute x-coordinate of the new cursor position.

   wAbsY
   Specifies the absolute y-coordinate of the new cursor position.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 103.

Microsoft Windows may specify a position at which the cursor shape would
lie partially outside of the display bitmap. The OEM function is
responsible for clipping the cursor shape to the display boundary.

The MoveCursor function is called at mouse-interrupt time, outside of the
main thread of Windows processing. Since MoveCursor may even interrupt its
own processing, the device driver should disable interrupts while reading
the wAbsX and wAbsY coordinates by using the EnterCrit and LeaveCrit macros
in the WINDEFS.INC file. Do not use sti and cli instructions in the driver.



SaveScreenBitmap

    WORD SaveScreenBitmap(lpRect, wCommand)
    LPRECT lpRect;
    WORD wCommand;

The SaveScreenBitmap function saves a single bitmap from the display or
restores a single (previously stored) bitmap to the display. It is used,
for example, when a menu is pulled down, to store the part of the screen
that is behind the menu until the menu is closed.


Parameters

   lpRect
   Points to a RECT structure containing the rectangle to use.

   wCommand
   Specifies the action to take. It can be one of the following values:

            Value   Meaning
            ---------------------------------------------------------------

            0       Saves the rectangle.

            1       Restores the rectangle.

            2       Discards previous save, if there was one.


Return Value

The return value is AX=1 if successful. Otherwise, AX=0 for any of the
following error conditions:

o   Shadow memory does not exist (save, restore, ignore).

o   Shadow memory is already in use (save).

o   Shadow memory is not in use (restore).

o   Shadow memory has been stolen or trashed (restore).


Comments

The export ordinal for this function is 92.

Because SaveScreenBitmap can save only one bitmap at a time, the device
driver must maintain a record of whether or not the save area is currently
in use.

The bitmap is stored in shadow memory (that is, memory for which the device
has control of allocation). Therefore, the device can save the bitmap in
whatever form is most convenient for it, without the rest of Windows
worrying about where it goes.



SetCursor

    void SetCursor(lpCursorShape)
    LPCURSORSHAPE lpCursorShape;

The SetCursor function sets the cursor bitmap that defines the cursor
shape. Each call replaces the previous bitmap with that pointed to by
lpCursorShape. If lpCursorShape is NULL, the cursor has no shape and its
image is removed from the display screen.


Parameters

   lpCursorShape
   Points to a CURSORSHAPE structure that specifies the appearance of the
   cursor for the specified device.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 102.

The cursor bitmap is actually two bitmaps. The first bitmap is ANDed with
the contents of the screen, and the second is XORed with the result. This
helps to preserve the appearance of the screen as the cursor is replaced
and ensures that at least some of the cursor is visible on all the
potential backgrounds.


2.4 Windows for Pen Computing Function Reference

The following is an alphabetical listing of the Pen computing functions for
display drivers.



GetLPDevice

    LPPDEVICE GetLPDevice(VOID);

The GetLPDevice function retrieves a pointer to the display driver's
physical device structure (PDEVICE). The Recognition Context Manager (RC)
for Pen computing calls this function when preparing to ink.

Display drivers that support Pen computing must export the GetLPDevice
function.


Parameters

This function has no parameters.


Return Value

The return value is a 32-bit pointer to the physical-device structure
(PDEVICE).


Comments

The export ordinal for this function is 601.

The RC Manager uses the pointer in subsequent calls to the display driver's
Output function. When the RC Manager has pen strokes to draw, it calls
Output using the OS_POLYLINE parameter.


See Also

InkReady, Output



InkReady

    BOOL InkReady(lpfn)
    LPFN lpfn;      /* pointer to callback function */

The InkReady function notifies the display driver that the Recognition
Context Manager (RC) is ready to ink a path drawn by the pen. The RC
Manager for Pen computing calls this function when the user stroked a path
using the pen. The display driver completes the inking by calling the
callback function pointed to by the lpfn parameter. Depending on whether
any other drawing operation is under way, the driver may call the callback
function immediately or wait for the current drawing operation to complete.

Display drivers that support Pen computing must export the InkReady
function.


Parameter

   lpfn
   Points to the callback function that completes the inking.


Return Value

The return value is TRUE if it completed the inking (called the callback
function) immediately. Otherwise, it is FALSE to indicate that the display
driver will complete the inking as soon as the current drawing operation is
complete.


Comments

The export ordinal for this function is 600.

The InkReady function determines whether any other drawing operation is
under way. If not, the function should call the callback function
immediately, and then return TRUE. If a drawing operation is under way,
InkReady must save the callback function address and return FALSE. The
display driver is then responsible for calling the callback function as
soon as the current drawing operation is complete.

The callback function pointed to by lpfn takes no parameters and returns no
value.


See Also

GetLPDevice


2.5 File-Format Reference

The following is an alphabetical listing of the file formats that are
specific to display drivers.



CONFIG.BIN

    typedef struct tagCONFIG_BIN {

        /* machine-dependent parameters */

        short   VertThumHeight; /* vertical thumb height (in pixels)  */
        short   HorizThumWidth; /* horizontal thumb width (in pixels) */
        short   IconXRatio;     /* icon width (in pixels)             */
        short   IconYRatio;     /* icon height (in pixels)            */
        short   CurXRatio;      /* cursor width (in pixels)           */
        short   CurYRatio;      /* cursor height (in pixels)          */
        short   Reserved;       /* reserved                           */
        short   XBorder;        /* vertical-line width                */
        short   YBorder;        /* horizontal-line width              */

        /* default-system color values */

        RGBQUAD clrScrollbar;
        RGBQUAD clrDesktop;
        RGBQUAD clrActiveCaption;
        RGBQUAD clrInactiveCaption;
        RGBQUAD clrMenu;
        RGBQUAD clrWindow;
        RGBQUAD clrWindowFrame;
        RGBQUAD clrMenuText;
        RGBQUAD clrWindowText;
        RGBQUAD clrCaptionText;
        RGBQUAD clrActiveBorder;
        RGBQUAD clrInactiveBorder;
        RGBQUAD clrAppWorkspace;
        RGBQUAD clrHiliteBk;
        RGBQUAD clrHiliteText;
        RGBQUAD clrBtnFace;
        RGBQUAD clrBtnShadow;
        RGBQUAD clrGrayText;
        RGBQUAD clrBtnText;
        RGBQUAD clrInactiveCaptionText;
    } CONFIG_BIN;
The CONFIG.BIN resource defines the default values for system colors, line
widths (both horizontal and vertical), scroll bar thumb sizes, and cursor
and icon widths or compression ratios.

The CONFIG.BIN resource is required for display drivers.


Members

   VertThumHeight
   Specifies the height in pixels of the vertical scroll-bar thumb.

   HorizThumWidth
   Specifies the width in pixels of the horizontal scroll-bar thumb.

   IconXRatio
   Specifies either the icon width (in pixels) or the compression ratio. If
   a width is specified, it must be greater than 10. The icon resources in
   the driver must have the specified width. If a compression ratio is
   specified, it must be either 1 or 2, and all icon resources in the
   display driver must be 64-by-64-bits.

   IconYRatio
   Specifies either the icon height (in pixels) or the compression ratio.
   If a width is specified, it must be greater than 10. The icon resources
   in the driver must have the specified width. If a compression ratio is
   specified, it must be either 1 or 2, and all icon resources in the
   display driver must be 64-by-64-bits.

   CurXRatio
   Specifies either the cursor width (in pixels) or the compression ratio.
   If a width is specified, it must be greater than 10. The cursor
   resources in the driver must have the specified width. If a compression
   ratio is specified, it must be either 1 or 2, and all cursor resources
   in the display driver must be 32-by-32-bits.

   CurYRatio
   Specifies either the cursor height (in pixels) or the compression ratio.
   If a height is specified, it must be greater than 10. The cursor
   resources in the driver must have the specified height. If a compression
   ratio is specified, it must be either 1 or 2, and all cursor resources
   in the display driver must be 32-by-32-bits.

   Reserved
   Reserved; must be zero.

   XBorder
   Specifies the thickness in pixels of vertical lines.

   YBorder
   Specifies the thickness in pixels of horizontal lines.

   clrScrollbar
   Specifies the color of the scroll bar.

   clrDesktop
   Specifies the color of the Windows background.

   clrActiveCaption
   Specifies the color of the caption in the active window.

   clrInactiveCaption
   Specifies the color of the caption in an inactive window.

   clrMenu
   Specifies the color of the menu background.

   clrWindow
   Specifies the color of a window's background.

   clrWindowFrame
   Specifies the color of the window frame.

   clrMenuText
   Specifies the color of the text in a menu.

   clrWindowText
   Specifies the color of the text in a window.

   clrCaptionText
   Specifies the color of the text in an active caption.

   clrActiveBorder
   Specifies the default color of the text in an active border.

   clrInactiveBorder
   Specifies the color of the text in an inactive border.

   clrAppWorkspace
   Specifies the color of the application workspace (MDI background).

   clrHiliteBk
   Specifies the highlight color used in menus, edit controls, list boxes,
   and so on.

   clrHiliteText
   Specifies the text color for highlighted text.

   clrBtnFace
   Specifies the color of the 3-D button face shading.

   clrBtnShadow
   Specifies the color of the 3-D button edge shadow.

   clrGrayText
   Specifies the color of solid gray to be used for drawing disabled items.
   This member must be set to RGB(0,0,0) if no solid gray is available.

   clrBtnText
   Specifies the color of button text.

   clrInactiveCaptionText
   Specifies the color of the text in an inactive caption.


Comments

The resource identifier for this structure is 1; the resource type is
OEMBIN.

The recommended default system colors depend on the type of display. There
are the following recommended values.

---------------------------------------------------------------------------
Member                   16-Color      256-Color
---------------------------------------------------------------------------

clrActiveBorder          192,192,192   192,192,192

clrActiveCaption         000,000,128   164,200,240

clrAppWorkspace          255,255,255   255,251,240

clrBtnFace               192,192,192   192,192,192

clrBtnShadow             128,128,128   128,128,128

clrBtnText               000,000,000   000,000,000

clrCaptionText           255,255,255   000,000,000

clrDesktop               128,128,000   160,160,164

clrGrayText              192,192,192   192,192,192

clrHiliteBk              000,000,128   164,200,240

clrHiliteText            255,255,255   000,000,000

clrInactiveBorder        192,192,192   192,192,192

clrInactiveCaption       255,255,255   255,255,255

clrInactiveCaptionText   000,000,000   000,000,000

clrMenu                  255,255,255   255,255,255

clrMenuText              000,000,000   000,000,000

clrScrollbar             192,192,192   192,192,192

clrWindow                255,255,255   255,255,255

clrWindowFrame           000,000,000   000,000,000

clrWindowText            000,000,000   000,000,000

---------------------------------------------------------------------------



DISPLAY

    DESCRIPTION 'DISPLAY : AspectXY, LogPixelsX, LogPixelsY : Description'
The DESCRIPTION statement in a display driver's module-definition file
identifies the driver DLL as a a display driver, specifies the aspect-ratio
values associated with the display device, and provides a description for
the driver.


Parameters

   AspectXY
   Specifies the aspect ratio for the display. This parameter must be set
   to the same value as the driver's dpAspectXY member in the GDIINFO
   structure.

   LogPixelsX
   Specifies the horizontal pixels-per-inch for the display. This parameter
   must be set to the same value as the driver's dpLogPixelsX member in the
   GDIINFO structure.

   LogPixelsY
   Specifies the vertical pixels-per-inch for the display. This parameter
   must be set to the same value as the driver's dpLogPixelsX member in the
   GDIINFO structure.

   Description
   Specifies the name the display models supported by this driver. Although
   more than one name can be given, the names must not be separated commas
   (,).


Comments

The DISPLAY keyword must be capitalized.


Example

The following example shows the DESCRIPTION statement for the VGA display
driver:

    DESCRIPTION 'DISPLAY : 100,96,96 : VGA Color Display'
Chapter 3  Display Grabbers

The Microsoft Windows display grabbers provide the support that both
standard- and 386 enhanced-mode Windows needs to share the display with
non-Windows applications. WINOLDAP, which manages all non-Windows
applications, 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.

All display grabbers capture the contents of the screen when requested,
such as when the user presses the ALT+PRNTSCRN key combination. However,
the grabbers are also responsible for other kinds of support. For example,
a standard-mode grabber initializes, saves, and restores the video context
when switching between Windows and non-Windows applications, and a 386
enhanced-mode grabber paints the client area for non-Windows applications
that run in windows.

To distinguish between standard- and 386 enhanced-mode grabbers, Windows
uses the filename extensions .2GR and .3GR. For example, the grabbers that
support the VGA display driver are named VGA.2GR for standard-mode Windows
and VGA.3GR for 386 enhanced-mode Windows. In some cases, a single grabber
may support several display drivers (for example, EGACOLOR.2GR is used for
both EGA.DRV and EGAHIBW.DRV).

This chapter describes display grabbers for standard- and 386 enhanced-mode
Windows.


3.1 About the Standard-Mode Display Grabber

The standard-mode display grabber is a binary-image file consisting of a
set of functions that provide display-dependent services. Windows loads a
grabber whenever the user runs a non-Windows application. The 286grabber
setting in the [Boot] section of the SYSTEM.INI file specifies which
standard-mode grabber to load.

Windows calls grabber functions to set the display mode and to retrieve
information Windows needs to save and restore the video context for
non-Windows applications. When the user switches away or back to an
application, Windows calls other grabber functions to save or restore the
video context for that application.

A display grabber has the following components:

o   Standard functions

o   Extended functions

o   Standard and extended-function dispatch tables

o   Coordinate system


3.1.1 Standard and Extended Functions

A grabber provides a set of standard functions that initialize the display
and save and restore the video context.

The InquireGrab function returns the size of the grabber buffer, which
holds screen data when copying data to the clipboard. This function also
carries out extended functions, depending on the value Windows passes to it
in the AX register. The InquireSave function returns the size of the save
buffer, the buffer used to hold the screen contents and video context when
Windows switches away from the non-Windows application. Either InquireGrab
or InquireSave (whichever Windows calls first) is responsible for
initializing the grabber the first time the function is called.

The SaveScreen and RestoreScreen functions save and restore the video
context needed to support switching away and back to the non-Windows
application. Windows supplies the buffer to receive or contain the data;
the functions are responsible for copying the data to or from the display
device.

The optional InitScreen function initializes the display to a text mode
(one that Windows supports). Windows calls this function before the
non-Windows application starts and when Windows switches away from the
application.

A display grabber also includes several extended functions. Windows calls
the extended functions by supplying an extended-function number in the AX
register when it calls the InquireGrab function.

The GetVersion function (0FFFAh) returns the version number of the grabber,
and the GetInfo function (0FFFEh) returns information about the grabber and
screen. The EnableSave and DisableSave functions (0FFFCh and 0FFFBh) enable
and disable video-context switching. Using these functions allow a grabber
to install or remove hooks needed to support video-context switching. The
SetSwapDrive function (0FFFDh) sets the current swap drive and path that
the grabber can use to create swap files during a context switch. The
GetBlock function (0FFF8h) copies a block of screen data to a specified
buffer.

Windows calls grabber functions in real mode, not in protected mode. This
means the grabber can carry out its work using the same techniques as
MS-DOS programs or drivers.


3.1.2 Standard-Function Dispatch Table

Since a display grabber is a binary-image file, the grabber cannot export
its standard functions. To give Windows access to the functions, the
grabber includes a standard-function dispatch table, consisting of a series
of jump instructions, at the start (offset 0) of its code segment. There is
one 3-byte jump instruction for each grabber function. Windows transfers
control to a grabber function by computing the offset of the desired
function's dispatch table entry and by making a FAR call to that entry.
Although each dispatch table entry is a NEAR jump instruction to the
corresponding function, the function itself must execute a FAR return
instruction when it returns to Windows.

The standard-function dispatch table has the following form:

            org 0

    StdFuncTable label word
            jmp     InquireGrab     ;function 00001h
            jmp     Obsolete        ;function 00002h
            jmp     Obsolete        ;function 00003h
            jmp     Obsolete        ;function 00004h
            jmp     InquireSave     ;function 00005h
            jmp     SaveScreen      ;function 00006h
            jmp     RestoreScreen   ;function 00007h
            jmp     InitScreen      ;function 00008h
The grabber must not modify or move the dispatch table after it has been
loaded.

The dispatch-table entry for the InitScreen function, an optional function,
is at offset 015h. Windows checks for a jump instruction at offset 015h to
determine whether the InitScreen function is present. If InitScreen is
present, Windows calls the function whenever a non-Windows application
starts up, and subsequently after every video-context switch to that
application.


3.1.3 Extended-Function Dispatch Table

A display grabber also includes several extended functions. Windows calls
the extended functions by supplying an extended-function number in the AX
register when it calls the standard function InquireGrab. The InquireGrab
function uses the extended-function dispatch table, consisting of function
offsets, to transfer control to the desired function. This table differs
from the standard-function dispatch table because it contains offsets, not
jump instructions.

The extended-function dispatch table has the following form:

    ExtFuncTable    label   word
            dw      Obsolete        ;function 0FFF4h
            dw      Obsolete        ;function 0FFF5h
            dw      Obsolete        ;function 0FFF6h
            dw      Obsolete        ;function 0FFF7h
            dw      GetBlock        ;function 0FFF8h
            dw      Obsolete        ;function 0FFF9h
            dw      GetVersion      ;function 0FFFAh
            dw      DisableSave     ;function 0FFFBh
            dw      EnableSave      ;function 0FFFCh
            dw      SetSwapDrive    ;function 0FFFDh
            dw      GetInfo         ;function 0FFFEh
            dw      Obsolete        ;function 0FFFFh

3.1.4 Coordinate System

All the grabber-block functions operate using a left-hand coordinate system
that is based on character cells in a manner similar to that used by the
BIOS. The coordinate system origin (0,0) is located in the upper-left
corner of the screen. Positive x direction is to the right and positive y
direction is downward. The coordinate space consists of the set of integers
that range from 0 to (icCharsX - 1) in the x direction and from 0 to
(icCharsY - 1) in the y direction. The quantities icCharsX and icCharsY are
found in the grabber's INFOCONTEXT structure, which may be obtained at any
time by calling the extended-grabber function GetInfo. Notice that points
in this space represent the upper-left corner of the character cells, not
their center.

As indicated by their names, block functions operate on blocks of character
cells. A block is fully specified by its origin (relative to the screen
origin) and its x and y extents in the GRABREQUEST structure. The extents
are unsigned one-based values. A block is the set of character cells in the
rectangle defined by the origin of the block and the x and y coordinates.
Specifying an extent of 0 on either axis has the same effect as specifying
an extent equal to the maximum screen extent on that axis. In other words,
the entire screen may be easily specified by setting:

    grXorg = grYorg = grXext = grYext = 0
For graphics mode, the same cell-based convention applies so that Windows
need not discern differences between graphics and text screens. The size of
a character cell in graphics mode is the same size cell that the BIOS would
use to display text using Interrupt 10h functions. The current grabbers do
not yet support the specification of arbitrary block regions in graphics
mode. An attempt to specify any other block in graphics mode will return
the ERR_UNSUPPORTED error value.

The ERR_BOUNDARY error value indicates blocks that violate screen
boundaries.


3.1.5 Buffer-Size Calculations

The low-level functions of all the grabbers define a number of equates.
These equates are used to calculate the size of various data buffers needed
to take screen snapshots (grabbers) and switch the video context. Because
these calculations vary widely among display adapters, the rationale for
many of the calculated assumptions may not be clear. Therefore, the
explanation provided in the following section is an attempt to clarify this
process.


3.1.6 Binary-Image File

The standard-mode grabber is a binary-image file, not an executable file.
The grabber is built by assembling and linking the sources and converting
the result to a binary file using the exe2bin command.

Since Windows cannot relocate segment addresses in binary-image files, the
grabber's code and data for the grabber should be combined in the same
segment (tiny memory model). To support this model, Windows always sets the
DS register equal to the grabber's code segment address before calling any
grabber function. This means the DS and CS registers are equal when a
grabber function is first called.


3.2 About the 386 Enhanced-Mode Grabber

The 386 enhanced-mode display grabber is a dynamic-link library (DLL). The
library consists of a set of functions that let Windows display the output
of a non-Windows application in a window and copy the screen contents of a
non-Windows application to the clipboard in a Windows-compatible format.

386 enhanced-mode WINOLDAP loads the grabber and calls the functions
whenever it needs to carry out some action with the screen contents of a
nonsystem virtual machine (VM). All non-Windows applications run on
nonsystem virtual machines. The grabber works in conjunction with the
virtual-display device (VDD) to retrieve the screen contents of a given VM.
The contents are displayed in a window or copied to the clipboard. The
386grabber setting in the [Boot] section of the SYSTEM.INI file specifies
which 386 enhanced-mode grabber to load.


3.2.1 Initialization

As with other dynamic-link libraries, Windows calls the grabber's
initialization routine, InitGrabber, when it first loads the grabber.
InitGrabber can carry out any initializations the grabber needs. However,
most grabbers wait until WINOLDAP calls the CheckGRBVersion and GetFontList
functions to carry out initializations.

WINOLDAP calls CheckGRBVersion to check the grabber's version number and to
let the grabber make sure the virtual-display device is compatible with the
grabber. It calls GetFontList to retrieve a list of fonts for drawing text
in a window.


3.2.2 Window Painting and Updating

The grabber receives requests to paint or update the window of a
non-Windows application whenever a change in the video context of the
corresponding VM occurs, such as when the application writes to the screen
or the user changes the size of the window.

If a non-Windows application writes to the screen, the virtual-display
device sends WINOLDAP a screen update message and WINOLDAP calls the
UpdateScreen functions in the grabber to update the window. The grabber
calls the virtual-display device to retrieve the current contents of the VM
screen, then places the contents in the application's window.

If a user resizes a window containing a non-Windows application, Windows
sends WINOLDAP a paint message, and WINOLDAP calls the PaintScreen function
in the grabber to paint the window. Again, the grabber calls the
virtual-display device to retrieve the screen contents, and places the
contents in the window.


3.2.3 Virtual-Display Device Services

The grabber calls several virtual-display device functions to carry out
requests to update, paint, or grab the screen. To call a virtual-display
device function, the grabber first retrieves the virtual-display device
entry point address using Get Device Entry Point Address (Interrupt 2Fh
Function 1684h). The grabber then can set registers and call the address to
carry out a function.

The grabber calls the Get_Version function to verify that it is matched
with the correct virtual-display device. Whenever the grabber needs access
to the video memory or the video controller context, it queries the virtual
display device. The virtual-display device returns a structure describing
the requested memory or controller context.

The grabber calls the Get_Mem function to get the current contents of the
video memory while updating the windowed display. The grabber calls the
Get_GrbMem function to get a snapshot of the entire screen in response to
the user pressing the ALT+PRNTSCRN key combination in a full-screen VM. The
grabber calls the Free_Mem and Free_Grab functions to tell the
virtual-display device that the grabber is no longer using this memory.
Get_State and Get_GrbState return the current and grabbed controller
context, respectively.

The grabber calls the Get_Mod function to update the windowed display
incrementally. Get_Mod returns a structure that indicates modifications to
the current display. The grabber modifies only those parts of the window
that have changed, and then calls the Clear_Mod function to inform the
virtual-display device that the modifications have been carried out.

To make sure that the video memory or context will not change when the
grabber is accessing the memory, the VM should suspend operations
immediately after a call to the Get_Mem or Get_Mod function. The VM can
continue operations only after a call to the Free_Mem function or an
explicit call to the Unlock_App function from the grabber.


3.2.4 On-Screen Selection

When a non-Windows application runs in a window, the user can select all or
a portion of the application's output for copying to the clipboard. Carry
out the following procedure to create a selection:

1.  Choose the MS-DOS icon.

2.  From the System menu, choose the Edit command.

3.  From the Edit cascading menu, choose the Mark command.

4.  Move the cursor to the start point of the selection.

5.  Sweep through a selection using the SHIFT+arrow key combination.

WINOLDAP calls the BeginSelection function, with starting point (0,0), when
the user chooses the Mark command. Each time the user subsequently presses
an arrow key or SHIFT+arrow key combination, WINOLDAP calls the
KeySelection function. KeySelection returns a new starting point for arrow
keys and a new end point for SHIFT+arrow key combinations.

For each new start point, WINOLDAP calls EndSelection to cancel the
previous selection, and calls the BeginSelection function to start the new
selection. For each new end point, WINOLDAP calls the MakeSelctRect
function to record the current selection rectangle.

In text mode, the start and end points must be aligned on character
boundaries. In graphics mode, the points should be aligned on byte or
multiple-byte boundaries.

The coordinates of the start and end points are given in screen
coordinates, and represent a window client area position corrected by the
scroll bar position. The client area coordinate (0,0) corresponds to the
screen coordinate (ColOrg, RowOrg). The EXTPAINTSTRUC structure contains
the ColOrg and RowOrg members.


3.2.5 Screen Captures

The user can capture the non-Windows application's screen by pressing the
ALT+PRNTSCRN key combination when the application is either full screen or
in a window, or by making a selection and choosing the Copy command when
the application is in a window. WINOLDAP calls the RenderSelection function
to direct the grabber to copy the contents of the current selection to the
clipboard.

To do a screen capture, WINOLDAP first calls the display grabber's
selection functions by specifying a selection rectangle that consists of
the entire screen of the non-Windows application. To the grabber, there is
no difference between a screen capture and a normal selection.


3.3 Standard-Mode Function Reference

The following is an alphabetical listing of the grabber functions used for
standard-mode grabbers.

DisableSave

The DisableSave function disables video-context switching. This function
gives the grabber the chance to remove any hooks installed by the
EnableSave function.


Parameters

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).


Return Value

This function has no return value.


See Also

EnableSave



EnableSave

The EnableSave function enables video-context switching. This function
gives the grabber the chance to install any hooks needed for context
switching.


Parameters

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).


Return Value

This function has no return value.


See Also

DisableSave



GetBlock

The GetBlock function copies a rectangular area of the screen to a
specified buffer.


Parameters

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).

   ES:DI
   Points to a GRABREQUEST structure defining the size and format of the
   block to capture. The structure has the following format:

        GrabRequest struc
            grlpData    dd  ?       ;long pointer to I/O buffer
            grXorg      db  ?       ;x origin (unsigned)
            grYorg      db  ?       ;y origin (unsigned)
            grXext      db  ?       ;x extent (unsigned)
            grYext      db  ?       ;y extent (unsigned)
            grStyle     db  ?       ;style flags
            grChar      db  ?       ;character code for fill operations
            grAttr      db  ?       ;attribute for fill operations
        GrabRequest ends

Return Value

The return value is the number of bytes transferred and is set in the AX
register if successful. The carry flag is cleared as well. Otherwise, the
return value is one of the following error values.

Value                    Meaning
---------------------------------------------------------------------------

ERR_UNSUPPORTED (0FFh)   Block operation not supported.

ERR_BOUNDARY (0FEh)      Source or destination range in error.


Comments

If the grlpData member is NULL, GetBlock returns the number of bytes to
copy without actually copying the bytes.

GetBlock uses only the Format value of the grStyle member. If the Format
value in grStyle is FMT_NATIVE, GetBlock copies the data in the native
screen format for the current video context. Thus, text screens result in
character and attribute pairs being copied, while graphics screens result
in a bitmap. Since the native format is screen dependent, use it for saving
and restoring; don't attempt to interpret the data.

If the Format value is FMT_OTHER, GetBlock copies the data in a variant of
the Windows clipboard format defined by the grabber-buffer structure,
GRABST. This buffer has GT_TEXT type for text screens and GT_NEWBITMAP type
for graphics screens.

GetBlock does not use the grChar and grAttr members.

In text mode, the display adapter may contain multiple character sets or
allow downloadable character sets. The data returned in clipboard format
will be translated to the standard OEM set if it can be determined that
another set is in use, which character set it is, and whether or not a
translation table is available for the job. The EGA is an example of an
adapter that makes it hard to determine that a set has been downloaded and
practically impossible to determine which one it is.



GetInfo

The GetInfo function returns information about the grabber in a GRABINFO
structure.


Parameters

   ES:DI
   Points to the GRABINFO structure to receive the grabber information.

   The structure has the following form:

                          GrabInfo struc
                              giDisplayId     db  ?       ;display ID code
                              giScrType       db  ?       ;specifies the screen type
                              giSizeX         dw  ?       ;x raster size in .1mm units
                              giSizeY         dw  ?       ;y raster size in .1mm units
                              giCharsX        db  ?       ;# x char cells (columns)
                              giCharsY        db  ?       ;# y char cells (rows)
                              giMouseScaleX   db  ?       ;x transform for MS-Mouse
                              giMouseScaleY   db  ?       ;y transform for MS-Mouse
                              giReserved      db  38 dup (?)
                          GrabInfo ends

Return Value

The return value is 0 in the AX register if block operations are not
supported in graphics mode. The return value is 1 if block operations are
not supported in text mode.


Comments

GetInfo fills a GRABINFO structure pointed to by the ES:DI register pair.

Although Windows knows nothing about the reserved members, the grabber can
fill some of the members with the extra data in INFOCONTEXT since it is
convenient for debugging purposes. Because these members are still
reserved, they may change at any time.

The block functions also check the current mode and return the value
ERR_UNSUPPORTED to indicate nonsupport for the request.



GetVersion

The GetVersion function returns the grabber version number.


Parameters

This function has no parameters.


Return Value

The return value is the grabber's version number set in the AX register.



InitScreen

The InitScreen function initializes the screen to text mode, and to the
requested number of lines per screen.


Parameters

   AX
   Specifies the number of lines for the screen. If the number of lines
   requested cannot be supported by the display device, the function rounds
   down to a number that the device can support.

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).


Return Value

This function has no return value.


Comments

Windows calls this function just before a non-Windows application starts as
well as before switching back to Windows. When switching back to Windows,
InitScreen sets the display to a text mode that Windows supports. This
ensures that Windows can correctly display the Windows screen.

Windows switches back to Windows when the non-Windows application
terminates or when the user switches away. If the user switches away,
Windows calls InitScreen after saving the application screen and calling
the DisableSave function.


See Also

DisableSave



InquireGrab

The InquireGrab function either returns the size of the grabber buffer or
it calls an extended function.


Parameters

   AX
   Specifies the action to take. It can contain one of the following
   values.

                      Value      Meaning
                      -----------------------------------------------------

                      1          Returns buffer size for text capture.

                      2          Returns buffer size for graphics capture.

                      3-0FFFFh   Carries out the corresponding extended
                                 function.

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).


Return Value

The return value in the AX:DX register pair is either the buffer size (in
bytes), or the return value depends on the specified extended function
call.


Comments

The InquireGrab (or InquireSave) function is responsible for carrying out
any necessary initializations for the grabber the first time the function
is called. Windows calls either InquireGrab or InquireSave before any other
call to a grabber function (unless the InitScreen function is present).


See Also

InitScreen, InquireSave



InquireSave

The InquireSave function returns the size of the screen save buffer.


Parameters

   AX
   Specifies the action to take. It can contain one of the following
   values.

                      Value   Meaning
                      -----------------------------------------------------

                      1       Returns buffer size for text capture.

                      2       Returns buffer size for graphics capture.

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).


Return Value

The return value in the DX:AX register pair is the specified buffer size
(in bytes).


Comments

The InquireSave (or InquireGrab) function is responsible for carrying out
any necessary initializations for the grabber the first time the function
is called. Windows calls either InquireGrab or InquireSave before any other
call to a grabber function (unless the InitScreen function is present).


See Also

InitScreen, InquireGrab



RestoreScreen

The RestoreScreen function restores a previously saved video context.


Parameters

   AX
   Specifies the size in bytes of the saved video context.

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).

   ES:DI
   Points to the saved video context.


Return Value

The return value is a cleared carry flag if successful. Otherwise, the
carry flag is set to indicate an error.


Comments

Windows guarantees that the offset portion of the saved video context (the
DI register) will always be zero.


See Also

SaveScreen



SaveScreen

The SaveScreen function saves the current video context.


Parameters

   AX
   Specifies the size in bytes of the saved video context.

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).

   ES:DI
   Points to the saved video context.


Return Value

The return value is a cleared carry flag if successful. Otherwise, the
carry flag is set to indicate an error.


Comments

Windows guarantees that the offset portion of the screen save area (the DI
register) will always be zero.


See Also

RestoreScreen



SetSwapDrive

The SetSwapDrive function uses the current swap drive and path.


Parameters

   BL
   Specifies the ASCII drive letter for the swap drive (such as A, B, or
   C). This register contains 0FFh if no swap drive is available.

   DS
   Specifies the segment address of the grabber (CS and DS registers are
   equal).

   ES:DI
   Points to the path template for Windows temporary-file format.


Return Value

This function has no return value.


Comments

The next call to the following SaveScreen function uses the given swap
drive letter to open the swap file, if needed. Failure to call this
function at least once before SaveScreen may result in a failure to switch
the video context. This drive and path information is stored as a static
value and need not be set before every call to SaveScreen.


See Also

SaveScreen


3.4 Standard-Mode Structure Reference

The following is an alphabetical listing of the grabber structures used for
standard-mode grabbers.



DEVICECONTEXT

The DEVICECONTEXT structure is a device-dependent structure internal to
grabbers. Its layout, content, and length will vary from grabber to
grabber.

The following is the DEVICECONTEXT structure for the grabbers for Hercules
adapters:

    DeviceContext struc
        dcScrMode       db  ?   ;BIOS screen mode
        dcScrStart      dw  ?   ;regeneration of start position
        dcCursorPosn    dw  ?   ;cursor position in CRTC format
        dcCursorMode    dw  ?   ;cursor start/stop scan lines
        dcModeCtl       db  ?   ;3x8 mode register data
        dcExModeCtl     db  ?   ;3xx extended-mode register data
        dcColorSelect   db  ?   ;3D9 color select register data
        dcCrtcParms     dw  ?   ;-> CRTC parameters for non-BIOS modes
        dcfSwitchGmt    db  ?   ;switch graphics/multiple text
    DeviceContext ends
The following is the DEVICECONTEXT structure for EGA grabbers:

    DeviceContext struc
        dcScrMode       db  ?           ;BIOS screen mode
        dcScrStart      dw  ?           ;regeneration of start position
        dcCursorPosn    dw  ?           ;cursor position in CRTC format
        dcCursorMode    dw  ?           ;cursor start/stop scan lines
        dcAddrPatch     db  ?           ;3Dx / 3Bx patch byte
        dcfSwitchGmt    db  ?           ;switch graphics/multiple text
        dcFileNum       dw  ?           ;-> random number in swap file
        dcFontBank      db  4  dup (?)  ;ERI font information
        dcSwapPath      db  64 dup (?)  ;full swap path
    DeviceContext ends
The following is the DEVICECONTEXT structure for VGA grabbers:

    DeviceContext   struc
        dcScrMode       db  ?           ;BIOS screen mode
        dcScrStart      dw  ?           ;regeneration of start position
        dcCursorPosn    dw  ?           ;cursor position in CRTC format
        dcCursorMode    dw  ?           ;cursor start/stop scan lines
        dcAddrPatch     db  ?           ;3Dx / 3Bx patch byte
        dcfSwitchGmt    db  ?           ;switch graphics/multiple text
        dcFileNum       dw  ?           ;-> random number in swap file
        dcFontBank      db  8  dup (?)  ;VGA has 8 font banks
        dcSwapPath      db  64 dup (?)  ;full swap path
    DeviceContext   ends


GRABINFO

    GrabInfo struc
        giDisplayId     db  ?       ;display ID code
        giScrType       db  ?       ;specifies the screen type
        giSizeX         dw  ?       ;x raster size in .1mm units
        giSizeY         dw  ?       ;y raster size in .1mm units
        giCharsX        db  ?       ;# x char cells (columns)
        giCharsY        db  ?       ;# y char cells (rows)
        giMouseScaleX   db  ?       ;x transform for MS-Mouse
        giMouseScaleY   db  ?       ;y transform for MS-Mouse
        giReserved      db  38 dup (?)
    GrabInfo ends
The GRABINFO structure contains the current video-context information.


Members

   giDisplayId
   Specifies the display-identifier code.

   giScrType
   Specifies the screen type. It can be one of the following values.

                      Value               Meaning
                      -----------------------------------------------------

                      ST_TEXT (00h)       Screen is alphanumeric.

                      ST_GRPH (01h)       Screen is graphics.

                      ST_LARGE (02h)      Screen is high-resolution
                                          graphics.

                      ST_SPECGRAB (04h)   Reserved; do not use.

   giSizeX
   Specifies the x-raster size in 0.1 millimeter units.

   giSizeY
   Specifies the y-raster size in 0.1 millimeter units.

   giCharsX
   Specifies the number of characters cells in a row.

   giCharsY
   Specifies the number of characters cells in a column.

   giMouseScaleX
   Specifies the x-transform for the Microsoft Mouse(R).

   giMouseScaleY
   Specifies the y-transform for the Microsoft Mouse.

   giReserved
   Reserved; do not use.


See Also

GetInfo



GRABREQUEST

    GrabRequest struc
        grlpData    dd  ?       ;long pointer to I/O buffer
        grXorg      db  ?       ;x origin (unsigned)
        grYorg      db  ?       ;y origin (unsigned)
        grXext      db  ?       ;x extent (unsigned)
        grYext      db  ?       ;y extent (unsigned)
        grStyle     db  ?       ;style flags
        grChar      db  ?       ;character code for fill operations
        grAttr      db  ?       ;attribute for fill operations
    GrabRequest ends
The GRABREQUEST structure contains information used to capture all or a
portion of the screen.


Members

   grlpData
   Contains the address of the buffer to receive or containing the screen
   data.

   grXorg
   Specifies the x-origin (unsigned) of the upper-left corner of the block.

   grYorg
   Specifies the y-origin (unsigned) of the upper-left corner of the block.

   grXext
   Specifies the x-extent of the block. If grXext is zero, the entire
   screen width is assumed.

   grYext
   Specifies the y-extent of the block. If grYext is zero, the entire
   screen height is assumed.

   grStyle
   Specifies the type and format of the block operation. It can be a
   combination of one Screen Operation and one Format value. The following
   are the values for the Screen Operation.

                      Value                 Screen Operation
                      -----------------------------------------------------

                      F_BOTH (00h)          Fills with single character and
                                            attribute.

                      F_CHAR (01h)          Fills with single character
                                            only.

                      F_ATTR (02h)          Fills with single attribute
                                            only.

                      C_BOTH (03h)          Copies characters and
                                            attributes from grlpData.

                      C_CHAR (04h)          Copies characters only from
                                            grlpData.

                      C_ATTR (05h)          Copies attributes only from
                                            grlpData.

                      C_CHAR_F_ATTR (06h)   Copies characters from grlpData
                                            and fills with single attribute.

                      C_ATTR_F_CHAR (07h)   Copies attributes from grlpData
                                            and fills with single character.

   The following are the values for Format.
                      Value              Format
                      -----------------------------------------------------

                      FMT_NATIVE (00h)   Uses format native to mode.

                      FMT_OTHER (80h)    Uses clipboard format or format
                                         specified by the Screen Operation
                                         value.

   grChar
   Specifies a character code for fill operations.

   grAttr
   Specifies an attribute byte for fill operations.


Comments

All block functions receive a pointer to a GRABREQUEST structure in the
ES:DI register pair. Not all the members are used by all functions.


See Also

GetBlock



GRABST

    GrabSt struc
        gbType      dw ?       ;specifies format for grabber operation
        gbSize      dw ?       ;length (not including first 4 bytes)
        gbWidth     dw ?       ;width of bitmap in pixels
        gbHeight    dw ?       ;height of bitmap in raster lines
        gbPlanes    dw ?       ;# of color planes in the bitmap
        gbPixel     dw ?       ;# of adjacent color bits on each plane
        gbWidth2    dw ?       ;width of bitmap in 0.1 mm units
        gbHeigh2    dw ?       ;height of bitmap in 0.1 mm units
        gbBits      dw ?       ;the actual bits
    GrabSt ends
The GRABST structure contains information used by the grabber to copy the
proper format to the grab buffer.


Members

   gbType
   Specifies the format for the operation. It can be one of the following
   values.

                      Value              Meaning
                      -----------------------------------------------------

                      GT_TEXT (1)        ANSI or OEM text.

                      GT_OLDBITMAP (2)   Windows bitmap format (version
                                         2.x).

                      GT_NEWBITMAP (3)   Windows bitmap format (version
                                         3.x).

                      GT_RESERVED4 (4)   Reserved; do not use.

                      GT_RESERVED5 (5)   Reserved; do not use.

   gbSize
   Specifies the length of the structure, not including first 4 bytes.

   gbWidth
   Specifies the width of the bitmap in pixels.

   gbHeight
   Specifies the height of the bitmap in raster lines.

   gbPlanes
   Specifies the number of color planes in the bitmap.

   gbPixel
   Specifies the number of adjacent color bits on each plane.

   gbWidth2
   Specifies the width of the bitmap in 0.1 millimeter units.

   gbHeigh2
   Specifies the height of the bitmap in 0.1 millimeter units.

   gbBits
   Contains the actual bitmap data.


See Also

GetBlock



INFOCONTEXT

    InfoContext struc
        icDisplayId    db  ?  ;display ID code
        icScrType      db  ?  ;screen type code
        icSizeX        dw  ?  ;horizontal raster size in .1mm units
        icSizeY        dw  ?  ;vertical raster size in .1mm units
        icCharsX       db  ?  ;number of character columns
        icCharsY       db  ?  ;number of character rows
        icMouseScaleX  db  ?  ;mouse to grabber coordinate transform in x
        icMouseScaleY  db  ?  ;mouse to grabber coordinate transform in y
        icPixelsX      dw  ?  ;number of pixels in x
        icPixelsY      dw  ?  ;number of pixels in y
        icWidthBytes   dw  ?  ;width in bytes of a row/scan line
        icBitsPixel    db  ?  ;number of adjacent bits/pixel
        icPlanes       db  ?  ;number of planes per pixel
        icInterlaceS   db  ?  ;interlace-shift factor
        icInterlaceM   db  ?  ;interlace-mask factor
        iclpScr        dd  ?  ;long pointer to screen
        icScrLen       dw  ?  ;current screen-page length
    InfoContext ends
The INFOCONTEXT structure is a global structure shared by all the grabbers
and may be considered the non-Windows application version of the GDIINFO
structure for Windows drivers.


Members

   icDisplayId
   Specifies the display ID code.

   icScrType
   Specifies the screen-type code.

   icSizeX
   Specifies the horizontal raster size in .1 millimeter units.

   icSizeY
   Specifies the vertical raster size in .1 millimeter units.

   icCharsX
   Specifies the number of character columns.

   icCharsY
   Specifies the number of character rows.

   icMouseScaleX
   Specifies the mouse-to-grabber coordinate transform in x.

   icMouseScaleY
   Specifies the mouse-to-grabber coordinate transform in y.

   icPixelsX
   Specifies the number of pixels in x.

   icPixelsY
   Specifies the number of pixels in y.

   icWidthBytes
   Specifies the width in bytes of a row per scan line.

   icBitsPixel
   Specifies the number of adjacent bits per pixel.

   icPlanes
   Specifies the number of planes per pixel.

   icInterlaceS
   Specifies the interlace-shift factor.

   icInterlaceM
   Specifies the interlace-mask factor.

   iclpScr
   Contains the address of the screen.

   icScrLen
   Specifies the current screen-page length.


Comments

INFOCONTEXT is essentially a superset of the GRABINFO structure returned by
the GetInfo entry point. GRABINFO has sufficient reserved space so that
this information may be made available to the Windows layer in the future
as well as allow for more members being added if needed.


See Also

GetInfo


3.5 386 Enhanced-Mode Function Reference

The following is an alphabetical listing of the grabber functions used for
386 enhanced-mode grabbers.



AdjustInitEndPt

    POINT AdjustInitEndPt(lpPntStruct, Y, X)
    LPEXTPAINTSTRUC lpPntStruct;
    WORD Y;
    WORD X;

The AdjustInitEndPt function adjusts the initial-selection end point.


Parameters

   lpPntStruct
   Points to an EXTPAINTSTRUC structure.

   Y
   Specifies the y-coordinate of the point to be adjusted.

   X
   Specifies the x-coordinate of the point to be adjusted.


Return Value

The return value is a POINT structure containing the end point adjusted
down and to right for initial selection.


Comment

The export ordinal for this function is 17.

Initially, the start point and the end point are the same. When the user
extends the selection by pressing a SHIFT+arrow key combination, WINOLDAP
calls the AdjustInitEndPt function to ensure that the selection rectangle
is not empty but encloses at least one character.


See Also

BeginSelection



BeginSelection

    void BeginSelection(lpPntStruct, Y, X)
    LPEXTPAINTSTRUC lpPntStruct;
    WORD Y;
    WORD X;

The BeginSelection function starts the selection at the indicated point by
setting the display and selection rectangles in the EXTPAINTSTRUC
structure.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   Y
   Specifies the y-coordinate of the point to be set.

   X
   Specifies the x-coordinate of the point to be set.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 3.

The function sets the SelectSRect and GrabArea members of the SelStruc
member in the EXTPAINTSTRUC structure, making the start and end points for
the selection and display rectangles the same. The function also sets the
SELECTON bit in the SelecFlags member of the GrabArea member of the
SelStruc member of the EXTPAINTSTRUC structure.


See Also

AdjustInitEndPt, EndSelection



CheckGRBVersion

    DWORD CheckGRBVersion(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The CheckGRBVersion function checks the virtual-display device (VDD)
version.


Parameter

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

The return value specifies whether the VDD version is compatible. It can be
one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       VDD is compatible.

1       Version number error.

2       Display-type mismatch. The VDD and grabber are not compatible. In
        this case, the high-order 16 bits is the grabber version number.


Comments

The export ordinal for this function is 16.



ConsSelecRec

    void ConsSelecRec(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The ConsSelecRec function makes the display rectangle consistent with the
selection rectangle.


Parameter

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 8.

The function sets the SelctSRect member of the SelStruc member in the
EXTPAINTSTRUC structure to the values specified as start and end points in
the GrabArea member of the SelStruc member.



CursorOff

    void CursorOff(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The CursorOff function destroys the cursor for an application.


Parameter

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 15.


See Also

CursorOn



CursorOn

    void CursorOn(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The CursorOn function creates the cursor for an application if it has one.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 13.


See Also

CursorOff



CursorPosit

    POINT CursorPosit(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The CursorPosit function returns the position of the cursor on the display.


Parameter

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

The return value is the x- and y-coordinates of the upper-left corner of
the cursor. The function returns -1 if there is no cursor.


Comments

The export ordinal for this function is 14.



EndSelection

    void EndSelection(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The EndSelection function stops the selection.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 9.

The function clears the SELECTON bit in the SelecFlags member of the
GrabArea member of the SelStruc member of the EXTPAINTSTRUC structure.


See Also

BeginSelection



GetDisplayUpd

    WORD GetDisplayUpd(lpPntStruc, wParam, lParam)
    LPEXTPAINTSTRUC lpPntStruc;
    WORD wParam;
    DWORD lParam;

The GetDisplayUpd function calls the virtual-display device (VDD) to get a
display update (if any) and stores it in the PAINT structure.

It prevents any further changes from occurring in or to the application.
The application restarts after a call to one of the following functions:
UpdateScreen, PaintScreen, or GrbUnLockApp.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   wParam
   Specifies the 16-bit message parameter. It is -1 if WINOLDAP origin.

   lParam
   Specifies the 32-bit message parameter. It is 0 if WINOLDAP origin.


Return Value

The return value is a display update flag. It can be a combination of the
following values.

Value                   Meaning
---------------------------------------------------------------------------

fDisp_Ctlr (8)          Indicates controller-state change.

fDisp_VRAM (16)         Indicates video RAM change.

fDisp_Curs (32)         Indicates cursor change.

fDisp_HCurTrack (128)   Horizontal cursor track is required.


Comments

The export ordinal for this function is 18.

This function locks the application (prevents further changes from
occurring). The application can be started again by calling the
UpdateScreen, PaintScreen, or GrbUnLockApp functions.


See Also

GrbUnLockApp, PaintScreen, UpdateScreen



GetFontList

    void GetFontList(lpFontBuf)
    LPSTR lpFontBuf;

The GetFontList function returns a pointer to the list of extra fonts.


Parameters

   lpFontBuf
   Points to a buffer to receive font information.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 12.



GrabComplete

    void GrabComplete(lpPntStruc, wParam, lParam)
    LPEXTPAINTSTRUC lpPntStruc;
    WORD wParam;
    DWORD lParam;

The GrabComplete function signals the completion of the screen capture. The
function should call the virtual-display device (VDD) to free the grabber
memory.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   wParam
   Specifies the 16-bit message parameter. It is -1 if WINOLDAP origin.

   lParam
   Specifies the 32-bit message parameter. It is an event identifier.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 20.



GrabEvent

    void GrabEvent(lpPntStruc,wParam,lParam)
    LPEXTPAINTSTRUC lpPntStruc;
    WORD wParam;
    DWORD lParam;

The GrabEvent function provides a private channel of event communication
between the virtual-display device and the grabber to respond to an
ALT+PRNTSCRN key combination to perform a screen capture.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   wParam
   Specifies the 16-bit message parameter.

   lParam
   Specifies the 32-bit message parameter. It is an event identifier.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 19.



GrbUnLockApp

    void GrbUnLockApp(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The GrbUnLockApp function cancels the implied application lock of
GetDisplayUpd.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 22.


See Also

GetDisplayUpd



InvertSelection

    POINT InvertSelection(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The InvertSelection function inverts the selection.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

The return value is a POINT structure specifying the x- and y-coordinates
of the active selection end point.


Comments

The export ordinal for this function is 6.

The function ensures that subsequent output to the screen within the
selection rectangle is inverted.



KeySelection

    POINT KeySelection(lpPntStruc, StartType, Mfunc)
    LPEXTPAINTSTRUC lpPntStruc;
    WORD StartType;
    WORD Mfunc;

The KeySelection function moves the start or end point of the selection
rectangle and returns that point's new location.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   StartType
   Specifies whether the SHIFT key is up or down. The StartType parameter
   is zero if the key is up, and nonzero if the key down.

   Mfunc
   Specifies the direction to move the selection point. This parameter can
   be one of the following values.

                     Value   Meaning
                     ------------------------------------------------------

                     0       Move right.

                     1       Move left.

                     2       Move down.

                     3       Move up.


Return Value

The return value is a POINT structure containing the x- and y-coordinates
of the new selection start or end point.


Comments

The export ordinal for this function is 4.

WINOLDAP calls the KeySelection function whenever the user presses an arrow
key or a SHIFT+arrow key combination. If an arrow key is pressed, the
function moves the current start point left, right, up, or down as
specified by the Mfunc parameter. If a SHIFT+arrow key combination is
pressed, the function moves the current end point in the specified
direction.

The amount the function moves the point depends on the display mode. In
text mode, the function moves by the width and height of the current font.
In graphics mode, the function moves by a width and height that is
reasonable for the given display.

KeySelection does not update the EXTPAINTSTRUC structure. Instead, WINOLDAP
calls either the BeginSelection or MakeSelctRect function and passes it the
new point.


See Also

BeginSelection, MakeSelctRect



MakeSelctRect

    WORD MakeSelctRect(lpPntStruc, Y, X)
    LPEXTPAINTSTRUC lpPntStruc;
    WORD Y;
    WORD X;

The MakeSelctRect function sets a new selection. It is called after every
call to KeySelection in response to SHIFT+arrow key. Given a new end point,
it adjusts the new end point to be character aligned in text mode (and on a
convenient boundary in the video memory in graphics mode). It also adjusts
for maximum width and height of the screen. It sets the selection rectangle
based on the current start point and end point.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   Y
   Specifies the y-coordinate of the new end point.

   X
   Specifies the x-coordinate of the new end point.


Return Value

The return value is zero if no change was made to selection parameters. The
SelctSRect member of the SelStruc member must still be set in this case.


Comments

The export ordinal for this function is 5.

The function sets the SelctSRect member of the SelStruc member.


See Also

KeySelection



PaintScreen

    WORD PaintScreen(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The PaintScreen function paints the indicated region of the screen.

WINOLDAP calls this function when it receives the WM_PAINT message.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

The return value is a nonzero value if the function paints the screen if
successful. Otherwise, the return values is zero, possibly indicating that
there was not enough Windows memory to carry out the request.


Comments

The export ordinal for this function is 1.



RenderSelection

    DWORD RenderSelection(lpPntStruc, wParam, lParam)
    LPEXTPAINTSTRUC lpPntStruc;
    WORD wParam;
    DWORD lParam;

The RenderSelection function transforms the selection into the clipboard
format.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   wParam
   Specifies the 16-bit message parameter. It is -1 if WINOLDAP origin.

   lParam
   Specifies the 32-bit message parameter. It is zero if WINOLDAP origin.


Return Value

The return value is a 32-bit value that specifies the clipboard format and
the handle for the rendered selection. The high-order 16 bits specifies the
clipboard format used (either CF_OEMTEXT or CF_BITMAP). The low-order 16
bits is a memory or bitmap handle, depending on the clipboard format.

The return value is zero in the high-order 16 bits if there is no
selection. The return value is a negative value in the high-order 16 bits
if the function could not transform the selection.


Comments

The export ordinal for this function is 7.



ScreenFree

    void ScreenFree(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The ScreenFree function frees anything associated with this application.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 2.



SetPaintFnt

    void SetPaintFnt(lpPntStruc, lpWidFullScr, lpHeightFullScr)
    LPEXTPAINTSTRUC lpPntStruc;
    LPINT lpWidFullScr;
    LPINT lpHeightFullScr;

The SetPaintFnt function sets the font for painting so that WINOLDAP can
compute the paint rectangle for use on calls to the PaintScreen function.
This function is called right before a call to PaintScreen. It is also
called before a call to the UpdateScreen function.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.

   lpWidFullScr
   Points to a 16-bit buffer that receives the full screen width. The width
   is in pixels for graphics mode and in characters for text mode.

   lpHeightFullScr
   Points to a 16-bit buffer that receives the full screen height. The
   height is in scan lines for graphics mode and in text lines for text
   mode.


Return Value

The return value specifies the value of the height and width of the full
screen. The high-order 16 bits specifies the height in scan lines for
graphics mode and in text lines for text mode. The low-order 16 bits
specifies the width in pixels for graphics mode and in characters for text
mode.


Comments

The export ordinal for this function is 11.

This function sets the FntHgt and FntWid members in the EXTPAINTSTRUC to
the width and height of the font. The function sets these members to zero
if the display mode is graphics.


See Also

PaintScreen, UpdateScreen



UpdateScreen

    WORD UpdateScreen(lpPntStruc)
    LPEXTPAINTSTRUC lpPntStruc;

The UpdateScreen function updates changed portions of the screen. When a
non-Windows application modifies the display on its own, UpdateScreen is
called.


Parameters

   lpPntStruc
   Points to an EXTPAINTSTRUC structure.


Return Value

The return value is 1 if the function paints the screen, unless the
FGRBPROB bit is set in EPStatusFlags member. The return value is zero if
the function cannot paint the screen, such as when Windows does not have
enough memory to carry out the request.


Comments

The export ordinal for this function is 12.


3.6 386 Enhanced-Mode Structure Reference

The following is an alphabetical listing of the grabber structures used for
386 enhanced-mode grabbers.



EXTPAINTSTRUC

    typedef struct tagEXTPAINTSTRUCT {
        PAINTSTRUCT     Pstruct;
        RECT            PGVDRect;
        WORD            HScrlPos;
        WORD            VScrlPos;
        WORD            ColOrg;
        WORD            RowOrg;
        DWORD           VM1_Hnd;
        PNTFONTSTRUC    DefFont;
        PNTFONTSTRUC    AltFnt1;
        PNTFONTSTRUC    AltFnt2;
        PNTFONTSTRUC    AltFnt3;
        PNTFONTSTRUC    AltFnt4;
        PNTFONTSTRUC    AltFnt5;
        PNTFONTSTRUC    AltFnt6;
        WORD            WhtBrshH;
        WORD            BlkBrshH;
        WORD            RNG1DSSEL;
        DWORD           ShellCall;
        BYTE            GGrbArea[GLOBALGRBSIZEMAX];
        RECT            PTVDRect;
        WORD            TDXpos;
        WORD            TDYpos;
        WORD            FntHgt;
        WORD            FntWid;
        DWORD           ThisVMHand;
        WORD            WindHand;
        WORD            BoxPrntHand;
        WORD            hThisInst;
        TTYSelect       SelStruc;
        BYTE            EPDispMod[VDD_MOD_MAX];
        BYTE            EPGrabDTA[VDD_CTRL_STATE_MAX];
        DWORD           EPStatusFlags;
        BYTE            VerStrng[8];
    } EXTPAINTSTRUCT;
The EXTPAINTSTRUC structure contains information about the state of the
display, including display modes and selection rectangles.

Chapter 4  Printer Drivers

The Microsoft Windows printer drivers manage all printer output for Windows
applications. Each driver provides a set of functions that Windows uses to
initialize the printer, retrieve information about the printer, print text
and graphics, and allow users to modify the operation of the printer.


4.1 About the Printer Driver

A printer driver is a dynamic-link library (DLL) that consists of a set of
graphics functions for a particular printer device. These graphics
functions translate device-independent graphics commands into a stream of
device-dependent commands and data. A printer driver receives the graphics
commands from the graphics-device interface (GDI) portion of Windows and
sends device commands either directly or indirectly to the printer.

Each printer driver supports a specific printer technology. Printer
technologies include raster devices (for example, dot-matrix printers) and
vector devices (for example, plotters), and devices with higher-level
languages, such as PostScript page-description language (PDL). However, a
printer driver can support any number of models and manufacturers as long
as the printers share the same basic technology.

Unlike most Windows device drivers, a printer driver is generally not
responsible for hardware communication with the printer. Instead, the
driver uses existing Windows functions to open and write to a printing
queue, to a file on disk, or directly to the printer through a
communications port.


4.1.1 Printer-Driver Initialization

Printer-driver initialization occurs whenever Windows or a Windows
application loads the printer driver using the LoadLibrary function
(KERNEL.95). Windows loads a printer driver whenever an application uses
the CreateDC function (GDI.53) to create a device context for the printer.
Windows applications load the driver to prepare for subsequent calls to the
printer driver's DeviceMode, ExtDeviceMode, or DeviceCapabilities function.

As with other dynamic-link libraries, Windows calls the printer driver's
initialization routine (if any) when it loads the driver. The routines of
most drivers do little more than initialize the heap and load resources,
such as the name of the driver's Help file. Although a driver may require
additional initialization, it typically waits until GDI provides the
additional information needed for this initialization when it calls the
driver's Enable function.

If a printer driver allocates global resources or alters the state of the
system, the driver is responsible for freeing these resources and restoring
the previous state before the driver terminates. Because every driver
includes a WEP function that Windows calls as the driver is quitting, the
printer driver can use this function to free resources and restore the
system.


4.1.2 GDI Information Structure

Every printer driver must have a GDIINFO structure that specifies the
printer's capabilities and characteristics. GDI uses this information to
determine what the printer can do and how much GDI must do to support
graphics output to the printer. The GDI information can be classified as
follows:

o   Driver management

o   Driver capabilities

o   Device dimensions

The driver-management information specifies the version of Windows for
which the driver was written, the type of technology the printer uses to
generate output, the size in bytes of the printer's PDEVICE structure, and
number of device contexts the driver can manage at the same time.

The driver-capabilities information specifies the capabilities of the
device, such as whether the printer can draw polygons and ellipses, scale
text, and clip output. Driver capabilities also specify the number of
device brushes, pens, fonts, and colors available on the printer and
whether the printer can handle bitmaps and color palettes.

The device-dimension information specifies the maximum width and height of
the printable area in both millimeters and device units, the number of
color bits or planes, the aspect ratio, the minimum length of a dot in a
styled line, and the number of device units or pixels per inch.


4.1.3 Enabling and Disabling Physical Devices

GDI enables operation of the printer driver by calling the driver's Enable
function and directing the driver to initialize a physical device for
subsequent graphics output. A physical device is a PDEVICE structure that
represents a printer and its current operating state. A printer driver uses
the physical-device information to determine how to carry out specific
tasks, such as which device-dependent graphics commands to use, and which
output port to send the commands. The printer driver initializes the
physical device by copying information to the PDEVICE structure.

GDI calls the Enable function whenever an application calls the CreateDC
function (GDI.53) to create a device context (DC) for the printer. GDI
calls the function twice: once to retrieve a copy of the driver's GDIINFO
structure, and a second time to initialize the PDEVICE structure. After the
first call, GDI uses the dpDEVICEsize member in the GDIINFO structure to
determine the size of the driver's PDEVICE structure. GDI then allocates
memory for the structure and calls Enable for the second time, passing a
pointer to the structure. With this call, the driver initializes the
structure.

To initialize the PDEVICE structure, the driver typically examines the
names of the printer model and output device or file passed to Enable by
GDI. It may also examine any printer environment passed to Enable. The
driver then fills the PDEVICE structure with all the information that the
output functions need to generate appropriate graphics commands for the
given printer model and to send the commands to the given device or file.

Although only the printer driver initializes and uses the PDEVICE
structure, GDI allocates memory for the structure, determines when to pass
it to the driver's output functions, and deletes the structure when it is
no longer needed. Except for the first 16 bits of the PDEVICE structure,
the content and format of the structure depends entirely on the printer
driver. The first 16 bits, on the other hand, must be set to a nonzero
value. GDI reserves zero to indicate a BITMAP structure. GDI creates and
uses a BITMAP structure in place of a PDEVICE structure when an application
creates a memory-device context.

A printer driver can allocate additional structures and store their
addresses in the PDEVICE structure. Because GDI may direct a printer driver
to create a large number of physical devices, the printer driver should not
allocate additional structures in the limited space of the driver's
automatic data segment, especially if the driver allows multiple device
contexts.

GDI disables the physical device and possibly frees the printer driver
whenever an application calls the DeleteDC function (GDI.68). GDI disables
the physical device by calling the driver's Disable function. It expects
the driver to complete any outstanding printing job and free any resources
associated with the physical device. After the driver returns from the
Disable function, GDI frees the memory it allocated for the PDEVICE
structure. If there are no other device contexts for this printer driver,
Windows frees the driver, removing any driver code and data from memory.


4.1.4 Device-Context Management

Since Windows is a multitasking environment, more than one application may
create a device context for a printer at the same time. This means GDI may
direct the printer driver to initialize more than one physical device. The
printer driver sets the dpDCManage member in its GDIINFO structure to
specify how it will manage these requests. The driver can specify one of
the following methods:

o   Driver allows multiple device contexts. It creates a new PDEVICE for
    each device context that specifies a new device and filename pair, but
    uses the same PDEVICE for any subsequent device contexts that specify
    the same device and filename pair.

o   Driver allows multiple device contexts, but it creates a new PDEVICE
    for each device context regardless of whether the device and filename
    pairs are the same.

o   Driver allows multiple device contexts but only if all device contexts
    have unique device and filename pairs. The driver creates a PDEVICE for
    each device context. The driver returns an error on any attempt to
    create a second device context with an existing device and filename
    pair.

o   Driver allows multiple device contexts, but only creates one PDEVICE.
    All device contexts share the same PDEVICE regardless of the device and
    filename pairs.

o   Driver allows only one device context. The driver returns an error on
    any attempt to create a second device context.

Printer drivers normally allow multiple device contexts but create new
PDEVICE structures for each device context. With separate PDEVICE
structures, the driver can maintain information about multiple print jobs
without one job affecting the other.


4.1.5 Dimensions and Mapping Modes

A printer driver provides values in its GDIINFO structure specifying the
aspect ratio, logical pixels-per-inch, and mapping modes for the printer.
The following sections detail these modes.


4.1.5.1 Aspect Ratio

The aspect ratio defines the relative dimensions of the printer's pixels.
The ratio consists of three values: an x-, y-, and xy-aspect. These
represent the relative width, height, and diagonal length (or hypotenuse)
of a pixel. GDI uses the aspect ratio to determine how to draw squares and
circles as well as drawing lines at an angle.

The aspect values have the following relationship:

    (dpAspectXY * dpAspectXY) == (dpAspectX * dpAspectX) +
    (dpAspectY * dpAspectY)
Because the dimensions are given as relative values, they may be scaled as
needed to obtain accurate integer values. Keep the values under 1000 for
numerical stability in GDI calculations. For example, a device with a 1:1
aspect ratio (such as a 300 dpi laser printer) can use 100 for the
dpAspectX member and the dpAspectY member and 141 (100 * 1.41421...) for
dpAspectXY.


4.1.5.2 Logical Pixels-Per-Inch

Printer drivers should always use real inches. A 300 dpi laser printer puts
300 in both members.


4.1.5.3 Mapping Modes

The printer driver provides viewport and window extents for the standard
mapping modes: MM_LOENGLISH, MM_HIENGLISH, MM_LOMETRIC, MM_HIMETRIC, and
MM_TWIPS.

Place the device resolution in pixels-per-inch in the viewport extents and
the number of logical units-per-inch in the window extent. The y-coordinate
of the viewport is negated to reflect the fact that the x-axis is along the
top of the paper in the default mapping mode (MM_TEXT, which specifies
device coordinates) with y increasing while going down the page; whereas in
the other mapping modes, the x-axis is along the bottom edge of the page.

For example, on a 300 dpi laser printer, the MM_TWIPS mapping mode will
require that the dpTwpWin member be set to (1440,1440) and the dpTwpVpt
member be set to (300, -300).


4.1.6 Printer-Driver Environment

The printer-driver environment consists of information about the printer,
such as font cartridges, paper trays and sizes, printer orientation,
graphics capabilities, color, and other advanced features. Windows
applications use this information to create printed output that takes full
advantage of the printer environment.

Printers normally have a large number of options from which the user can
select. This information can come from any of four sources:

o   The driver's default setup.

o   The driver's WIN.INI section of user options. The WIN.INI should
    maintain at least one such section so that modified printer setups can
    be retained from session to session. This information is edited by the
    driver's Setup dialog box.

o   The driver may call GDI to retain the driver's environment from device
    context to device context on a port-by-port basis. This allows faster
    initialization of the driver and avoids the time-consuming process of
    reading options from the WIN.INI file.

o   The application can pass the environment to the driver in a buffer
    pointed to by the lpInitData parameter of the Enable function.

Upon device initialization (that is, during the pair of Enable functions),
this information is used to set up information in the GDIINFO and PDEVICE
structures. For example, the paper size selection will affect the height
and width fields. Also, a printer that allows multiple graphics densities
will modify the various resolution fields.


4.1.7 Device-Mode Dialog Boxes

The DEVMODE structure is used for the environment and the initialization
data (which are the same). By convention, all drivers place the device name
in the first 32 bytes of DEVMODE as a null-terminated string. All the other
data is device dependent.

For Windows 3.x, a new convention has been adopted that defines an
additional number of members. These members enable the application to
perform device-independent manipulations of the device environment.

When Enable is called, the device driver should first check the lpInitData
parameter to see if the application has supplied valid initialization data.
If it is valid, then the driver should use that environment to initialize
the GDIINFO and PDEVICE structures and not use or modify the default
environment information.

If the environment cannot be found or if the data obtained is invalid or
intended for another device, the device driver should extract user settings
from the WIN.INI file, by using the profile string functions, such as
GetProfileInt.

However, the driver should contain useful defaults for all strings, so that
it can create a valid environment even if the WIN.INI file is empty.

The driver should use the device name string at the beginning of the
DEVMODE structure to determine whether or not the environment obtained from
GetEnvironment is correct.

A driver may also maintain additional information in its DEVMODE structure
to determine validity if the device name matches one the driver supports.

The printer driver can set or delete the environment by using the
SetEnvironment function (GDI.132). It can retrieve the current environment
using the GetEnvironment function (GDI.133).

The driver should always set up the default environment if it is not
present, except when the driver is initialized with a non-default
environment (that is, the lpInitData parameter to Enable points to
application-supplied data).


4.1.7.1 New Members in the DEVMODE Structure

The dmYResolution and dmTTOption members in the DEVMODE structure are new
for Windows 3.1. The DEVMODE structure returned by the ExtDeviceMode
function contains one or both of these members if the dmField member
includes the following values:

    DM_YRESOLUTION  0x0002000L
    DM_TTOPTION     0x0004000L
The dmYResolution member specifies the vertical resolution of the printer
in dots per inch. In this case, the dmPrintQuality member specifies the
horizontal resolution in dots per inch. If the DM_YRESOLUTION bit is not
set in dmFields, dmYResolution is not used and dmPrintQuality retains the
original meaning.

The dmTTOption member specifies how TrueType fonts should be printed. The
member can be set to one of the following values.

Value               Meaning
---------------------------------------------------------------------------

DMTT_BITMAP (1)     Prints TrueType fonts as graphics.

DMTT_DOWNLOAD (2)   Downloads TrueType fonts as soft fonts.

DMTT_SUBDEV (3)     Substitutes device fonts for TrueType.

NOTE  Before calling the the CreateDC or CreateIC functions, an application
should call the DeviceCapabilities function with the DC_TRUETYPE index to
retrieve the driver's TrueType capabilities. The application can use the
value returned by the driver to set the dmTTOption member to the
appropriate value.

The default action is to download TrueType as soft fonts for
Hewlett-Packard printers that use PCL; substitute device fonts for TrueType
for PostScript printers; and to print TrueType fonts as graphics for
dot-matrix printers.


4.1.8 Printer-Device Modes

All printer drivers are required to export the DeviceMode function, which
displays a dialog box to edit the default environment. This function sets
the profile strings in the WIN.INI file for the options chosen by the user.
It should also set the environment using the SetEnvironment function. The
DeviceMode function uses USER functions, such as DialogBox (USER.240), to
display dialog boxes.

The most common way to call DeviceMode is with Control Panel. However,
other applications that make heavy use of printer output, such as Microsoft
Write or Microsoft Excel, may also provide a means for calling the printer
driver's DeviceMode function.

Windows 3.x drivers also export two environment-related functions,
ExtDeviceMode and DeviceCapabilities. These functions are designed to allow
greater application control over the printer environment. All printer
drivers should implement these functions.

ExtDeviceMode enables the application to call the driver to obtain device
initialization data either from the user or from the application's
modifications to the default environment. GDI then calls the Enable
function with a pointer to this information, allowing the driver to preset
its GDIINFO and PDEVICE structures according to the application's options,
rather than the defaults. That way, the application can store different
printer settings for itself and its documents or even request specific
setup properties, such as orientation.

DeviceCapabilities enables the application to get information about such
things as what DeviceMode fields the driver uses and what limits, ranges,
or selections are valid.


4.1.8.1 Indexes for the DeviceCapabilities Function

Printer drivers must process requests from applications for new
DeviceCapabilities indexes. A driver's DeviceCapabilities function must
check for and process the following values.

Value                      Meaning
---------------------------------------------------------------------------

DC_ENUMRESOLUTIONS (13)    Retrieves a list of resolutions supported by the
                           model.

DC_FILEDEPENDENCIES (14)   Retrieves a list of filenames which also need to
                           be installed when the driver is installed.

DC_TRUETYPE (15)           Retrieves the driver's capabilities with regard
                           to printing TrueType fonts.

DC_PAPERNAMES (16)         Enumerates the actual string describing the
                           paper names.

DC_ORIENTATION (17)        Retrieves the relationship between Portrait and
                           Landscape orientations in terms of the number of
                           degrees that portrait orientation is to be
                           rotated counterclock-wise to get landscape
                           orientation.

DC_COPIES (18)             Retrieves the maximum number of copies the
                           device can print.

The implementation of one or all of the indices is optional. If a driver
does not implement a given index, the DeviceCapabilities function should
return -1. For more information about the new indices, see the
DeviceCapabilities function.


4.1.8.2 New Paper Sizes

There are 21 new predefined paper sizes. The include file, PRINT.H,
contains a complete list of all supported paper sizes. Applications
typically call the DeviceCapabilities function to retrieve names and sizes
of the supported paper sizes, so printer drivers must be ready to process
the following DeviceCapabilities index values:

Value           Meaning
---------------------------------------------------------------------------

DC_PAPER        Retrieves the identifiers of the listed paper sizes.

DC_PAPERNAMES   Retrieves the names of the listed paper sizes.

DC_PAPERSIZES   Retrieves the width and height of the listed paper sizes.


4.1.9 Per-Page Printer Settings

Applications can now modify printer settings (that is, DEVMODE values)
while printing a document. The ResetDC function lets applications update
the printer device context at each new page. This means applications can
print documents containing a mixture of page orientations, paper sources,
and other printing options without having to divide the document into
smaller documents.

To support ResetDC, a printer driver must provide code for the RESETDEVICE
escape. This escape, processed by the driver's Control function, copies
printer output state information from one physical device context (PDEVICE)
to another. GDI uses the escape to replace existing device contexts with
new ones.

When an application calls ResetDC, GDI first creates a new PDEVICE by
calling the driver's Enable function. This new PDEVICE receives the new
printer settings as specified by the application. GDI next uses the
RESETDEVICE escape to copy output state information from the existing
PDEVICE to the new one. The output state includes information such as job
number and list of downloaded fonts. The escape must copy the state
information without changing the printer settings in the new PDEVICE.
Finally, GDI substitutes the new PDEVICE for the old one in the
application's device context, discarding the old PDEVICE by calling the
Disable function.

When the printer driver receives the RESETDEVICE request, it must expect a
subsequent call to Disable with no intervening call to the ENDDOC escape.
The printer driver must also ensure that the new printer settings take
affect starting on the next printed page. If a printer driver allocated
bitmap or working buffers when it received the STARTDOC escape, the driver
should free the buffers for the old PDEVICE and allocate new buffers for
the new PDEVICE (an option is to reallocate the buffers).

The ResetDC function cannot be used to change the driver name, device name,
or the output port. When the user physically changes port connection or the
device name, the application must delete the original device context and
recreate a device context with the new device name and output port. Also
the application must cancel the selection of all objects in its device
context before calling ResetDC.


4.1.10 Printer-Model Names

To make printer driver installation easier and more intuitive,
printer-model names have been removed from the DeviceMode dialog box. Users
have found it confusing to select a printer model when installing the
driver only to have to reselect the printer model again within the
printer's DeviceMode dialog box. For Windows 3.1, the DeviceMode dialog box
displays the name of the printer model (selected during installation by the
user) in the title bar of the dialog box.

To support this change, printer drivers must now have corresponding
SETUP.INF or OEMSETUP.INF entries that list all the printer-model names.
Control Panel uses the entries to determine which printer models are
available. If the entries aren't available, Control Panel obtains the
printer-model name from the DESCRIPTION statement in the driver's
executable file header.


4.1.11 Standard Print Dialogs

Windows 3.1 includes a set of standard print dialogs for use by Windows
applications. These dialogs provide a standard interface for users to
select and change printer settings, such as page range, number of copies,
and print quality.

To support the standard print dialogs, a printer driver must export the
ExtDeviceMode and DeviceCapabilities functions. The dialogs call these
functions to get the necessary settings for the standard dialog boxes. If a
printer driver does not export these functions, no printer settings can be
set from within an application using the standard dialog. In such cases,
the dialog boxes are displayed, but the printer settings fields are
disabled (greyed out) and the driver is forced to use the system defaults
that were previously set in Control Panel.

A printer driver can extend the capabilities of the standard print dialogs
by exporting the AdvancedSetUpDialog function. If this function is
available, the standard print dialogs display a More button. If the user
chooses the button, the dialog box calls the AdvancedSetUpDialog function
allowing the driver to display its own dialog box containing fields for
advanced printer settings, such as color, duplex printing, and screen
parameters.


4.1.12 Printer Entries in the WIN.INI File

Printer drivers that support more than one model should now record current
printer settings for each model even if the models use the same port. A
driver records the printer settings for a given model by adding to the
WIN.INI file a section having the following form:

    [ModelName, Port]
The ModelName specifies the name of the model and Port specifies the output
port current associated with the printer as shown in the following example:

    [HP LaserJet IIID, LPT2]
This section must include all printer settings except printer fonts. To
record font information, the driver must add a section having the following
form:

    [DeviceName, Port]
The DeviceName specifies the name of the device and the port specifies the
name of the output port associated with the device as shown in the
following example:

    [HPPCL5A, LPT1]
This section only lists fonts, including those in external cartridges. Also
this section ensures backward compatibility with third-party font packages
that use this section to add fonts.


4.1.13 Physical Objects

Physical objects are device-dependent representations of the logical pens,
brushes, and fonts that Windows applications use to perform output. GDI
directs a printer driver to create physical objects whenever an application
selects a logical object for subsequent drawing. The process of converting
a logical object into a physical object is called realizing the object, and
every printer driver provides a RealizeObject function to carry out this
task.

GDI calls the RealizeObject function when an application calls the
SelectObject function (GDI.45) to select a logical object for a device
context. GDI calls the function twice: once to retrieve the size of the
physical object, and a second time to realize the object. Although the
printer driver realizes an object, GDI manages it, allocating memory for
the object, passing the object to the driver to perform output, and
deleting the object when it is no longer needed.

GDI realizes a physical object when it is selected to avoid the overhead of
realizing the object each time it is used for drawing. The contents and
organization of the structure defining a physical object are specific to
the driver. Usually, the structure includes the logical object plus any
other information that the driver needs.


4.1.14 Device Pens and Brushes

Most printer drivers maintain and manipulate device objects. Device objects
are structures that represent pens and brushes that the device supports.

To determine what device objects are available, GDI calls the EnumObj
function and expects the driver to enumerate all the pens and brushes that
a device supports. The function translates physical descriptions of the
objects into logical descriptions and returns these descriptions to GDI.
All logical objects created this way must be unique, that is, when
translated into physical objects and used for drawing, they should produce
different output.

The driver enumerates all the styles and colors of pens and brushes. Since
pens are defined to be only pure colors, only logical colors that translate
to pure physical colors will be enumerated. For devices that support many
colors, only a subset of all the colors will be enumerated.


4.1.15 Device Fonts

The most common type of device object is a device font. Most printers are
capable of printing some set of built-in fonts. The concept of device fonts
enables drivers and applications to take advantage of a device's ability to
render fonts. Device fonts are also expected to print faster and look
better than GDI fonts.

To determine what device fonts are available, GDI calls the EnumDFonts
function and expects the printer driver to enumerate the fonts. Typically,
GDI first calls EnumDFonts passing an empty string for the font name. This
indicates that the driver should enumerate each font name that it supports.
On subsequent calls, GDI passes one of enumerated font names and expects
the driver to enumerate all the sizes of that font.

Printer drivers may also wish to support GDI raster and vector fonts. For
banding devices, it is usually not difficult to support GDI raster fonts
because GDI contains support functions to render raster fonts into
monochrome-band bitmaps. GDI raster fonts are most useful for devices (such
as lower-resolution dot-matrix printers) with resolutions near those of the
display.

For nonbanding devices, supporting GDI raster fonts is not as easy. In
fact, the PostScript driver (a nonbanding device) does not support GDI
raster fonts.

Supporting vector fonts is also optional. If a driver does not support
vector fonts, GDI will simulate them by drawing line segments.


4.1.16 Color

A printer driver must provide support for translating logical colors (RGB
values) to physical colors. For printers with color palettes, the printer
driver must provide additional information in its GDIINFO structure.


4.1.16.1 Color Objects

GDI calls the ColorInfo function to translate physical and logical color
representations. This function translates in both directions, that is, from
physical to logical and from logical to physical. When given a logical
color, the function returns the nearest physical color. When given a
physical color, the function returns the logical color that best describes
that color.

This function supports the GDI function GetNearestColor.


4.1.16.2 Color Palettes

GDI ignores the color palette members if the RC_PALETTE value is not set in
the dpRaster member. However, they must be present (and accounted for in
the length returned by Enable) if the driver is version 3.x.


4.1.17 Output

A printer driver provides a variety of graphics output from lines to text.
The driver supports each type of output with a specific output function.
When an application calls GDI to carry out a graphics operation, GDI calls
the corresponding output function in the driver. The following lists output
functions and associated graphics output.

Type of Output               Functions
---------------------------------------------------------------------------

Bitmaps                      BitBlt, StretchBlt

Device-independent bitmaps   SetDIBitsToDevice, StretchDIBits

Floodfills                   ScanLR

Lines and figures            Output

Pixels                       Pixel

Text                         ExtTextOut, StrBlt

Some output functions are optional. If a printer driver does not include an
optional function, GDI simulates the output using other output functions.

When GDI calls the output functions, it passes parameters that specify the
output as well as the physical device and physical objects to be used to
generate the output.


4.1.18 Text

A printer driver provides supporting functions and values for text output,
such as maximum text width and height, character widths, and character
clipping.


4.1.18.1 Maximum Text Width and Height

The maximum width and length of text that can be printed on a page is
determined by choosing either the Portrait or Landscape orientation. In
Portrait orientation, the page is taller than wide, when viewing the text
upright. In Landscape orientation, the page is wider than tall, when
viewing the text upright.


4.1.18.2 Character Widths

Use the GetCharWidth function to determine character widths for
variable-width fonts. It is important that the values returned by this
function match and that the actual widths of the characters displayed. Any
differences will produce misalignments, and any text formatting or
justification will not work as intended.


4.1.18.3 Clipping Character Strings

Character strings should be clipped pixel-by-pixel like all other graphics,
whenever possible. Some types of printers, however, do not allow
pixel-precision clipping of device-based fonts. When this is the case, the
driver should clip character strings on a per-character basis.

A driver should clip a character if any part of the character is outside
the left or right edge of the clipping rectangle. If any part of the
character is outside the top or bottom edge of the clipping rectangle, the
driver should print the character.


4.1.19 Fonts

A printer driver provides support for the various fonts provided or
supported by GDI.


4.1.19.1 Big Fonts

Some printer drivers use a new format for fonts when running in protected
mode (with Windows running in either standard or 386 enhanced mode) on an
80386 or 80486-based computer. This format allows for fonts that can exceed
64K bytes of data, as well as some other options. In this situation, GDI
will convert all the 2.x format fonts to the new format so that only one
font file format is used in memory.

If a printer driver prints GDI bitmap fonts directly, it should be modified
to handle big fonts. In many cases, a driver will not need to be updated if
it is a banding monochrome driver that uses only the brute functions. The
brute functions are already aware of the new format. For more information
about brute functions, see Section 4.1.25 The Brute Functions, later in
this chapter.

If a printer driver uses the color library, the library supports the big
font format, as well as the old 2.x format.


4.1.19.2 TrueType

GDI provides TrueType support for any driver that supports GDI raster fonts
(that is, it supports drivers that set the DT_RASPRINTER value in the
dpTechnology member of the GDIINFO structure). To support TrueType on these
printers, GDI generates a raster font from the TrueType outlines and passes
the font to the driver just as with any other raster font. This means many
Windows 3.0 printer drivers, especially drivers for dot-matrix printers,
currently support TrueType--no code changes in the driver are required.

Printer drivers that do not support raster fonts must be modified to
support TrueType. Typically, the modification consists of adding code to
convert TrueType fonts into a downloadable font format that the printer
accepts. To simplify the task of adding TrueType support to nonraster
printer drivers, GDI provides several TrueType service functions.


4.1.19.3 TrueType Service Functions

Printer drivers can use TrueType service functions to retrieve information
about TrueType fonts, to retrieve bitmaps of individual glyphs in the
fonts, and to realize a complete font, retrieving both information and
bitmaps. Following are the service functions and brief descriptions.

Function               Description
---------------------------------------------------------------------------

EngineDeleteFont       Deletes a realized TrueType font.

EngineEnumerateFont    Enumerates TrueType fonts.

EngineGetCharWidth     Retrieves character widths for TrueType fonts.

EngineGetGlyphBmp      Retrieves the bitmap for a rasterized glyph.

EngineRealizeFont      Realizes a TrueType font.

EngineSetFontContext   Sets the context for rasterizing glyphs.

GetRasterizerCaps      Specifies whether TrueType is available.

A printer driver can determine whether TrueType is currently available by
calling the GetRasterizerCaps function. Since users can turn TrueType off,
it is important that a driver check for TrueType before generating output.

If TrueType is on, the driver can call the EngineEnumFonts function
whenever GDI calls the driver's EnumDFonts function. This gives the font
engine the chance to enumerate the TrueType fonts having the specified
font. The driver can call the EngineRealizeFont function whenever GDI calls
the driver's RealizeObject function. This gives the TrueType font engine an
opportunity to generate a physical font that matches the specified logical
font. When the engine realizes a font, it fills a FONTINFO structure with
information about the font as well as the bitmap data for the individual
glyphs. A driver can use this information to create a downloadable font in
the format recognized by the printer.

In general, a printer driver should call the EngineRealizeFont and
EngineEnumerateFont functions before processing its own device fonts (if
any). If GDI requests that the driver delete a realized TrueType font (by
calling RealizeObject), the driver must call the EngineDeleteFont function
to delete the font.

A printer driver can retrieve character width information for a realized
TrueType font by using the EngineGetCharWidth function. It can retrieve
bitmaps for individual glyphs in the font by using the EngineSetFontContext
and EngineGetGlyphBmp functions. The driver must call EngineSetFontContext
first to set the font before calling EngineGetGlyphBmp. Drivers for
printers that accept individual glyph definitions (as opposed to full font
definitions) can use the character width information and bitmap data to
download individual glyphs.


4.1.19.4 Specifying the Spot Size

The spot size is a set of values that help the TrueType rasterizer create
the best glyph bitmaps for a given printer. All printer drivers can benefit
by setting the spot size in their GDIINFO structure regardless of whether
the driver uses TrueType service functions. The spot size should be
specified in the dpSpotSizeX and dpSpotSizeY members of the driver's
GDIINFO structure. If these members are not zero, GDI passes the values to
the TrueType engine to help it rasterize glyphs.


4.1.20 Device-Independent Bitmaps

Device-independent bitmaps (DIBs) are bitmaps in a new format that was
designed to provide a device-independent way for applications to transfer
bitmap images to a variety of output devices. Besides the bitmap bits,
these bitmaps contain color-table information and additional dimension
information.

A printer driver should include support for DIBs, especially in color
devices. If a driver does not support DIBs, GDI can convert DIBs into the
standard monochrome bitmap format, but the quality of DIB output will
rarely be satisfactory in such situations.

If a printer driver can do more with the bitmap, it should attempt to
support DIBs handling, especially if it can perform its own half-toning or
coloring of bitmaps. To enable such functionality, the driver should
support the SetDIBitsToDevice and StretchDIBits functions, and possibly
support the SetDIBits and GetDIBits functions if the driver deals with GDI
bitmaps.


4.1.21 Print Jobs

A printer driver provides print job support by handling printer-specific
escapes. GDI passes escapes to a printer driver's Control function whenever
an application calls the Escape function (GDI.38).


4.1.21.1 The QUERYESCSUPPORT Escape

All drivers are required to implement the QUERYESCSUPPORT escape. For this
escape, the lpInData parameter points to a 16-bit value that contains the
index of another escape.

The driver returns a positive number if the driver implements that escape,
or zero if the escape is unimplemented. The driver always returns nonzero
if the escape queried is QUERYESCSUPPORT.


4.1.21.2 The SETABORTPROC Escape

SETABORTPROC is the first escape an application calls when printing. An
application passes a pointer to a callback function in the lpInData
parameter when it calls the SETABORTPROC escape. This callback function is
used to check for user actions such as cancelling the print job. The
printer driver, however, is not responsible for the callback function; GDI
modifies the SETABORTPROC escape so that lpInData points to the
application's device context handle.

The hDC parameter given to the driver by this escape should be used with
the OpenJob function to enable the output functions in GDI to call the
application's callback function. Printer drivers generally save this handle
in the PDEVICE structure. If the application does not use SETABORTPROC,
NULL should be passed to the OpenJob function.


4.1.21.3 The STARTDOC Escape

Usually, STARTDOC is the escape an application calls. STARTDOC indicates to
GDI and the device driver that the application is printing.

This escape also supplies a Print Manager job title in a NULL-terminated
string pointed to by lpInData. The lpOutData parameter is unused. This
supplies the title used by the OpenJob function.

Together, with the port name supplied as a parameter to Enable and the hDC
supplied by the SETABORTPROC escape, the driver now has all the data
necessary to call the OpenJob function.


4.1.21.4 RESETDEVICE and STARTDOC Escapes

To support the ResetDC and StartDoc functions, which are new to Windows
3.1, printer drivers must process the RESETDEVICE and STARTDOC escapes in
their Control functions.

Although the STARTDOC escape was available in Windows 3.0, the lpInData and
lpOutData parameters have changed. Specifically, lpInData points to a
null-terminated string specifying the name of the document, and lpOutData
points to a DOCINFO structure specifying the output port or file as well as
the document name. The structure has the following form:

    typedef struct {
        short   cbSize;
        LPSTR   lpszDocName;
        LPSTR   lpszOutput;         // output port name
    } DOCINFO, FAR * LPDOCINFO;
The lpszOutput is the name of the output file to use. If either lpOutData
or lpszOutput is NULL, the output port given to CreateDC should be used.

The RESETDEVICE escape, corresponding to the new ResetDC function, allows
the driver to move a printer's output state from an old physical device
structure to a new one. This allows applications to change the printer
setup, such as orientation, with creating a new print job. For more
information about this escape, see Section 4.1.23, Other Escapes.


4.1.21.5 The NEWFRAME Escape

An application calls the NEWFRAME escape when a new page is to be printed.
The printer driver completes output for the given page and advances to the
next page. NEWFRAME does not use the lpInData or lpOutData parameters.


4.1.21.6 The ENDDOC and ABORTDOC Escapes

When an application has completed printing all output, it calls the ENDDOC
escape. ENDDOC does not use either the lpInData or lpOutData parameters. At
this point, the driver may call the CloseJob function.

Another common escape is ABORTDOC, which is also called ABORTPIC in older
documentation or applications, and has the same number assigned. This
escape allows GDI or the application to cancel a print job. Generally, if
the job is valid, the driver will clean up and call the DeleteJob function.


4.1.22 Banding Drivers

How the output functions are implemented depends on whether or not the
device uses banding. Banding devices have their output stored in a
metafile. This metafile is replayed for every band that is rendered (either
by GDI or applications that wish to implement banding). Therefore, output
coordinates must be mapped into the current band, and output outside of the
band must be clipped.

Nonbanding devices perform output to the device in one pass. Therefore, the
device must have access to the entire display surface. Drivers must be able
to perform all the output functions to both the display surface and to
memory bitmaps. This restriction would make it very difficult for devices
that supported complex drawing primitives if it were not for the help that
GDI and the display driver supply.

In the GDIINFO structure, banding color drivers should use the same
bits-per-pixel and planes values used for band bitmaps.

Devices choose numbers that match how they output color. Color printers
that use the color dot-matrix libraries specify the same values as the
bitmap format. The color library in this DDK uses one bit-per-pixel in
three planes. The driver developer must modify the library to use another
format.


4.1.22.1 Raster vs. Vector Devices

Many printers (such as dot-matrix and most laser printers) are raster
printers, that is, they print out text and graphics as bitmaps or raster
lines. Other devices (such as plotters and PostScript-based printers) are
vector devices, which draw text and graphics as a sequence of vectors or
lines. (Although PostScript printers are based on raster engines, the
language itself is vector oriented except where bitmaps are concerned.)

Raster devices usually have constraints that cause problems for
implementing the full GDI device model. Raster devices, for example, do not
implement any vector graphics operations. Therefore, all vector graphics
must be drawn as a bitmap before printing. Some devices, such as dot-matrix
printers, do not allow the driver to print anywhere on the page. They
require that text and graphics be output in the order of the print
direction position on the page.

These bitmaps can be enormous for a device such as a 300 dpi laser printer.
In such cases, the driver breaks up the page into smaller rectangles that
are printed individually. For each of the rectangles, GDI or the
application will draw all the graphics that fit in each rectangle into a
bitmap and then print each individual bitmap.

These rectangles are called bands, and the printing process that uses these
bands is called banding. It is usually necessary to band raster printers;
however, banding is not necessary for vector devices.

For vector devices (that is, nonbanding devices), the application calls GDI
graphics functions, which are translated into device-driver graphics
primitives. After each page is printed, the application uses the NEWFRAME
escape to eject the page.

An application can either treat the driver as if it were a nonbanding
device by calling the GDI functions and ending each page with the NEWFRAME
escape, in which case GDI performs the banding, or it can handle the
banding itself.


4.1.22.2 The NEXTBAND Escape

Before any graphics are drawn, the driver is called upon to perform the
NEXTBAND escape. When the Control function is called for the NEXTBAND
escape, lpInData points to a POINT structure, and lpOutData points to a
RECT structure.

The driver should initialize its band bitmap and set the RECT structure to
the size, in device coordinates, of the rectangle that the band represents
on the page.

GDI adds the POINT structure to determine the scaling factor for graphics
output. Some devices support the use of graphics at a lower resolution than
text to allow for faster output. The x-coordinate of the POINT corresponds
to horizontal scaling and the y-coordinate to vertical scaling.

The value in the structure corresponds to a shift count. A point of (0,0)
specifies graphics at the same density as text, whereas a point of (1,1)
specifies half-density graphics in both directions, for example, a 300 dpi
laser printer printing bitmaps at 150 dpi.

GDI then calls the driver's Output function to draw text or graphics in the
band bitmap. When all drawing for the band is finished, GDI calls the
driver with another NEXTBAND escape. The driver draws the band in the band
bitmap, reinitializes the bitmap, sets a new rectangle, and continues with
the next band as it did with the first.

When all the bands on the page are exhausted, and the driver receives a
NEXTBAND escape, it should output the last graphics band and then set the
rectangle pointed to by the lpOutData parameter to an empty rectangle to
indicate that there are no more bands on the page. It should also perform
all the processing necessary to eject the completed page. The next NEXTBAND
escape will correspond to the first band of the next page.

If the application performs banding, it will call the Escape function to
get the band rectangles. If GDI is handling banding for an application,
then GDI collects all the graphics functions on a page into a metafile,
that is, a temporary file containing a list of the graphics functions and
their parameters. When the application calls Escape to carry out the
NEWFRAME escape, GDI turns this escape into a sequence of NEXTBAND calls to
the Control function. GDI sets the clip region for the actual printer
device context to the band rectangle and then plays back the metafile,
which recreates all of the application's output in the band bitmap. GDI
does this for each band until the band rectangle returned by the driver is
empty.

Some devices, such as raster laser printers, allow text to be placed
anywhere on the page at any time. Furthermore, these printers do not place
text into the band bitmap, since all the device fonts exist in printer or
cartridge memory. To optimize text output, their drivers use a single,
full-page band for all the text output and a sequence of smaller bands for
bitmapped graphics.

As an optimization, some of these drivers maintain a flag to detect whether
or not any output, other than text, is attempted during the first,
full-page band. If not, the driver skips the graphics bands.


4.1.22.3 The BANDINFO Escape

Some devices, such as laser printers, can print text and graphics anywhere
on the page but still require banding support for vector graphics
operations. Since these devices usually use their own internal device
fonts, they can greatly improve their text printing performance by using a
single, full-page band for text only as the first band. The driver ignores
graphics calls during this band and handles only the ExtTextOut or StrBlt
functions. Graphics are printed on subsequent, smaller bands.

An application that is aware of this process can speed up its printing
operation by determining whether text or graphics will be printed on the
current band. It may do so using the BANDINFO escape. The application can
also use BANDINFO to optimize the banding process.


4.1.23 Other Escapes

Few applications use the QUERYESCSUPPORT escape to look for the
SETABORTPROC, STARTDOC, NEWFRAME, ENDDOC, or ABORTDOC escapes. Therefore, a
printer driver should handle all of these escapes.

In addition, there are a few applications that perform banding without
verifying that banding is required either by using QUERYESCSUPPORT or the
GetDeviceCaps function (which examines the GDIINFO structure). A nonbanding
driver can easily support such an application by returning the full page as
the band rectangle on the first NEXTBAND escape and returning an empty
rectangle for the next NEXTBAND escape and ejecting the page.

There are a large number of other escapes that may or may not be
appropriate to a specific driver. They are all listed alphabetically and
described in detail in Chapter 11, Graphics-Driver Escapes.


4.1.24 Print Manager Support

In most cases, printer drivers are not responsible for sending bytes
directly to the output port. Instead, printer drivers call special GDI
functions to carry out the output. Depending on the options selected by the
user, those functions will route the output to a specific port, to a disk
file, across a network connection, or to a temporary file for later output
by Print Manager.

GDI contains functions a device driver can call to perform output. The
driver does not need to know if output is being queued or written directly
to the port. The following lists these functions, and provides a brief
description of each.

Function         Description
---------------------------------------------------------------------------

CloseJob         Closes a print job, and enables it for printing.

DeleteJob        Deletes a open job, removing it from the print queue.

EndSpoolPage     Marks the end of a spooled page.

OpenJob          Opens a print job, returning a handle that the driver can
                 use to write output to the job.

StartSpoolPage   Marks the start of a spooled page. Print Manager manages
                 print jobs by printing one spooled page at a time.

WriteDialog      Displays a dialog box directing the user to carry out some
                 action to permit printing to continue.

WriteSpool       Writes data to an open print job.


4.1.25 The Brute Functions

The brute functions is a set of graphics-support functions that a printer
driver can use to carry out certain graphics operations. The brute
functions permit a printer driver to use the resources of GDI rather than
provide its own support to complete some graphics operations.

Brute functions primarily provide support for memory bitmaps. On each call
to a printer-driver function, the driver checks the PDEVICE structure and
determines if it represents a memory bitmap. If such cases, the driver
calls a corresponding brute function, passing on all the parameters, to
carry out the graphics operation.

For banding drivers, the driver calls the brute functions for the main
output device as well as for the memory bitmaps.


4.1.25.1 Brute-Information Functions

The following brute functions take the same parameters and return values as
the corresponding driver functions and actually call the display driver to
manipulate monochrome memory bitmaps:

o   dmRealizeObject

o   dmEnumDFonts

o   dmEnumObject

o   dmColorInfo

For graphics, most raster drivers call the dmColorInfo function to map
colors. Display drivers then add together the three color components (R, G,
and B). If the weighted, average color value of these components is equal
to or greater than 128, then the color maps to white. Otherwise, it maps to
black.

The IBM Color Printer driver does the same thing in monochrome mode.
However, in color mode, each color is compared individually to the 128
value. Hewlett-Packard printers that use the PCL driver are only adjustable
for text.

Notice that the following colors all map to white on EGA, VGA, and 8514/a
displays:

o   Light grey

o   Green

o   Yellow

o   Magenta

o   Cyan


4.1.25.2 Brute-Output Functions

Nonbanding drivers (such as PostScript or a plotter driver) use the brute
functions to support memory bitmaps. Whenever a pointer to the driver's
PDEVICE structure is passed to the driver, GDI may substitute a pointer to
a BITMAP structure. The driver can differentiate between the two cases
because the first member (bmType) of a BITMAP structure must be zero,
whereas the first member (often called epType) of a PDEVICE structure must
be nonzero. If this first member is zero, the driver simply passes the same
arguments through to the corresponding brute function and returns its
return value.

Banding drivers operate by using a memory bitmap to simulate the display
surface. Therefore, a banding driver calls the brute function with a
pointer to a BITMAP structure that defines the band bitmap. The driver also
has to translate some coordinate parameters from device coordinates to
bitmap coordinates since, in general, there will be many bands in different
positions on a page of output. The brute functions, however, always use
coordinates relative to the bitmap, that is, (0,0) to (bmWidth, bmHeight).

Therefore, many output functions may take the following form:

    Function(LPPDEVICE lpDevice, ... )
    {
        if (!lpDevice-> epType)
          {
            /* output to memory bitmap */
            return dmFunction(lpDevice, ... );
          }
        /* if this is a nonbanding driver, perform
         * device-specific output. Otherwise, for a
         * banding driver,
         */

        /* transform coordinates according to band position
         */
        somerandomxcoordinate -= lpDevice-> xBandPosition;
        somerandomycoordinate -= lpDevice-> yBandPosition;

        /* assume that a BITMAP structure is stored somewhere in
         * the PDEVICE for the band bitmap
         */
        lpDevice = (LPPDEVICE)&lpDevice-> epBandBmpHdr;

        return dmFunction(lpDevice, ... );
    }
The brute functions operate by calling the corresponding display driver
function to manipulate a memory bitmap. Therefore, they have exactly the
same parameters as the corresponding driver functions, with the exception
that the lpDevice parameters are always assumed to point to BITMAP
structures.

Since driver capabilities and bitmap formats vary from display to display,
the printer driver should use the brute functions only for monochrome (not
color) bitmaps. Also, since the scan line and polyline support is required
for all display drivers, the printer driver can assume that this support is
in the brute functions.

The following brute functions are available for output:

o   dmBitBlt

o   dmOutput

o   dmPixel

o   dmStrBlt

o   dmScanLR

There is currently no dmExtTextOut function; the driver calls the
ExtTextOut function.


4.1.25.3 Color-Library Functions

Although the dot-matrix (brute) library functions in GDI (such as dmBitBlt
and dmOutput) only support monochrome printers, a color printer driver can
call corresponding functions in the the color library which do implement
color. The color library supports all the dot-matrix (dm) functions except
dmTranspose. The dmTranspose function does not depend on color format. The
arguments and return values of these functions are the same as those for
the GDI monochrome versions of these functions.

The library implements color using a 3-plane RGB (Red, Green, Blue) banding
bitmap, which is converted to CMYK (Cyan, Magenta, Yellow, Black) when the
bitmap is sent to the printer. If a printer requires a different format,
the color library must be modified.

Both dmBitBlt and dmOutput compile short, efficient functions into the
stack segment and then call them to perform the actual operation. In
protected mode, this requires creating a code segment alias for the stack
segment. A selector must be allocated for these two functions to operate.
It is stored in the global variable ScratchSelector, which is external to
the library and which must be supplied by the driver. In the sample IBM
Color Printer driver, the selector is allocated and freed in Enable and
Disable, respectively.


4.1.26 GDI Priority Queues

The GDI library provides the priority-queue data type that is used with
device-specific fonts to sort output strings into the correct order on the
page. Priority queues are accessed through a two-byte value, known as the
key. Each key can also have two bytes of associates information, called a
tag.

The following lists the priority-queue functions, and provides a brief
description of each.

Function    Description
---------------------------------------------------------------------------

CreatePQ    Creates a priority queue.

DeletePQ    Deletes a priority queue.

InsertPQ    Inserts a key in a priority queue.

MinPQ       Returns the tag having the smallest key in the queue.

SizePQ      Sets the size of the priority queue.

ExtractPQ   Extracts a key from a priority queue.


4.1.27 Stub Functions

Because printer drivers are dynamic-link libraries that GDI loads using the
LoadLibrary function, they must also export the WEP function. This function
indicates that Windows is shutting down or the printer driver is being
unloaded from the system.

Printer drivers must include the SetAttribute and DeviceBitmap functions.


4.1.28 Installing Over Previous Versions

The Windows 3.1 Setup program will automatically update any installed
printer drivers with new drivers provided with Windows 3.1. As part of this
process, Setup will replace:

    generic printer name=driver, port
in the [Devices] and [PrinterPorts] sections with:

    specific model name=new driver, port
Setup will not update the [DriverName, Port] section. This will be done by
the individual driver when Setup calls the DevInstall function.


4.2 Function Reference

The following is an alphabetical listing of graphics functions that are
specific to printer drivers. For a complete description of the graphics
functions that are common to other graphics drivers, see Chapter 10,
Graphics-Driver Functions.

AdvancedSetUpDialog

    WORD AdvancedSetUpDialog(hWnd, hDriver, lpDevModeIn, lpDevModeOut)
    HWND hWnd;
    HANDLE hDriver;
    LPDEVMODE lpDevModeIn;
    LPDEVMODE lpDevModeOut;

The AdvancedSetUpDialog function displays a dialog box with which the user
sets advanced print-job options. Applications call this function indirectly
whenever the user chooses the Options button in the Print Setup dialog box.
AdvancedSetUpDialog lets the user specify print-job options that the driver
supports, such as color, duplex printing, and text quality, but that are
not available through the Print Setup dialog boxes.

Printer drivers that do not export AdvancedSetUpDialog must export the
ExtDeviceMode function.


Parameters

   hWnd
   Identifies the parent window. AdvancedSetUpDialog uses this handle as
   the parent window handle when it creates the dialog box.

   hDriver
   Identifies the module instance of the device driver. AdvancedSetUpDialog
   uses this handle as the module instance handle when it creates the
   dialog box.

   lpDevModeIn
   Points to a DEVMODE structure specifying the initial values for the
   advanced printer options in the dialog box. If the lpDevModeIn parameter
   is NULL or the dmSpecVersion member in this DEVMODE structure is less
   than 0x0300, AdvancedSetUpDialog must return -1 without displaying the
   dialog box.

   lpDevModeOut
   Points to a DEVMODE structure that receives the final values for the
   advanced printer options. The final values include any input from the
   user. If the user cancels the dialog box, AdvancedSetUpDialog must at
   least copy the initial values (supplied in the lpDevModeIn parameter) to
   the lpDevModeOut parameter. The lpDevModeOut parameter must specify all
   print settings, not just those changed by the user.


Return Value

The return value is IDOK if the user chose the OK button to exit the dialog
box, or IDCANCEL if the user chose the Cancel button. In either case, the
structure pointed to by lpDevModeOut contains final values for the advanced
pint-job options. If an error occurs, the function returns -1.


Comments

The export ordinal for this function is 93.

AdvancedSetUpDialog creates an application-modal dialog box using the
DialogBox function (USER.240). The dialog box must provide options for the
user to set the various advanced operating modes of the device. If
DialogBox returns IDOK, AdvancedSetUpDialog copies the complete print-job
information including all the user's input to lpDevModeOut. Otherwise, it
must copy the complete contents of lpDevModeIn to lpDevModeOut.

Although AdvancedSetUpDialog and ExtDeviceMode may display similar dialog
boxes, these functions are not identical. In particular,
AdvancedSetUpDialog must not update or modify the current environment or
WIN.INI settings.


See Also

ExtDeviceMode



DeviceCapabilities

    #include <drivinit.h>

    DWORD DeviceCapabilities(lpDeviceName, lpPort, nIndex, lpOutput,
        lpDevMode)
    LPSTR lpDeviceName;       /* pointer to device-name string         */
    LPSTR lpPort;             /* pointer to port-name string           */
    WORD nIndex;              /* device capability to query            */
    LPSTR lpOutput;           /* pointer to the output                 */
    LPDEVMODE lpDevMode;      /* pointer to structure with device data */

The DeviceCapabilities function retrieves the capabilities of the printer
device driver and is recommended for all printer drivers.


Parameters

   lpDeviceName
   Points to a null-terminated string that contains the name of the printer
   device, such as Hewlett-Packard LaserJet that uses PCL.

   lpPort
   Points to a null-terminated string that contains the name of the port to
   which the device is connected, such as LPT1.

   nIndex
   Specifies the capabilities to query. It can be any one of the following
   values.

         Value                    Meaning
         ------------------------------------------------------------------

         DC_BINNAMES              Copies an array containing a list of the
                                  names of the paper bins. This array is in
                                  the form char
                                  PaperNames[cBinMax][cchBinName] where
                                  cchBinName is 24. If the lpszOutput
                                  parameter is NULL, the return value is
                                  the number of bin entries required.
                                  Otherwise, the return value is the number
                                  of bins copied. To work properly with the
                                  common dialog box library (COMMDLG), a
                                  printer driver for Windows 3.1 must
                                  support the DC_BINNAMES index.

         DC_BINS                  Retrieves a list of available bins. The
                                  function copies the list to lpOutput as a
                                  WORD array. If lpOutput is NULL, the
                                  function returns the number of supported
                                  bins to allow the application the
                                  opportunity to allocate a buffer with the
                                  correct size. See the description of the
                                  dmDefaultSource member of the DEVMODE
                                  structure for information on these
                                  values. An application can determine the
                                  name of device-specific bins by using the
                                  ENUMPAPERBINS escape.

         DC_COPIES                Returns the maximum number of copies the
                                  device can produce.

         DC_DRIVER                Returns the printer-driver version number.

         DC_DUPLEX                Returns the level of duplex support. The
                                  function returns 1 if the printer is
                                  capable of duplex printing. Otherwise,
                                  the return value is zero.

         DC_ENUMRESOLUTIONNAMES   Retrieves a list of resolution names
                                  supported by the model. The application
                                  should allocate a buffer to hold one or
                                  more arrays each containing CCHPAPERNAME
                                  (64) bytes. If lpOutput is NULL, the
                                  function returns the number of
                                  resolutions supported by the model. If
                                  lpOutput is not NULL, the buffer is
                                  filled in.

         DC_ENUMRESOLUTIONS       Returns a list of available resolutions.
                                  If lpOutput is NULL, the function returns
                                  the number of available resolution
                                  configurations. Resolutions are
                                  represented by pairs of LONG integers
                                  representing the horizontal and vertical
                                  resolutions.

         DC_EXTRA                 Returns the number of bytes required for
                                  the device-specific portion of the
                                  DEVMODE structure for the printer driver.

         DC_FIELDS                Returns the dmFields member of the
                                  printer driver's DEVMODE data structure.
                                  The dmFields member indicates which
                                  member in the device-independent portion
                                  of the structure are supported by the
                                  printer driver.

         DC_FILEDEPENDENCIES      Returns a list of files which also need
                                  to be loaded when a driver is installed.
                                  If lpOutput is NULL, the function returns
                                  the number of files. If lpOutput is not
                                  NULL, it is a pointer to an array of
                                  filenames. Each element in the array is
                                  exactly 64 characters long.

         DC_MAXEXTENT             Returns a POINT structure containing the
                                  maximum paper size that the dmPaperLength
                                  and dmPaperWidth members of the printer
                                  driver's DEVMODE structure can specify.

         DC_MINEXTENT             Returns a POINT structure containing the
                                  minimum paper size that the dmPaperLength
                                  and dmPaperWidth members of the printer
                                  driver's DEVMODE structure can specify.

         DC_ORIENTATION           Retrieves the relationship between
                                  portrait and landscape orientations in
                                  terms of the number of degrees that
                                  portrait orientation is to be rotated
                                  counterclock-wise to get landscape
                                  orientation. It can be one of the
                                  following values.

                                         Value   Meaning
                                         ----------------------------------

                                         0       No landscape orientation.

                                         90      Portrait is rotated 90
                                                 degrees to produce
                                                 landscapes. (For example,
                                                 PCL.)

                                         270     Portrait is rotated 270
                                                 degrees to produce
                                                 landscape. (For example,
                                                 dot-matrix printers.)

         DC_PAPERNAMES            Retrieves a list of the nonstandard paper
                                  names supported by the model. The
                                  application should allocate a buffer to
                                  hold one or more arrays each containing
                                  CCHPAPERNAME (64) bytes. If lpOutput is
                                  NULL, the function returns the number of
                                  non-standard paper sizes supported by the
                                  model. If lpOutput is not NULL, the
                                  buffer is filled in.

         DC_PAPERS                Retrieves a list of supported paper
                                  sizes. The function copies the list to
                                  lpOutput as a WORD array and returns the
                                  number of entries in the array. If
                                  lpOutput is NULL, the function returns
                                  the number of supported paper sizes to
                                  allow the application the opportunity to
                                  allocate a buffer with the correct size.
                                  See the description of the dmPaperSize
                                  member of the DEVMODE data structure for
                                  information on these values.

         DC_PAPERSIZE             Copies the dimensions of supported paper
                                  sizes in tenths of a millimeter to an
                                  array of POINT structures pointed to by
                                  lpOutput. This allows an application to
                                  obtain information about nonstandard
                                  paper sizes.

         DC_SIZE                  Returns the dmSize member of the printer
                                  driver's DEVMODE data structure.

         DC_TRUETYPE              Retrieves the driver's capabilities with
                                  regard to printing TrueType fonts. The
                                  return value can be one or more of the
                                  following capability flags.

                                         Value           Meaning
                                         ----------------------------------

                                         DCTT_BITMAP     (0x0000001L)
                                                         Device is capable
                                                         of printing
                                                         TrueType fonts as
                                                         graphics.

                                         DCTT_DOWNLOAD   (0x0000002L)
                                                         Device is capable
                                                         of downloading
                                                         TrueType fonts.

                                         DCTT_SUBDEV     (0x0000004L)
                                                         Device is capable
                                                         of substituting
                                                         device fonts for
                                                         TrueType.

                                  In this case, the lpOutput parameter is
                                  not used, and should be NULL.

         DC_VERSION               Returns the specification version to
                                  which the printer driver conforms.

   lpOutput
   Points to an array of bytes. The actual format of the array depends on
   the setting of the nIndex parameter. If set to zero, DeviceCapabilities
   returns the number of bytes required for the output data.

   lpDevMode
   Points to a DEVMODE structure. If the lpDevMode parameter is NULL, this
   function retrieves the current default initialization values for the
   specified printer driver. Otherwise, the function retrieves the values
   contained in the structure to which lpDevMode points.

   The DEVMODE structure has the following form:

             typedef struct _devicemode {    /* dm */
                 char  dmDeviceName[CCHDEVICENAME];
                 WORD  dmSpecVersion;
                 WORD  dmDriverVersion;
                 WORD  dmSize;
                 WORD  dmDriverExtra;
                 DWORD dmFields;
                 short dmOrientation;
                 short dmPaperSize;
                 short dmPaperLength;
                 short dmPaperWidth;
                 short dmScale;
                 short dmCopies;
                 short dmDefaultSource;
                 short dmPrintQuality;
                 short dmColor;
                 short dmDuplex;
                 short dmYResolution;
                 short dmTTOption;
             } DEVMODE;

Return Value

The return value depends on the setting of the nIndex parameter if
successful. Otherwise, the return value is -1 if the function fails.


Comments

The export ordinal for this function is 91.


See Also

ENUMPAPERBINS, ExtDeviceMode



DevInstall

    WORD DevInstall(hWnd, lpModelName, OldPort, NewPort)
    HWND hWnd;
    LPSTR lpModelName;
    LPSTR OldPort;
    LPSTR NewPort;

The DevInstall function changes port connections, and installs and removes
printers. Control Panel calls this function whenever the user switches the
port for a printer model.


Parameters

   hWnd
   Identifies the parent window to use for any dialog boxes the function
   creates.

   lpModelName
   Points to a null-terminated string specifying the name of the current
   printer model.

   OldPort
   Points to a null-terminated string specifying the name of the port being
   changed. If the OldPort parameter is NULL, the function installs the new
   printer model.

   NewPort
   Points to a null-terminated string specifying the name of the port to be
   changed to. If the NewPort parameter is NULL, the function removes
   printer model.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

1       Succeeded

0       Doesn't support this function

-1      Failed for unknown reason


Comments

When the function changes a port, it must change the port in the
[ModelName, Port] section of the WIN.INI file. Also, the function should
check for a font section with valid entries for the old port. If there are
fonts, the function should warn the user with a message informing them that
there are printer fonts installed for the old port. The user can install
them using the Fonts button from the Printer Setup dialog box.

When installing a new printer, the function must scan the WIN.INI file for
a [DriverName, NewPort] section. If one is found and ModelName matches the
printer index listed there, the function creates a new section [ModelName,
NewPort] and moves all nonfont-related information from the [DriverName,
Newport] section to this new [ModelName, NewPort] section. After this
operation, the [DriverName, NewPort] section contains only the printer
fonts listing. If the function doesn't find a [DeviceName, NewPort]
section, no action is required.

When removing a printer, the function must remove the [ModelName, OldPort]
section including all settings there, but it must not remove the
[DriverName, OldPort] section. Other models may be using fonts installed on
this port.


4.3 Printer Environment Function Reference

The following is an alphabetical listing of printer-environment functions.



GetEnvironment

    int GetEnvironment(lpszPort, lpvEnviron, cbMaxCopy)
    LPCSTR lpszPort;      /* address of port name              */
    void FAR* lpvEnviron; /* address of buffer for environment */
    UINT cbMaxCopy;       /* maximum number of bytes to copy   */

The GetEnvironment function retrieves the current environment that is
associated with the device attached to the specified system port and copies
it into the specified DEVMODE structure. The environment, maintained by
graphics device interface (GDI), contains binary data that GDI uses
whenever a device context is created for the device on the given port.


Parameters

   lpszPort
   Points to the null-terminated string that specifies the name of the
   desired port.

   lpvEnviron
   Points to the DEVMODE structure that will receive the environment. The
   DEVMODE structure has the following form:

         typedef struct _devicemode {    /* dm */
             char  dmDeviceName[CCHDEVICENAME];
             WORD  dmSpecVersion;
             WORD  dmDriverVersion;
             WORD  dmSize;
             WORD  dmDriverExtra;
             DWORD dmFields;
             short dmOrientation;
             short dmPaperSize;
             short dmPaperLength;
             short dmPaperWidth;
             short dmScale;
             short dmCopies;
             short dmDefaultSource;
             short dmPrintQuality;
             short dmColor;
             short dmDuplex;
             short dmYResolution;
             short dmTTOption;
         } DEVMODE;
   cbMaxCopy
   Specifies the maximum number of bytes to be copied to the structure.


Return Value

The return value specifies the number of bytes copied to the DEVMODE
structure pointed to by the lpvEnviron parameter, if the function is
successful. If lpvEnviron is NULL, the return value is the number of bytes
required to hold the environment. It is zero if the environment cannot be
found.


Comments

The GetEnvironment function is used by drivers only.

The GetEnvironment function fails if there is no environment for the given
port.

An application can call this function with the lpvEnviron parameter set to
NULL to determine the size of the structure required to hold the
environment. It can then allocate the required number of bytes and call the
GetEnvironment function a second time to retrieve the environment. The
first member in the block pointed to by the lpEnviron parameter should be
an atom that the printer driver has added to the global atom table.


See Also

SetEnvironment



SetEnvironment

    int SetEnvironment(lpszPort, lpvEnviron, cbMaxCopy)
    LPCSTR lpszPort;            /* address of port name                  */
    const void FAR* lpvEnviron; /* address of buffer for new environment */
    UINT cbMaxCopy;             /* maximum number of bytes to copy   */

The SetEnvironment function copies the contents of the specified buffer
into the environment associated with the device attached to the specified
system port. The environment, maintained by GDI, contains binary data used
by GDI whenever a device context is created for the device on the given
port.


Parameters

   lpszPort
   Points to a null-terminated string that specifies the name of the port.

   lpvEnviron
   Points to the buffer that contains the new environment. This buffer is
   in the form of a DEVMODE structure. The DEVMODE structure has the
   following form:

         typedef struct _devicemode {    /* dm */
             char  dmDeviceName[CCHDEVICENAME];
             WORD  dmSpecVersion;
             WORD  dmDriverVersion;
             WORD  dmSize;
             WORD  dmDriverExtra;
             DWORD dmFields;
             short dmOrientation;
             short dmPaperSize;
             short dmPaperLength;
             short dmPaperWidth;
             short dmScale;
             short dmCopies;
             short dmDefaultSource;
             short dmPrintQuality;
             short dmColor;
             short dmDuplex;
             short dmYResolution;
             short dmTTOption;
         } DEVMODE;
   cbMaxCopy
   Specifies the maximum number of bytes to copy to the buffer.


Return Value

The return value is the number of bytes copied to the environment, if the
function is successful. It is zero if there is an error or 1 if the
environment is deleted.


Comments

The SetEnvironment function is used by device drivers.

The SetEnvironment function deletes any existing environment. If there is
no environment for the given port, SetEnvironment creates one. If the
cbMaxCopy parameter is zero, the existing environment is deleted and not
replaced.

The first member of the DEVMODE structure pointed to by the lpvEnviron
parameter must be the same as that passed in the lpDestDevType parameter of
the Enable function. If lpszPort specifies a null port, the dmDeviceName
member is used to locate the environment. The first member in the block
pointed to by the lpEnviron parameter should be an atom that the printer
driver has added to the global atom table.


See Also

GetEnvironment


4.4 Priority-Queue Function Reference

The following is an alphabetical listing of the priority-queue functions.



CreatePQ

    HPQ CreatePQ(size)
    int size;

The CreatePQ function creates a priority queue.


Parameters

   size
   Specifies the maximum number of items to be inserted into this priority
   queue.


Return Value

The return value is a handle to the priority queue if the function is
successful. Otherwise, it is zero.


See Also

DeletePQ



DeletePQ

    int DeletePQ(hPQ)
    HPQ hPQ;

The DeletePQ function deletes a priority queue.


Parameter

   hPQ
   Identifies a priority queue.


Return Value

The return value is TRUE if the queue is deleted. Otherwise, it is -1.



ExtractPQ

    int ExtractPQ(hPQ)
    HPQ hPQ;

The ExtractPQ function returns the tag associated with the key having the
smallest value in the priority queue and removes the key from the queue.


Parameter

   hPQ
   Identifies a priority queue.


Return Value

The return value is a tag associated with the key in the priority queue.



InsertPQ

    BOOL InsertPQ(hPQ, tag, key)
    HPQ hPQ;
    int tag;
    int key;

The InsertPQ function inserts the key and its associated tag into the
priority queue.


Parameters

   hPQ
   Identifies a priority queue.

   tag
   Specifies a tag associated with the key.

   key
   Specifies a key.


Return Value

The return value is TRUE if the insertion is successful. Otherwise, it is
-1.



MinPQ

    int MinPQ(hPQ)
    HPQ hPQ;

The MinPQ function returns the tag associated with the key having the
smallest value in the priority queue, without removing this element from
the queue.


Parameter

   hPQ
   Identifies a priority queue.


Return Value

The return value is the tag associated with the key in the priority queue.


See Also

ExtractPQ



SizePQ

    int SizePQ(hPQ, sizechange)
    HPQ hPQ;
    int sizechange;

The SizePQ function increases or decreases the size of the priority queue.


Parameters

   hPQ
   Identifies a priority queue.

   sizechange
   Specifies the number of entries to be added or removed.


Return Value

The return value is the number of entries that can be accommodated by the
resized priority queue. The return value is -1 if the resulting size is
smaller than the actual number of elements in the priority queue.


4.5 Print Manager Function Reference

The following is an alphabetical listing of Print Manager functions.



CloseJob

    int FAR PASCAL CloseJob(hJob)
    HANDLE hJob;

The CloseJob function closes the print job identified by the given handle.


Parameters

   hJob
   Identifies the print job to close. The handle must have been previously
   opened using the OpenJob function.


Return Value

The return value is positive if the function is successful. Otherwise, it
is one of the following error values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.


See Also

OpenJob



DeleteJob

    int FAR PASCAL DeleteJob(hJob, wDummy)
    HANDLE hJob;
    WORD wDummy;

The DeleteJob function deletes the given print job from the printing queue.
A driver should call this function if it detects an error condition, or is
asked to quit a job by the application.


Parameters

   hJob
   Identifies the print job to delete. The handle must have been previously
   opened using the OpenJob function.

   wDummy
   Reserved; must be set to zero.


Return Value

The return value is positive if the function is successful. Otherwise, it
is one of the following error values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.


See Also

OpenJob



EndSpoolPage

    int FAR PASCAL EndSpoolPage(hJob)
    HANDLE hJob;

The EndSpoolPage function marks the end of a spooled page. A driver uses
this function, in conjunction with the StartSpoolPage function, to divide
printer output into pages. Each page is stored in a temporary file on the
machine's hard disk when Print Manager is running. Dividing a print job
into pages allows Print Manager to begin printing one page while the driver
is still generating output on subsequent pages. A Print Manager page does
not need to correspond to a physical page of printed output; the division
is the driver's decision.


Parameters

   hJob
   Identifies the print job. The handle must have been previously opened
   using the OpenJob function.


Return Value

The return value is positive if the function is successful. Otherwise, it
is one of the following error values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.


Comments

When Print Manager is not running, page division is not very important
because temporary files are not involved. However, starting and ending at
least one Print Manager page is still required.

Calls to StartSpoolPage and EndSpoolPage can occur at any point during the
output. Some drivers use one spool page per physical page. Others use one
page for the whole job. The printing of a particular page by the Print
Manager application does not begin until it receives the corresponding
EndSpoolPage function.

A driver can perform output at any point between these two calls. When
EndSpoolPage is called and Print Manager is loaded, the page's temporary
file is submitted to Windows Print Manager.


See Also

OpenJob, StartSpoolPage



OpenJob

    HANDLE FAR PASCAL OpenJob(lpOutput, lpTitle, hdc)
    LPSTR lpOutput;
    LPSTR lpTitle;
    HDC hdc;

The OpenJob function creates a print job and returns a handle identifying
the job. A driver uses the handle in subsequent functions to write output
to the print job as well as control the job.


Parameters

   lpOutput
   Points to a null-terminated string specifying the port or file to
   receive the output. A driver typically supplies the same filename as
   pointed to by the lpOutputFile parameter when GDI calls the driver's
   Enable function.

   lpTitle
   Points to a null-terminated string specifying the title of the document
   to print. This parameter must be supplied by the application when it
   calls the STARTDOC escape. This title appears in the Print Manager
   display.

   hdc
   Identifies the application's device context. This parameter must be
   supplied by the application when it calls the STARTDOC escape.


Return Value

The return value is a handle identifying the print job if the function is
successful. Otherwise, it is one of the following error values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.


See Also

CloseJob, Enable, STARTDOC



StartSpoolPage

    int FAR PASCAL StartSpoolPage(hJob)
    HANDLE hJob;

The StartSpoolPage function marks the start of a spooled page. A driver
uses this function, in conjunction with the EndSpoolPage function, to
divide printer output into pages. Each page is stored in a temporary file
on the machine's hard disk when Print Manager is running. Dividing a print
job into pages allows Print Manager to begin printing one page while the
driver is still generating output on subsequent pages. A Print Manager page
does not need to correspond to a physical page of printed output; the
division is the driver's decision.


Parameters

   hJob
   Identifies the print job. The handle must have been previously opened
   using the OpenJob function.


Return Value

The return value is positive if the function is successful. Otherwise, it
is one of the following error values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.


Comments

When Print Manager is not running, page division is not very important
because temporary files are not involved. However, starting and ending at
least one Print Manager page is still required.

Calls to StartSpoolPage and EndSpoolPage can occur at any point during the
output. Some drivers use one spool page per physical page. Others use one
page for the whole job. The printing of a particular page by the Print
Manager application does not begin until it receives the corresponding
EndSpoolPage function.

A driver can perform output at any point between these two calls. When
EndSpoolPage is called and Print Manager is loaded, the page's temporary
file is submitted to Windows Print Manager.


See Also

EndSpoolPage, OpenJob



WriteDialog

    int FAR PASCAL WriteDialog(hJob, lpMsg, cch)
    HANDLE hJob;
    LPSTR lpMsg;
    WORD cch;

The WriteDialog function displays a message box containing the specified
message. A driver uses this function to inform the user of a possible
printing problem. For example, a driver for a printer using manual-paper
loading can call WriteDialog to ask the user to place a new sheet in the
printer. The print job will not continue printing until the user chooses
the OK button in the message box. The user may also choose a Cancel button
to cancel the print job.


Parameters

   hJob
   Identifies the print job. The handle must have been previously opened
   using the OpenJob function.

   lpMsg
   Points to a null-terminated string containing the message to be
   displayed.

   cch
   Specifies the number of bytes in the message pointed to by the lpMsg
   parameter.


Return Value

The return value is IDOK if the function is successful. Otherwise, it is
IDCANCEL.


See Also

OpenJob



WriteSpool

    int FAR PASCAL WriteSpool(hJob, lpData, cch)
    HANDLE hJob;
    LPSTR lpData;
    WORD cch;

The WriteSpool function writes printer output to the port or file
associated with the print job. A driver must call this function after
calling StartSpoolPage and before calling EndSpoolJob.


Parameters

   hJob
   Identifies the print job. The handle must have been previously opened
   using the OpenJob function.

   lpData
   Points to the device-dependent data to write.

   cch
   Specifies the number of bytes to write.


Return Value

The return value is positive if the function is successful. Otherwise, it
is one of the following error values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.


See Also

EndSpoolPage, OpenJob, StartSpoolPage


4.6 TrueType Structure Reference

The following is an alphabetical listing of the structures that are
specific to TrueType support for printer drivers.



BITMAPMETRICS

    typedef struct _BITMAPMETRICS {
        SIZEL sizlExtent;
        POINTFX pfxOrigin;
        POINTFX pfxCharInc;
    } BITMAPETRICS;
The BITMAPMETRICS structure defines the character cell that corresponds to
a given glyph bitmap. The structure gives the width and height of the cell,
the position of the bitmap relative to the origin of the cell, and the
horizontal and vertical increments.


Members

   sizlExtent
   Specifies the width and height of the bitmap. Since scan lines are
   aligned on 32-bit boundaries, the byte width of a scan line is the
   number of pixels rounded to the next multiple of 32 and divided by 8.

   pfxOrigin
   Specifies the position of the upper-left corner of the bitmap relative
   to the character origin.

   pfxCharInc
   Specifies the increment to the next character. In this case,
   PFXCHARINC.X is the increment along the baseline.


Comments

The increment and origin of a character may be such that consecutive
characters overlap. That is, the origin may be negative or the increment
may be smaller that the actual width. The device driver is responsible for
drawing overlapping glyphs without overwriting characters.

When calculating string widths, a device driver uses the increment as the
width.



FIXED

    typedef DWORD FIXED;
The FIXED type specifies a 32-bit, fixed point number. The type consists of
16-bit fields, representing an integer and a fraction as follows:

Bits    Meaning
---------------------------------------------------------------------------

0-15    Specifies the fractional part of the fixed point number. The
        fraction is always a positive value representing the numerator n of
        the expression n/65536.

16-31   Specifies the integer part of the fixed point number. The integer
        is a signed value in the range -32768 to 32767.



POINTFX

    typedef struc _POINTFX {
        FIXED x;
        FIXED y;
    } POINTFX;
The POINTFX structure specifies the x- and y-coordinates of a point. The
coordinates are expressed as 32-bit fixed point numbers.


Members

   x
   Specifies a width or x-coordinate.

   y
   Specifies a height or y-coordinate.



SIZEL

    typedef struct _SIZEL {
        DWORD x;
        DWORD y;
    } SIZEL;
The SIZEL structure contains information about the size or location of a
object specified as two 32-bit values.


Members

   x
   Specifies a width or x-coordinate.

   y
   Specifies a height or y-coordinate.



TTINFO

    typedef struct tagTTINFO {
        WORD cbInfo;
        WORD fFlags;
    } TTINFO;
The TTINFO structure contains information specifying whether TrueType is
operating and whether TrueType fonts have been installed.


Members

   cbInfo
   Specifies the number of bytes in the structure.

   fFlags
   Specifies the state of TrueType and TrueType fonts. This field can be a
   combination of the following values:

     Value    Meaning
     ----------------------------------------------------------------------

     0x0001   At least one TrueType has been installed.

     0x0002   TrueType rasterizer is operating.


4.7 File-Format Reference

The following is an alphabetical listing of the file formats that are
specific to printer drivers. For a complete description of the file formats
that are common to other graphics drivers, see Chapter 13, Font Files.



DDRV

    DESCRIPTION 'DDRV Description:AspectXY,LogPixelsX,LogPixelsY'
The DDRV statement in the printer driver's module-definition file names the
printer models supported by the printer driver, and specifies the aspect
ratio and logical pixels-per-inch values of the printer.

Every printer driver must provide a DDRV statement. Control Panel uses the
statement to display the name of the printer to the user and to choose
matching screen fonts for the printer.


Parameters

   Description
   Specifies the name or names of the printer models supported by this
   driver. Although more than one name can be given, the names must not be
   separated by commas (,).

   AspectXY
   Specifies the aspect ratio for the printer. This parameter must be set
   to the same value as the driver's dpAspectXY member in the GDIINFO
   structure.

   LogPixelsX
   Specifies the horizontal pixels-per-inch for the printer. This parameter
   must be set to the same value as the driver's dpLogPixelsX member in the
   GDIINFO structure.

   LogPixelsY
   Specifies the vertical pixels-per-inch for the printer. This parameter
   must be set to the same value as the driver's dpLogPixelsX member in the
   GDIINFO structure.


Comments

The DDRV keyword must be capitalized. At least one character (typically a
space) must follow the DDRV keyword; Control Panel always ignores this
first character.

Control Panel uses the Description (all characters up to the colon)
parameter to create new settings for the [Devices] and [PrinterPorts]
sections in the WIN.INI file. The settings have the following form:

    Description=Port[,Data]

Examples

The following example shows a DDRV description for a printer driver
supporting a single model:

    DESCRIPTION 'DDRV PCL / HP LaserJet:100,300,300'
The following example shows support for multiple printer models:

    DESCRIPTION 'DDRV Printer 1/Printer2:100,300,300'
Chapter 5  Network Drivers

The Microsoft Windows network driver provides a set of generic network
functions that File Manager and other system utilities can use to make
network connections, print over the network, and keep track of jobs in
network print queues. This chapter describes the network driver functions,
and explains how the network driver interacts with existing network
software.


5.1 About the Network Driver

The network driver is a dynamic-link library (DLL) containing exported
network functions. Windows calls these network functions to carry out
network requests, such as redirecting a local drive to a remote server or
adding a job to a network print queue. The network functions, in turn, may
use MS-DOS functions, NetBIOS routines, and network software to complete
the network request.


5.1.1 Initializing the Driver

The driver's initialization routine (the entry point for the DLL) should
check to make sure that the appropriate network is actually installed and
running. If it is not, the routine should return zero to prevent the driver
from being loaded. Windows then behaves exactly as if no network driver
were installed.

The driver should also check the netwarn setting in the [Windows] section
of the WIN.INI file. If the value is 1, the driver should display a message
box to inform the user that the network is not installed before returning
to Windows. The netwarn setting allows users who run Windows frequently
without loading the network to disable the message box.


5.1.2 Enabling and Disabling the Driver

The network driver provides the Enable and Disable functions to allow
Windows to enable and disable the driver. The Enable function prepares the
system and network software for operation; the Disable function restores
the system and software to its previous configuration. For example, the
Enable function hooks the interrupt, and the Disable function removes the
hook.

Windows calls Enable when first loading the driver. Standard-mode Windows
calls Disable when switching to a non-Windows application, and it calls
Enable when switching back from the non-Windows application. Finally,
Windows calls Disable when terminating itself. This final call to Disable
occurs before Windows calls the driver's WEP function.


5.1.3 Network Capabilities

Every network driver provides a set of network capabilities, such as
connecting to devices and managing print jobs. To help Windows determine
what capabilities the driver supports, the driver exports the WNetGetCaps
function. Windows calls WNetGetCaps with an index specifying a given
function category, and WNetGetCaps returns a bit mask specifying which
network functions the driver supports for that given category. WNetGetCaps
also returns other information about the driver, such as its version
number.


5.1.4 Connection Functions

The network driver can provide a variety of connection functions to let
File Manager and Print Manager connect to remote drives and devices.

Function                Description
---------------------------------------------------------------------------

WNetAddConnection       Creates a connection to a network drive or device.

WNetCancelConnection    Removes a connection to a network drive or device.

WNetGetConnections      Retrieves a list of current connections.

WNetRestoreConnection   Reconnects one or more permanently connected
                        network drives.


5.1.4.1 Saved Network Connections

Saved network connections are connections which are always automatically
connected when Windows starts. If the connection cannot be made, the drive
is still treated as connected, as if it were in the error state. File
Manager reconnects the drive if the user selects it. When the user connects
to a drive or printer, that connection is remembered as a permanent
connection. When the user disconnects a device through the disconnect
dialog box, it is removed from the list of permanently connected devices.

Although error state and permanent devices can be reconnected from File
Manager, the drives may not (generally will not) be valid for other Windows
applications. If Windows is unable to restore a permanent connection when
starting, a dialog box will warn the user of this event.

Network drivers which implement these functions will return a specification
version of 3.1 (0x030A) from when the WNNC_SPEC_VERSION value is specified
with the WNetGetCaps function.

Drivers written for the Windows 3.0 level of functionality will be supplied
with reasonable defaults for all 3.1 features. If a network does not
require special support for any of the features the network driver may be
written to the 3.0 specification.


5.1.4.2 Default Shell Behavior

If a network driver does not support the 3.1 functions (for example, it is
a Windows 3.0 network driver), Windows and File Manager simulate a new
method of supporting permanent connections.

If the user makes a permanent connection, the device will be added to the
[Network] section in the WIN.INI file. The keyword will be the local device
and the value will be the network resource. For security, passwords will
not be saved. The following example illustrates the new section:

    [Network]
    S:=\\USER2\SHELL
    T:=\\TOOLSVR\DOSENV
    U:=\\PYREX\USER
    LPT1=\\WINDEV\PRINTER
When a device is disconnected, it is removed from the list of permanent
devices. File Manager simulates the behavior of WNetGetConnection returning
a connection with a special status when it is listed in the WIN.INI file,
but is not connected. The default connection dialogs allows the user to
reconnect a disconnected device which has a saved connection. The dialogs
also support disconnecting and reconnecting a device in an error state.

When Windows starts, it enumerates devices saved in the [Network] section
and attempts to redirect them using WNetAddConnection. If a device is
already redirected, the redirection will not be overridden. If
WNetAddConnection returns the WN_BAD_PASSWORD value, the user will be
prompted to supply the password.

Network drivers which require their own connection dialog boxes or startup
restore function should attempt to duplicate the functionality of the
default behavior as closely as possible in order to provide consistency. To
maintain this consistency, network drivers should use the [Network]
section. The keywords A: through Z: and all common MS-DOS device names
(LPT1, COM1, PRN, and so on) are reserved, including those not currently
supported for redirection. The network driver may define additional
keywords of its own.


5.1.5 Printing Functions

The network driver can provide a variety of printing functions to let File
Manager and Print Manager open printing jobs and monitor the print queues.

Function              Description
---------------------------------------------------------------------------

WNetAbortJob          Cancels a print job while still open.

WNetCancelJob         Cancels a print job, removing the job from the queue.

WNetCloseJob          Closes a print job and enables it for printing.

WNetHoldJob           Holds a print job until released.

WNetLockQueueData     Locks a queue buffer, allowing a program to view the
                      status of a printing queue.

WNetOpenJob           Opens a print job, permitting a program to
                      subsequently write data to the job.

WNetReleaseJob        Releases a held print job.

WNetSetJobCopies      Specifies the number of copies to print.

WNetUnlockQueueData   Unlocks a previously locked queue buffer.

WNetUnwatchQueue      Stops watching a specific queue.

WNetWatchQueue        Watches a specific queue, informing Print Manager of
                      any changes to the queue.

WNetWriteJob          Writes data to a print job.


5.1.6 Dialog Functions

The network driver can provide a variety of dialog boxes to allow a user to
modify the networks configuration and operation.

Function               Description
---------------------------------------------------------------------------

WNetBrowseDialog       Displays a dialog box allowing the user to browse a
                       list of network drives and devices and choose one to
                       connect to.

WNetConnectDialog      Displays a connection dialog box allowing the user
                       to specify how to connect a network drive or device.

WNetConnectionDialog   Displays a dialog box allowing the user to specify
                       whether to connect or disconnect a network driver or
                       device.

WNetDeviceMode         Displays a dialog box allowing the user to examine
                       and modify network settings.

WNetDisconnectDialog   Displays a disconnection dialog box allowing the
                       user to specify whether a network drive or device
                       should be disconnected.

WNetGetPropertyText    Adds one or more buttons to the standard property
                       dialog.

WNetPropertyDialog     Carries out actions specified by driver-specific
                       buttons in the property dialog.

WNetViewQueueDialog    Displays a queue-viewing dialog box allowing the
                       user to view the print jobs in a given queue.

The network driver displays dialog boxes to ask for or present information.
In particular, Control Panel allows the user to call a network-specific
dialog box, which can provide access to any additional features the network
supports. For example, the dialog box could allow the user to log on under
a new name or send messages to another user, if the network supports these
operations.

It is also the place where the driver version, copyright, and any other
information can be displayed. In general, network dialog box will offer the
user any options, some mechanism should be included to enable the user to
access online Help.


5.1.7 Administrative Functions

The network driver can provide a variety of administrative functions to
allow File Manager to keep up-to-date information about directories on
network servers.

Function               Description
---------------------------------------------------------------------------

WNetDirectoryNotify    Notifies File Manager of changes to a network
                       directory.

WNetGetDirectoryType   Retrieves the type (normal or network) of a given
                       directory.

In Windows 3.1, these administrative functions are limited to modifying
directory icons, and getting notification of directory manipulations.


5.1.8 Long-Filename Functions

The network driver can provide a variety of long-filename functions. The
long-filename functions give access to files with names that do not fit the
MS-DOS standard filename convention on network drives. These are the
following long filename functions.

Function            Description
---------------------------------------------------------------------------

LFNCopy             Copies a file.

LFNDelete           Deletes a file.

LFNFindClose        Ends the search for matching files.

LFNFindFirst        Searches for the first file with a matching name.

LFNFindNext         Searches for the next file with a matching name.

LFNGetAttributes    Retrieves file attributes.

LFNGetVolumeLabel   Retrieves the volume label.

LFNMKDir            Creates a directory.

LFNMove             Moves a file.

LFNParse            Parses paths.

LFNRMDir            Removes a directory.

LFNSetAttributes    Sets file attributes.

LFNSetVolumeLabel   Sets the volume label.

LFNVolumeType       Specifies volume type.

Typically, these functions are called only when a network drive with long
filenames is detected. In other words, they do not need to support local
drives. The exception is the LFNCopy function, which must be able to copy
to or from any type of volume.

The return value is typically an MS-DOS error function (as returned from
MS-DOS functions when the carry flag is set, or from Interrupt 21h Function
59h, Get Extended Error Information). If a function returns the special
error value 0xFFFF, then the network error message functions will be called
to retrieve error message text.

The maximum length of any long filename will be assumed to be 260
characters, including the terminator.

File-attribute values are identical to MS-DOS file-attribute fields.


5.1.9 Error-Handling Functions

The network driver can provide a variety of error-handling functions to let
File Manager and Print Manager retrieve additional information about errors
that occur over the network.

Function           Description
---------------------------------------------------------------------------

WNetGetError       Returns the status value (including error value) for the
                   most recent network operation.

WNetGetErrorInfo   Returns a text string describing the most recent network
                   error.

If appropriate, File Manager posts error messages whenever an error is
reported by a network driver function. If the error value is WN_NET_ERROR,
the WNetGetError and WNetGetErrorText functions will be called to allow the
network driver to return a network-specific error. If these two functions
fail or are not implemented, a generic message will be used instead. Some
functions, such as connection dialogs, are allowed to post their own
messages as part of processing the dialog box. File Manager never posts
error messages if the return value is WN_SUCCESS, WN_CANCEL, or WN_CONTINUE
unless otherwise noted.


5.1.10 User Functions

For network drivers that provide user functions, the following ordinals are
reserved for the user functions:

    WNNC_ORD_UserStart      500
    WNNC_ORD_UserEnd        599
File Manager never uses ordinals in this range.


5.2 About the Network-Driver Support Software

The network driver (as well as Windows and non-Windows applications) may
require network support software to actually carry out network requests. In
many cases, a network driver carries out a request by calling corresponding
functions in MS-DOS, the NetBIOS, or in real-mode network device drivers or
terminate-and-stay-resident (TSR) programs. Since the network driver runs
in protected mode, extra measures are required to call this real-mode
software. Furthermore, since Windows can switch between applications while
network requests are being processed, measures are required to prevent loss
and corruption of data as a result of a switch.

The following sections describe network support in standard- and 386
enhanced-mode Windows.


5.2.1 Network Support for 386 Enhanced-Mode Windows

Since 386 enhanced-mode Windows is a multitasking, protected-mode
environment, the network driver or related software must support the
following:

o   Asynchronous network requests

o   Application programming interface (API) mapping

o   Expanded Memory Specification (EMS) memory

In 386 enhanced-mode Windows, much of the additional network support is
provided by virtual devices.


5.2.1.1 VNETBIOS and DOSNET Virtual Devices

Microsoft provides two network-related virtual devices: VNETBIOS and
DOSNET. The VNETBIOS device provides support for the NetBIOS interface; the
DOSNET device supports the Microsoft LAN Manager and Microsoft Network
interfaces. If the network support software is compatible with these
interfaces, no additional work is required to support the network driver.
If the support software is not compatible, a new or a modified virtual
device may be required.

The VNETBIOS and DOSNET virtual devices may be modified, extended, or
replaced to fit a given network's needs. Notice, however, that the DOSNET
device provides services that are also used by other virtual devices.
Therefore, it is standard practice to replace it with a new device that has
a different name, but which also uses the same device identifier as DOSNET.


5.2.1.2 Asynchronous Network Requests

The VNETBIOS device maps all asynchronous request arguments to a global
buffer located between 640K and 1 megabyte. Furthermore, VNETBIOS sets up a
dummy callback function for any requests in which the application provided
a callback. The network software uses the global buffer and dummy callback
to complete the asynchronous event. Later, VNETBIOS copies the data to the
application's original buffer and calls the application's callback address.
When either Windows or a virtual machine (VM) terminates, 386 enhanced-mode
Windows cancels any outstanding asynchronous network requests as well as
all local connections.

Support for asynchronous network requests can also be added to the network
software. Although this requires changes to the network software, no
customizing of 386 enhanced-mode Windows is required. Network software can
manage asynchronous requests by using virtual-machine identifiers or by
using critical sections.

Network software can always retrieve the identifier of the current virtual
machine by using Get Current Virtual Machine ID (Interrupt 2Fh Function
1683h). This means the software can always identify which virtual machine
that initiates the asynchronous request by saving the identifier with the
requests buffer or callback address. Later, when the network software needs
to access these locations, it can again retrieve the current VM identifier
and compare it with the saved identifier. If the identifiers match, the
stored addresses are valid and the software can complete the operation. If
they do not match, the network software can use Switch VMs and Callback
(Interrupt 2Fh Function 1685h) to direct 386 enhanced-mode Windows to
switch to the correct virtual machine. In such cases, Windows calls the
given callback function which can carry out the network operation.

Network software can also handle asynchronous requests by enclosing the
request in a critical section. However, this method is not recommended.
Windows does not switch tasks while in the critical section, so although an
asynchronous request is guaranteed to complete in the correct virtual
machine, the user will be left waiting for each asynchronous task to
complete before being allowed to switch to another program or application.
Since some asynchronous requests can be outstanding for a very long time,
this can make the system less than useful. Network software can start and
end a critical section by using Begin Critical Section and End Critical
Section (Interrupt 2Fh Functions 1681h and 1682h).


5.2.1.3 API Mapping

In 386 enhanced-mode, MS-DOS, the BIOS, and all TSR programs (such as
networks) run in virtual mode. If a Windows application needs to pass an
address to MS-DOS, the BIOS, the network, or any other software loaded
before Windows, it must map the address to a real mode address. Mapping
applies to addresses pushed on stack as function parameters and addresses
embedded in buffers passed as function parameters.

In general, a mapper must hook the interrupts for MS-DOS, BIOS, or the
network to determine the exact API being used. In every case where an
address is being passed, the mapper must:

1.  Copy the passed data or buffer space down into virtual-mode memory.

2.  Replace the protected-mode address with a real-mode address pointing to
    the data's new location.

3.  Simulate the original interrupt to let the recipient software handle it.

When the MS-DOS, BIOS, or network software returns from the interrupt, the
mapper must go through the same process but in reverse, copying data from
the address to a protected-mode location, and readjusting the pointer to a
protected-mode address again so that the original caller can use it
correctly.


5.2.1.4 EMS Memory

Some network software minimize use of conventional memory by storing data
and code in EMS memory. Although this frees memory before 386 enhanced-mode
Windows starts, some EMS emulators are not compatible with Windows and may
either prevent Windows from starting or make the network data and code
unavailable while Windows runs.

To ensure EMS compatibility with Windows, use a cooperating EMS emulator
(such as EMM386.SYS). When starting, 386 enhanced-mode Windows checks for
an EMS emulator and prints an error message and terminates if it detects an
unknown emulator.

If the computer has EMS hardware but no software has opened an EMS handle,
386 enhanced-mode Windows bypasses and ignores EMS hardware. Instead, it
provides simulated expanded memory to Windows applications and non-Windows
applications. When Windows exits, it makes the EMS hardware available once
again.

If certain expanded memory emulators (such as Microsoft EMM386 version 4.0
and Compaq CEMM) are running and no software has opened an EMS handle, 386
enhanced-mode Windows turns off the emulator and provides simulated EMS to
Windows applications and non-Windows applications. When Windows exits, it
turns the EMS emulator back on.


5.2.1.5 Network-Virtual Device

With 386 enhanced-mode Windows, it is possible to write a virtual device
that understands the network well enough to route events to the appropriate
virtual machines.

For example, when the network card generates an interrupt telling the
network software that its information packet has arrived, the virtual
device reads the packet and simulates the network interrupt for the
real-mode network software. Otherwise, it can schedule an event for the
target VM, including boosting its priority to get it to run as soon as
possible, and, at that time, simulate the interrupt. Using this method, the
network software always receives the interrupt in the proper VM context.
Thus, the network software should not need to be modified at all.

Notice also that the virtual device could take on some part of the network
functionality, thus bypassing the normal network software in some or all
cases. This would avoid the bottleneck of having to call the normal network
software in virtual mode; the virtual device could copy the data directly
to the target application's buffers, and so forth. This would also avoid
data-overrun problems when 386 enhanced-mode Windows is unable to switch to
the proper virtual machine in a reasonable amount of time because a virtual
device can access any VM's address space at any time even when the VM is
inactive. And finally, it could free up memory for non-Windows applications
by, in effect, moving the entire network into protected mode.

Most network software runs in conventional memory (the first 640K bytes of
memory) and therefore competes with non-Windows applications for memory. To
free the conventional memory otherwise occupied by the network software, it
is recommended that the network software be moved to a virtual device.


5.2.1.6 Virtualized Connections

386 enhanced-mode Windows maintains a complete set of current drive and
directory information for each VM. Network support may keep global
connections or provide for separate connections in each VM, as appropriate.
If the network support keeps global connections, it should also provide a
mechanism to allow each new VM to inherit the current connections in
Windows.

Some networks may choose to handle the virtualization themselves rather
than rely on a virtual device. By keeping track of the current virtual
machine identifier, the network can maintain a separate state for each VM
and manage these appropriately. The virtual device can inform the network
software when virtual machines are created and destroyed. The virtual
device can even manage instance data within the network software by
transparently inserting the appropriate data for the current
virtual-machine context.


5.2.1.7 Network-Control Blocks

The VNETBIOS device supports up to 4K of network-control blocks (NCB).
Although this number of NCBs should be adequate for most situations, the
limit can also be set with the NetHeapSize setting in the [Networks]
section of the SYSTEM.INI file.


5.2.2 Networks in Standard-Mode Windows

Standard-mode Windows does not provide the same multitasking environment as
386 enhanced-mode Windows, so the potential impact on existing network
software is not as great. Nevertheless, network software may need
modification or additional software to accommodate the following:

o   Asynchronous network requests

o   Application Programming Interface (API) mapping

o   Expanded Memory Specification (EMS) memory

The following sections discuss these topics.


5.2.2.1 Asynchronous Network Requests

Asynchronous network requests can corrupt data or code if the user switches
away from the non-Windows application that initiated the request before the
network has completed to it. Standard-mode Windows automatically prevents
the user from switching away from an application that uses asynchronous
NetBIOS calls.

This may require changes to both the MS-DOS Extender and the non-Windows
application support module (that is, WINOLDAP.) Both the MS-DOS Extender
and WINOLDAP include support specifically for NetBIOS. Unfortunately, these
modules are not easily adapted to support other network API.

Standard-mode Windows prevents switches from occurring during critical
sections. By default, MS-DOS functions, including network functions, are
considered critical sections.


5.2.2.2 API Mapping

Windows applications in standard-mode use protected-mode addresses. Network
drivers that rely on real-mode network software to carry out network
requests must translate protected-mode addresses in the requests to
real-mode addresses before passing the request on to the network software.

Windows translates the following APIs:

o   Standard MS-DOS functions, including network-related functions

o   Standard BIOS functions

o   Standard NetBIOS functions

If the network driver uses other real-mode functions to carry out a network
request, the driver or related software must translate the protected-mode
addresses to real-mode addresses.

Since many networks use additional functions, code to support the address
translation is required.


5.2.2.3 Expanded Memory

Some network software uses expanded memory to store portions of its own
code and data. This helps minimize conventional memory usage, but may be
incompatible with standard-mode use of memory.

On machines with expanded memory specification (EMS) hardware,
standard-mode Windows does not alter the EMS hardware. This means the EMS
memory continues to function and is available for use by Windows
applications and non-Windows applications. Furthermore, starting or
terminating standard-mode Windows does not disrupt the state of the EMS
memory, so memory-resident applications, such as network software, can
continue uninterrupted use of EMS memory.

On 80386 machines however, protected-mode EMS emulators are typically used
to provide EMS memory. Since EMS emulators are often protected-mode
software, standard-mode Windows cannot run unless it can turn the emulator
off. Standard-mode Windows can turn off certain expanded memory emulators
(including all the versions of Microsoft EMM386 and Compaq CEMM) provided
they have no open handles. In such cases, there will be no EMS memory
available while standard-mode Windows is running. Windows turns on the EMS
emulator when Windows exits.


5.2.3 Exported Functions

File Manager, Control Panel, and Print Manager use network driver
functions. To fully support these Windows applications, the network driver
should provide as many network functions as are applicable to the network.

The network driver must export all the functions defined in this chapter,
including the Enable and Disable functions. If there is no appropriate
action for a function to take, then the function should just return the
WN_NOT_SUPPORTED value. However, the Enable and Disable functions are
exceptions and return nothing.

The driver must export a WEP function. This should be exported by name
only, not by ordinal value. Windows calls this function when Windows is
about to remove the driver when closing down.


5.2.4 Reserved Ordinals

If the driver exports functions that are not on this list, then those
functions should have export ordinals greater than 500. The numbers below
500 are reserved for functions with prescribed ordinal values. For example,
the WNetDeviceMode dialog box callback function should have an ordinal
value above 500 so as not to conflict with any required ordinals defined in
future versions.


5.2.5 String Handling

All strings passed to the network driver may be assumed to be ANSI strings.
Similarly, all strings returned by the network driver should be ANSI
strings.


5.2.6 Passing Buffers

Functions, such as WNetGetConnection, WNetGetErrorText, and WNetGetUser,
copy data to a buffer supplied by Windows. Since Windows can not know the
size of the data before making the call, these functions return the
WN_MORE_DATA value if the complete data does not fit in the buffer.

To make a call, Windows allocates a buffer and passes its address to the
function. Windows also passes the address of a 16-bit variable containing
the buffer size. The function then copies as much of the requested data
structure as it can into the buffer. If it all fits, the function returns
successfully. However, if it does not, the data may be left incomplete, and
the function returns the WN_MORE_DATA value. In both cases, the function
sets the 16-bit variable to the number of bytes actually required by the
data structure. This way, if the buffer passed in was too small and the
function failed, the caller may allocate a new buffer of the required size
and call the function again.


5.2.7 Data Structures

All the data structures are a fixed size. They are allocated to a
contiguous array starting at the beginning of the buffer. When they need to
refer to variable-length strings, the data structures will contain pointers
in the form of WORD offsets into the buffer. All strings should be
null-terminated. The driver should allocate space in the buffer to store
these strings, starting at the end of the buffer and growing downward. When
there is insufficient room in the middle for one more structure and its
attendant strings, the driver stops adding data and returns the
WN_MORE_DATA value.


5.3 Function Reference

The following is a complete alphabetical listing of the network-driver
functions.

Disable

    VOID Disable(VOID)

The Disable function disables the network driver. Windows calls Disable
when it is closing down. It also calls Disable when Windows is preparing to
be suspended, for example, just prior to switching away to a non-Windows
application.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 34.

If a network driver needs to hook an interrupt, it should make such a hook
during the Enable function and remove it during the Disable function. This
would prevent the driver's hook routine from being called when Windows was
swapped out to disk.

Windows calls Disable before the calling the driver's WEP function.


See Also

Enable



Enable

    VOID Enable(VOID)

The Enable function enables the network driver. Windows calls Enable when
it loads the driver for the first time and when Windows resumes execution
after having been suspended, for example, after switching away from a
non-Windows application.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 33.

If a network driver needs to hook an interrupt, it should make such a hook
during the Enable function and remove it during the Disable function. This
would prevent the driver's hook routine from being called when Windows was
swapped out to disk.


See Also

Disable



WNetAbortJob

    WORD WNetAbortJob(szQueue, fh)
    LPSTR szQueue;
    WORD fh;

The WNetAbortJob function cancels a print job while the file handle is
still open.


Parameters

   szQueue
   Points to the null-terminated name of the local device.

   fh
   Identifies the handle returned by the WNetOpenJob function.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED   Security violation.

WN_BAD_HANDLE      File handle is invalid.

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 3.


See Also

WNetOpenJob, WNetCancelJob



WNetAddConnection

    WORD WNetAddConnection(szNetPath, szPassword, szLocalName)
    LPSTR szNetPath;
    LPSTR szPassword;
    LPSTR szLocalName;

The WNetAddConnection function redirects a local device (either a disk
drive or a printer port) to a shared device on a remote server.


Parameters

   szNetPath
   Points to a null-terminated string specifying the shared device or
   remote server.

   szPassword
   Points to a null-terminated string specifying the network password for
   the specified device or server.

   szLocalName
   Points to a null-terminated string specifying the local drive or device
   to be redirected. All szLocalName strings are case-independent. Only the
   drive names A: through Z: and the device names LPT1 through LPT3 are
   used.


Return Value

The return value is one of the following values.

Value                  Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED       Security violation.

WN_ALREADY_CONNECTED   Local device already connected to a remote resource.

WN_BAD_LOCALNAME       Invalid local device name.

WN_BAD_NETNAME         Invalid network resource name.

WN_BAD_PASSWORD        Invalid password.

WN_BAD_POINTER         Invalid pointer.

WN_NET_ERROR           Network error.

WN_NOT_SUPPORTED       Function not supported.

WN_OUT_OF_MEMORY       Out of memory.

WN_SUCCESS             Success.


Comments

The export ordinal for this function is 17.



WNetBrowseDialog

    WORD WNetBrowseDialog(hParent, nType, szPath)
    HWND hParent;
    WORD nType;
    LPSTR szPath;

The WNetBrowseDialog function displays one or more dialog boxes that enable
the user to select a network resource.


Parameters

   hParent
   Identifies the window that should be specified as the parent of the new
   dialog box.

   nType
   Specifies what kind of resource to look for; possible values include
   WNBD_CONN_DISKTREE and WNBD_CONN_PRINTQ.

   szPath
   Points to the buffer to receive the network path of the selected
   resource.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_VALUE       Invalid nType parameter value.

WN_CANCELLED       Cancelled at user's request.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.

WN_WINDOWS_ERROR   Windows function failed.


Comments

The export ordinal for this function is 15.

The function returns a string containing the complete network path
selected. It should be formatted so that it can be passed unaltered to the
WNetAddConnection function.

Programs that call this function must allocate a buffer of at least 128
characters in length.



WNetCancelConnection

    WORD WNetCancelConnection(szName, fForce)
    LPSTR szName;
    BOOL fForce;

The WNetCancelConnection function cancels a redirection.


Parameters

   szName
   Points to either the name of the redirected local device (such as LPT1)
   or a fully-qualified network path. If a network path is specified, the
   driver will cancel all the connections to that resource.

   fForce
   Specifies whether any open files or open print jobs on the device should
   be closed before the connection is cancelled. If the fForce parameter is
   FALSE and there are open files or jobs, the connection should not be
   cancelled. The function should return the WN_OPEN_FILES error value.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_VALUE       The szName parameter is not a valid local device or
                   network name.

WN_NET_ERROR       Network error.

WN_NOT_CONNECTED   The szName parameter is not a redirected local device or
                   currently accessed network resource.

WN_NOT_SUPPORTED   Function not supported.

WN_OPEN_FILES      Files are open and the fForce parameter was FALSE.
                   Connection was not cancelled.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 18.



WNetCancelJob

    WORD WNetCancelJob(szQueue, wJobID);
    LPSTR szQueue;
    WORD wJobID;

The WNetCancelJob function attempts to cancel a previously spooled network
job.


Parameters

   szQueue
   Points to a null-terminated string specifying the name of the print
   queue.

   wJobID
   Specifies the job identifier.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED   Security violation.

WN_BAD_JOBID       Job ID is invalid.

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_JOB_NOT_FOUND   No job with this ID found on this queue.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 6.


See Also

WNetOpenJob



WNetCloseJob

    WORD WNetCloseJob(fh, pidJob, szQueue)
    WORD fh;
    WORD FAR * pidJob;
    LPSTR szQueue;

The WNetCloseJob function finishes the processing of a spooled print job.


Parameters

   fh
   Identifies the spool file. It must have been previously created using
   the WNetOpenJob function.

   pidJob
   Points to a variable that receives a unique job identifier. If the
   driver cannot return the correct job identifier, it should return the
   constant value WN_NULL_JOBID (0x0000) indicating that the identifier is
   not available.

   szQueue
   Points to a null-terminated string specifying the normalized name of the
   network queue.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_HANDLE      File handle is invalid.

WN_BAD_POINTER     Invalid pointer.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 2.

The pidJob and szQueue parameters can be used to reference the job at any
later time.


See Also

WNetOpenJob



WNetConnectDialog

    WORD WNetConnectDialog(hwndParent, iType)
    HWND hwndParent;
    WORD iType;

The WNetConnectDialog function displays a driver-specific connection dialog
box.


Parameters

   hwndParent
   Identifies the owner of the dialog box.

   iType
   Specifies the type of device to be connected. The type can be one of the
   following values.

                Value                     Meaning
                -----------------------------------------------------------

                WNTYPE_DRIVE (0x0001)     A disk device.

                WNTYPE_FILE (0x0002)      A file.

                WNTYPE_PRINTER (0x0003)   A printer device.

                WNTYPE_COMM (0x0004)      A communications port. Reserved;
                                          do not use.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_CANCEL          User canceled (no new drives).

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Not enough memory to display the dialog box.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 25.

The network driver carries out all connection functions in this dialog box.
The network driver maintains the features of the previous connection list
and the permanent connection option. If this function is not supported, a
default dialog box will be used. This dialog box will maintain the previous
list and will remember permanent connections in a manner consistent with
the default implementation of the WNetRestoreConnection function.

WNetConnectDialog (together with WNetDisconnectDialog) allows either one or
two dialog boxes to be used to manage disk shares in Windows 3.1. If both
WNetConnectDialog and WNetDisconnectDialog are supported, the user will
have two File Manager menu commands for connecting and disconnecting. If
the driver implements only WNetConnectionDialog, a single menu command and
dialog box will be presented. The default case (no hooks implemented) uses
one dialog box. A single dialog box (hooked with WNetConnectionDialog) is
always used to manage printer devices.

If the driver returns WN_NOT_SUPPORTED, File Manager carries out the same
default operations as it would if the driver did not have the capability
bit for this dialog set.


See Also

WNetConnectionDialog, WNetDisconnectDialog, WNetRestoreConnection



WNetConnectionDialog

    WORD WNetConnectionDialog(hwndParent, iType)
    HWND hwndParent;
    WORD iType;

The WNetConnectionDialog function displays the dialog box used to both
connecting and disconnecting devices.


Parameters

   hwndParent
   Identifies the owner of the dialog box.

   iType
   Specifies the type of device to be connected. The parameter can be one
   of the following values.

                Value                     Meaning
                -----------------------------------------------------------

                WNTYPE_DRIVE (0x0001)     A disk device.

                WNTYPE_FILE (0x0002)      A file.

                WNTYPE_PRINTER (0x0003)   A printer device.

                WNTYPE_COMM (0x0004)      A communications port. Reserved;
                                          do not use.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_CANCEL          User cancelled (no new drives).

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Not enough memory to display the dialog.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 27.

The difference between this function and the WNetConnectDialog and
WNetDisconnectDialog functions is seen in the interfaces of Control Panel
and File Manager. Control Panel's Printer Setup dialog box contains a
Network button which displays the connection dialog box which may be used
to both create and delete network connections.

For Windows 3.1, File Manager calls WNetConnectDialog and
WNetDisconnectDialog for disks, and Control Panel calls
WNetConnectionDialog for printers. The network driver should nonetheless
check the iType parameter in case one or the other component is redesigned.
(The network driver does not need to implement support for both types of
devices in both dialogs; a capability bit will be reserved for indicating
support for additional device types).

If the driver returns WN_NOT_SUPPORTED, File Manager carries out the same
default operations as it would if the driver did not have the capability
bit set for this dialog box.


See Also

WNetConnectDialog, WNetDisconnectDialog



WNetDeviceMode

    WORD WNetDeviceMode(hParent)
    HWND hParent;

The WNetDeviceMode function displays a dialog box, permitting to user to
examine and modify network settings.


Parameters

   hParent
   Identifies the parent window for the dialog box.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.

WN_WINDOWS_ERROR   Windows function failed.


Comments

The export ordinal for this function is 14.

The network dialog box is often used to display information such as the
driver's name, driver's version number, version number of the installed
network software, and copyright notice. It is also used to let the user
choose settings for the network.

The user can call this dialog box from Control Panel.



WNetDirectoryNotify

    WORD WNetDirectoryNotify(hwnd, lpDir, wOper)
    HWND hwnd;
    LPSTR lpDir;
    WORD wOper;

The WNetDirectoryNotify function is used by File Manager to notify the
network driver of certain directory operations. Network drivers typically
use this function to carry out special operations for certain directories.


Parameters

   hwnd
   Identifies the owner of any dialog boxes displayed by this function.
   Although no dialog box is required, this function can display one if
   user input is needed.

   lpDir
   Points to a null-terminated string specifying a directory name. The
   names must be unambiguous, contain no wildcard characters and be fully
   qualified.

   wOper
   Specifies the operation. It can be one of the following values.

                Value            Meaning
                -----------------------------------------------------------

                WNDN_MKDIR (1)   File Manager will create a directory with
                                 the given name.

                WNDN_RMDIR (2)   File Manager will remove the directory.

                WNDN_MVDIR (3)   File Manager will rename the directory.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_CANCEL          The user cancelled the operation. Cancel the operation.

WN_CONTINUE        The network driver handled the operation. Proceed as if
                   the operation has been successfully handled.

WN_NOT_SUPPORTED   The network driver does not handle the given wOper
                   parameter in any special way. Treat the same as
                   WN_SUCCESS return value.

WN_SUCCESS         Success. Proceed with the operation.

For any other error value, the network driver supports the given wOper
parameter but some error occurred. In this case, File Manager reports the
error to the user, and treats the return value as if it were the WN_CANCEL
value.


Comments

The export ordinal for this function is 31.

File Manager calls WNetDirectoryNotify for local directories as well as
network directories.



WNetDisconnectDialog

    WORD WNetDisconnectDialog(hwndParent, iType)
    HWND hwndParent;
    WORD iType;

The WNetDisconnectDialog function displays a driver-specific disconnection
dialog box.


Parameters

   hwndParent
   Identifies the owner of the dialog box.

   iType
   Specifies the type of device to be disconnected. The parameter can be
   one of the following values.

                Value                     Meaning
                -----------------------------------------------------------

                WNTYPE_DRIVE (0x0001)     A disk device.

                WNTYPE_FILE (0x0002)      A file.

                WNTYPE_PRINTER (0x0003)   A printer device.

                WNTYPE_COMM (0x0004)      A communications port. Reserved;
                                          do not use.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_CANCEL          User cancelled (no drive disconnected).

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Not enough memory to display the dialog box.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 26.

If this function is not supported, a default dialog box will be used. When
a device is disconnected using the default dialog box, it is removed from
the list of permanent connections. If the network driver supports this
function, File Manager will not attempt to use WNetCancelConnection. The
implication here is that the remote name returned by WNetGetConnection is
only used for display purposes.


See Also

WNetCancelConnection, WNetConnectDialog, WNetGetConnection



WNetGetCaps

    WORD WNetGetCaps(nIndex)
    WORD nIndex;

The WNetGetCaps function retrieves information about the network driver,
such as the network functions it supports.


Parameters

   nIndex
   Specifies the capabilities to retrieve. The parameter can have the
   following values.

                Value                       Meaning
                -----------------------------------------------------------

                WNNC_SPEC_VERSION (0x0001)  Returns the major and minor
                                            version numbers of the network
                                            driver specification to which
                                            the driver conforms. The high
                                            and low bytes of the return
                                            value contain the major and
                                            minor version numbers,
                                            respectively. For Windows 3.1,
                                            it returns 0x030A.

                WNNC_NET_TYPE (0x0002)      Returns a network type. The
                                            high byte contains the network
                                            type, and the low byte may
                                            contain a subtype. The network
                                            type can be one of the
                                            following values:

                                   WNNC_NET_None (0x0000)
                                   WNNC_NET_MSNet (0x0100)
                                   WNNC_NET_LanMan (0x0200)
                                   WNNC_NET_NetWare (0x0300)
                                   WNNC_NET_Vines (0x0400)
                                   WNNC_NET_10NET (0x0500)
                                   WNNC_NET_Locus (0x0600)
                                   WNNC_NET_Sun PC NFS (0x0700)
                                   WNNC_NET_LANstep (0x0800)
                                   WNNC_NET_9TILES (0x0900)
                                   WNNC_NET_LANtastic (0x0A00)
                WNNC_DRIVER_VERSION         Returns the driver version
                (0x0003)                    number.

                WNNC_USER (0x0004)          Returns a value specifying
                                            which user functions are
                                            available. The return value can
                                            be WNNC_USR_GetUser (0x0001).

                WNNC_CONNECTION (0x0006)    Returns a value specifying
                                            which connection functions are
                                            available. It can be a
                                            combination of the following
                                            values:

                                   WNNC_CON_AddConnection (0x0001)
                                   WNNC_CON_CancelConnection (0x0002)
                                   WNNC_CON_GetConnections (0x0004)
                                   WNNC_CON_AutoConnect (0x0008)
                                   WNNC_CON_BrowseDialog (0x0010)
                                   WNNC_CON_RestoreConnection (0x0020)
                                            The WNNC_CON_AutoConnect bit
                                            does not represent a network
                                            driver function. Instead, it
                                            means that the network will
                                            support the standard MS-DOS
                                            Open File with Handle function
                                            (Interrupt 21h, Function 3Dh)
                                            for automatically connecting to
                                            network resources.

                WNNC_PRINTING (0x0007)      Returns a value specifying
                                            which printing functions are
                                            available. It can be a
                                            combination of the following
                                            values:

                                   WNNC_PRT_OpenJob (0x0002)
                                   WNNC_PRT_CloseJob (0x0004)
                                   WNNC_PRT_HoldJob (0x0010)
                                   WNNC_PRT_ReleaseJob (0x0020)
                                   WNNC_PRT_CancelJob (0x0040)
                                   WNNC_PRT_SetJobCopies (0x0080)
                                   WNNC_PRT_WatchQueue (0x0100)
                                   WNNC_PRT_UnwatchQueue (0x0200)
                                   WNNC_PRT_LockQueueData (0x0400)
                                   WNNC_PRT_UnlockQueueData (0x0800)
                                   WNNC_PRT_ChangeMsg (0x1000)
                                   WNNC_PRT_AbortJob (0x2000)
                                   WNNC_PRT_WriteJob (0x8000)
                                            The WNNC_PRT_ChangeMsg bit does
                                            not represent a network driver
                                            function, but rather means that
                                            the driver will send
                                            SP_QUEUECHANGED messages to
                                            Print Manager.

                WNNC_DIALOG (0x0008)        Returns a value specifying
                                            which dialog functions are
                                            available. It can be a
                                            combination of the following
                                            values:

                                   WNNC_DLG_DeviceMode (0x0001)
                                   WNNC_DLG_BrowseDialog (0x0002)
                                   WNNC_DLG_ConnectDialog (0x0004)
                                   WNNC_DLG_DisconnectDialog (0x0008)
                                   WNNC_DLG_ViewQueueDialog (0x0010)
                                   WNNC_DLG_PropertyDialog (0x0020)
                                   WNNC_DLG_ConnectionDialog (0x0040)
                WNNC_ADMIN (0x0009)         Returns a value specifying
                                            which administrative functions
                                            are available. It can be a
                                            combination of the following
                                            values:

                                   WNNC_ADM_GetDirectoryType (0x0001)
                                   WNNC_ADM_DirectoryNotify (0x0002)
                                   WNNC_ADM_LongNames (0x0004)
                WNNC_ERROR (0x000A)         Returns a value specifying
                                            which error functions are
                                            available. It can be a
                                            combination of the following
                                            values:

                                   WNNC_ERR_GetError (0x0001)
                                   WNNC_ERR_GetErrorInfo (0x0002)
                WNNC_PRINTMGREXT (0x000B)   Returns a value specifying
                                            whether Print Manager functions
                                            are available. If the functions
                                            are available, the function
                                            returns a WINNET version number
                                            in standard major or minor
                                            version number format.
                                            Otherwise, it returns zero.


Return Value

The return value is either a value or a bitmask specified by the nIndex
parameter, if successful. Otherwise, the return value is zero if the driver
doesn't support any functions.


Comments

The export ordinal for this function is 13.



WNetGetConnection

    WORD WNetGetConnection(szLocalName, lpRemoteName, nBufferSize)
    LPSTR szLocalName;
    LPSTR lpRemoteName;
    WORD FAR * nBufferSize;

The WNetGetConnection function returns the name of the network resource
associated with a redirected local device.


Parameters

   szLocalName
   Points to a null-terminated string specifying the name of the redirected
   local device.

   lpRemoteName
   Points to the buffer that receives the null-terminated name of the
   remote network resource.

   nBufferSize
   Points to a variable containing the maximum number of bytes the buffer
   pointed to by lpRemoteName can hold. The function sets this variable to
   the actual number of bytes copied to the buffer.


Return Value

The return value is one of the following.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_VALUE       The szLocalName parameter is not a valid local device.

WN_MORE_DATA       Buffer was too small.

WN_NET_ERROR       Network error.

WN_NOT_CONNECTED   The szLocalName parameter is not a redirected local
                   device.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 12.



WNetGetDirectoryType

    WORD WNetGetDirectoryType(lpName, lpType)
    LPSTR lpName;
    LPINT lpType;

The WNetGetDirectoryType function retrieves the type of a given directory.
The type is defined by the network driver and is used to modify the display
of the drive tree in File Manager. In this way, the network driver can show
special directories to the user.


Parameters

   lpName
   Points to a null-terminated string specifying a directory name. The
   names must be unambiguous, contain no wildcard characters and be fully
   qualified.

   lpType
   Points to a 16-bit variable to receive the directory type. The network
   driver copies the the type before returning. The type can be one of the
   following values.

                Value               Meaning
                -----------------------------------------------------------

                WNDT_NORMAL (0)     A local directory. File Manager
                                    displays the directory icon.

                WNDT_NETWORK (1).   A network directory. File Manager
                                    displays a special network folder icon.

   For Windows 3.1, File Manager will supply its own icon for all special
   network directories. If the network driver returns an error, File
   Manager assumes the specified directory is a local directory.


Return Value

The return value is one of the following.

Value          Meaning
---------------------------------------------------------------------------

WN_NET_ERROR   A network error occurred.

WN_SUCCESS     Success.


Comments

The export ordinal for this function is 30.

WNetGetDirectoryType is called from all directories that are displayed, not
only directories on the network.



WNetGetError

    WORD WNetGetError(nError)
    WORD FAR * nError;

The WNetGetError function returns the network status code from the last
network operation.


Parameters

   nError
   Points to a variable to receive the network status code.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_NO_ERROR        No error status available.

WN_NOT_SUPPORTED   Function is not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 19.

This is guaranteed to be correct only if the application calls immediately
after receiving the network driver error status. If another application is
given a chance to run, it may call the driver and the original extended
error condition be overwritten.


See Also

WNetGetErrorText



WNetGetErrorText

    WORD WNetGetErrorText(nError, lpBuffer, nBufferSize)
    WORD nError;
    LPSTR lpBuffer;
    WORD FAR * nBufferSize;

The WNetGetErrorText function returns a text description associated with a
network error code.


Parameters

   nError
   Specifies the network error code returned by WNetGetError.

   lpBuffer
   Points to the buffer to receive the text of the error.

   nBufferSize
   Points to a variable containing the maximum number of bytes the buffer
   pointed to the lpBuffer parameter can hold. The function sets the
   variable to the actual number bytes copied to the buffer.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_MORE_DATA       The buffer was too small.

WN_NET_ERROR       A network error occurred when attempting to get the text.

WN_NO_ERROR        No error status available.

WN_NOT_SUPPORTED   Function is not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 20.


See Also

WNetGetError



WNetGetPropertyText

    WORD WNetGetPropertyText(iButton, nPropSel, lpszName, lpButtonName,
                             cbButtonName, nType)
    WORD iButton;
    WORD nPropSel;
    LPSTR lpszName;
    LPSTR lpButtonName;
    WORD cbButtonName;
    WORD nType;

The WNetGetPropertyText function specifies the names of buttons to add to a
property dialog. The function copies the name of the button specified by
the iButton parameter to the buffer pointed to by the lpButtonName
parameter. If the function copies an empty string to the buffer, the system
removes the corresponding button and all succeeding buttons from the dialog
box.


Parameters

   iButton
   Specifies the zero-based button index. The index must be in the range 0
   through 5, that is, the Windows 3.1 File Manager supports at most six
   buttons.

   nPropSel
   Specifies which items to focus on. In Windows 3.1, the parameter can be
   one of the following values.

                Value           Meaning
                -----------------------------------------------------------

                WNPS_FILE (0)   Single file.

                WNPS_DIR (1)    Single directory.

                WNPS_MULT (2)   Multiple selection of files and/or
                                directories.

   lpszName
   Points to a zero-terminated string specifying one or more item names. In
   Windows 3.1, the items are files and directories, so item names are
   always filenames. The files must be unambiguous, contain no wildcard
   characters and be fully qualified.

   lpButtonName
   Points to the buffer to receive the name of the property button.

   cbButtonName
   Specifies the size (in bytes) of the buffer pointed to by the
   lpButtonName parameter.

   nType
   Specifies the item type. In Windows 3.1, only WNTYPE_FILE will be used.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_VALUE       The lpszName parameter takes an unexpected form.

WN_MORE_DATA       The given buffer is too small to fit the text of the
                   button.

WN_NOT_SUPPORTED   Property dialogs are not supported for the given object
                   type (the nType parameter).

WN_OUT_OF_MEMORY   Couldn't load string from resources.

WN_SUCCESS         The lpButtonName parameter can be used. If it points to
                   the empty string, no button corresponds to an index as
                   high as the iButton parameter.


Comments

The export ordinal for this function is 32.

In Windows 3.1, only File Manager calls this function. File Manager calls
the function just prior to each time it displays the dialog. After File
Manager displays the property dialog, File Manager calls the
WNetPropertyDialog function whenever the user chooses one of the added
buttons.


See Also

WNetPropertyDialog



WNetGetUser

    WORD WNetGetUser(szUser, nBufferSize)
    LPSTR szUser;
    WORD FAR * nBufferSize;

The WNetGetUser function retrieves the current user name.


Parameters

   szUser
   Points to the buffer to receive the current user name.

   nBufferSize
   Points to a variable containing the size of the buffer pointed to by the
   szUser parameter. The function copies the actual size (in bytes) of the
   user name to the variable.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_USER        Not logged in; no current user name.

WN_MORE_DATA       The buffer was too small.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 16.

If the network does not support a string that directly corresponds to the
MS-Net user name, the driver can either return an acceptable substitute or
not support this function.

If the function returns WN_MORE_DATA, the function also copies the size (in
bytes) of the buffer required to hold the complete user name.



WNetHoldJob

    WORD WNetHoldJob(szQueue, wJobID)
    LPSTR szQueue;
    WORD wJobID;

The WNetHoldJob function attempts to hold a previously spooled network job.


Parameters

   szQueue
   Points to a null-terminated string specifying the name of the print
   queue.

   wJobID
   Specifies the job identifier.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED   Security violation.

WN_BAD_JOBID       Job ID is invalid.

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_JOB_NOT_FOUND   No job with this ID found on this queue.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 4.

The exact effect depends upon the network. In most cases, the held job will
continue to move up in the queue until it is ready to print. However, it
will then not be allowed to print and will sit with the queue number of 1,
while other jobs move around it and are printed. This will last until the
job is released using the WNetReleaseJob function.


See Also

WNetOpenJob, WNetReleaseJob



WNetLockQueueData

    WORD WNetLockQueueData(szQueue, szUser, lplpQueueStruct)
    LPSTR szQueue;
    LPSTR szUser;
    LPQUEUESTRUCT FAR * lplpQueueStruct;

The WNetLockQueueData function locks a buffer, maintained by the driver,
that describes the state of the queue. (The structure can be created at
this time if it was not already available.) Print Manager calls this
function.


Parameters

   szQueue
   Points to a null-terminated name of a local or remote queue.

   szUser
   Points to a null-terminated user name. If the szUser parameter is not
   NULL, it indicates that Print Manager is only interested in jobs
   belonging to that user. If this parameter is NULL, Print Manager will
   assume that QUEUESTRUCT contains information about all jobs.

   lplpQueueStruct
   Points to a variable to receive the address (selector:offset) of a
   driver-supplied buffer. The buffer contains a single QUEUESTRUCT
   structure followed by zero or more JOBSTRUCT structures and the
   variable-length strings to which they refer. The number of JOBSTRUCT
   structures is specified by the pqJobcount member in QUEUESTRUCT. The
   structure has the following format:

                    typedef struct _queuestruct {
                        WORD pqName;        /* queue name (offset)            */
                        WORD pqComment;     /* queue comment string (offset)  */
                        WORD pqStatus;      /* queue status                   */
                        WORD pqJobcount;    /* number of JOBSTRUCTs following */
                        WORD pqPrinters;    /* number of printers for queue   */
                                            /*   (zero if not available)      */
                    } QUEUESTRUCT;

                    typedef QUEUESTRUCT FAR * LPQUEUESTRUCT;

Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected. device

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 10.

While Print Manager's lock is in effect, the queue data must not be
modified or moved. Each lock operation is completed by a matching unlock
operation.

If the queue status is WNPRQ_PROBLEM, which means that all the printers on
this queue have stopped, examining the job status for the first job in the
queue. The first job usually reveals the exact nature of the problem.
However, this may not be true if the queue is serviced by multiple printers
that could have different problems, or if the first job is paused and the
first nonpaused job is being held up by an error.


See Also

WNetUnlockQueueData



WNetOpenJob

    WORD WNetOpenJob(szQueue, szJobTitle, nCopies, pfh)
    LPSTR szQueue;
    LPSTR szJobTitle;
    WORD nCopies;
    WORD FAR * pfh;

The WNetOpenJob function initializes a print job for transmission across
the net. It copies a file handle to the buffer indicated by the pfh
parameter, which Print Manager can use to write to the spool file.


Parameters

   szQueue
   Points to a null-terminated string specifying either a redirected local
   device or a fully qualified network name of a print queue.

   szJobTitle
   Points to a null-terminated string specifying the job title. If the
   szJobTitle parameter is NULL, the driver may use any appropriate
   default.

   nCopies
   Specifies the number of copies to print.

   pfh
   Points to a variable that receives the file handle for the job.


Return Value

The return value is one of the following values.

Value                Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER       Invalid pointer.

WN_BAD_QUEUE         The szQueue parameter is not a valid net queue or
                     redirected device.

WN_CANT_SET_COPIES   Warning, printing one copy.

WN_NET_ERROR         Network error.

WN_NOT_SUPPORTED     Function not supported.

WN_OUT_OF_MEMORY     Out of memory.

WN_SUCCESS           Success.


Comments

The export ordinal for this function is 1.

On some networks, open print jobs will automatically be closed and printed
after some time-out period. It is the responsibility of the driver to make
sure that the network does not pause on open print jobs, even if the
application is inactive for long periods of time.


See Also

WNetCloseJob



WNetPropertyDialog

    WORD WNetPropertyDialog(hwndParent, iButton, nPropSel, lpszName, nType)
    HWND hwndParent;
    WORD iButton;
    WORD nPropSel;
    LPSTR lpszName;
    WORD nType;

The WNetPropertyDialog function carries out any driver-specific actions
needed to support customized buttons. A driver adds customized buttons to
the property dialog box using the WNetGetPropertyText function. The system
calls this function whenever the user clicks an added button.

Windows 3.1 calls this function for file and directory network properties
only.


Parameters

   hwndParent
   Identifies the parent window which owns the file property dialog.

   iButton
   Specifies the zero-based index of the button that was pressed.

   nPropSel
   Specifies which item(s) the property dialog should act on. In Windows
   3.1, it can be one of the following values.

                  Value           Meaning
                  ---------------------------------------------------------

                  WNPS_FILE (0)   Single file.

                  WNPS_DIR (1)    Single directory.

                  WNPS_MULT (2)   Multiple selection of files and/or
                                  directories.

   lpszName
   Points to a null-terminated string specifying one or more item names. In
   Windows 3.1, the items are files and directories, so item names are
   always filenames. The files must be unambiguous, contain no wildcard
   characters and be fully qualified.

   nType
   Specifies the item type. For Windows 3.1, only WNTYPE_FILE can be used.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_VALUE       Some parameter takes an unexpected form or value.

WN_NET_ERROR       Some other network error occurred.

WN_OUT_OF_MEMORY   Not enough memory to display the dialog.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 29.

The WNetPropertyDialog function is only called on sets of properties for
which WNetGetPropertyText has assigned a button name.


See Also

WNetGetPropertyText



WNetReleaseJob

    WORD WNetReleaseJob(szQueue, wJobID)
    LPSTR szQueue;
    WORD wJobID;

The WNetReleaseJob function attempts to release a previously held network
job.


Parameters

   szQueue
   Points to a null-terminated string specifying the name of the print
   queue.

   wJobID
   Specifies the job identifier.


Return Value

The return value is one of the following values.

Return Value       Description
---------------------------------------------------------------------------

WN_ACCESS_DENIED   Security violation.

WN_BAD_JOBID       Job ID is invalid.

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_JOB_NOT_FOUND   No job with this ID found on this queue.

WN_JOB_NOT_HELD    The job is not held.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 5.


See Also

WNetHoldJob, WNetOpenJob



WNetRestoreConnection

    WORD WNetRestoreConnection(hwndParent, lpszDevice)
    HWND hwndParent;
    LPSTR lpszDevice;

The WNetRestoreConnection function reconnects one or more permanently
connected devices.


Parameters

   hwndParent
   Identifies the window to be used as the owner of any dialog or message
   boxes the network driver creates.

   lpszDevice
   Points to a null-terminated device name, such as for a disk or a
   printer. If this parameter is NULL, all devices are to be reconnected.
   If this parameter is 1, WNetRestoreConnection performs any
   initialization actions required by the driver and then reconnects all
   devices.

   File Manager calls this function with the 1 value exactly once during
   its initialization, and does not make any calls with the NULL value.


Return Value

The return value is one of the following values.

Value                  Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED       Permission violation.

WN_ALREADY_CONNECTED   The device is already connected.

WN_BAD_PASSWORD        The user supplied an inaccurate password.

WN_CANCELLED           The user cancelled the reconnection when prompted.

WN_CONTINUE            A failure occurred, but the network driver has
                       already reported the error to the user, and File
                       Manager should not post a message box. The device is
                       not valid and the File Manager should not access it.

WN_NET_ERROR           A network error has occurred.

WN_NOT_SUPPORTED       The driver does not support permanant connections.

WN_OUT_OF_MEMORY       Out of memory.

WN_SUCCESS             The device is reconnected.


Comments

The export ordinal for this function is 23.

During system initialization, the return value is ignored and the network
driver should report all errors to the user.

If a connection exists, this function should not override it.

If a connection cannot be reestablished, an error is returned, but the
device is not disconnected (that is, the connection is still remembered).

If this function is not supported, a minimum level of functionality will be
implemented by Windows, which will read a list of connections and attempt
to connect to them using WNetAddConnection.


See Also

WNetAddConnection



WNetSetJobCopies

    WORD WNetSetJobCopies(szQueue, wJobID, nCopies)
    LPSTR szQueue;
    WORD wJobID;
    WORD nCopies;

The WNetSetJobCopies function attempts to change the number of copies of a
previously spooled job.


Parameters

   szQueue
   Points to a null-terminated string specifying the name of the print
   queue.

   wJobID
   Specifies the job identifier.

   nCopies
   Specifies the number of copies to print. If the number is zero, the
   function will return an error code and will have no effect. If the
   number is too great for the queue to support, the number is changed to
   the largest one possible.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED   Security violation.

WN_BAD_JOBID       Job ID is invalid.

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_BAD_VALUE       Invalid number of copies.

WN_JOB_NOT_FOUND   No job with this ID found on this queue.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 7.


See Also

WNetOpenJob



WNetUnlockQueueData

    WORD WNetUnlockQueueData(szQueue)
    LPSTR szQueue;

The WNetUnlockQueueData function informs the driver that Print Manager is
no longer examining a block of queue data. The driver is free to
deallocate, reallocate, move, or modify the queue information at this
point.


Parameters

   szQueue
   Points to a null-terminated name of a network printer queue and is
   either a redirected local name or a remote name. This device should have
   been previously specified in a call to WNetWatchQueue.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 11.


See Also

WNetLockQueueData



WNetUnwatchQueue

    WORD WNetUnwatchQueue(szLocal)
    LPSTR szLocal;

The WNetUnwatchQueue function directs the driver to stop posting
notification messages. The driver may assume that watched queues will be
cancelled before Print Manager terminates.


Parameters

   szLocal
   Points to a null-terminated name of a local device.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_BAD_POINTER     Invalid pointer.

WN_BAD_QUEUE       The szQueue parameter is not a valid net queue or
                   redirected device.

WN_NET_ERROR       Network error.

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Out of memory.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 9.



WNetViewQueueDialog

    WORD WNetViewQueueDialog(hwndParent, lpszQueue)
    HWND hwndParent;
    LPSTR lpszQueue;

The WNetViewQueueDialog function displays a driver-specific network queue
dialog box.


Parameters

   hwndParent
   Identifies the owner of the dialog box.

   lpszQueue
   Points to a null-terminated string specifying the queue to view. If this
   parameter is NULL, the user must use the dialog box to specify the
   network printer to view.


Return Value

The return value is one of the following values.

Value              Meaning
---------------------------------------------------------------------------

WN_NOT_SUPPORTED   Function not supported.

WN_OUT_OF_MEMORY   Not enough memory to display the dialog.

WN_SUCCESS         Success.


Comments

The export ordinal for this function is 28.



WNetWatchQueue

    WORD WNetWatchQueue(hWnd, szLocal, szUser, nQueue)
    HWND hWnd;
    LPSTR szLocal;
    LPSTR szUser;
    WORD nQueue;

The WNetWatchQueue function instructs the driver to post messages to Print
Manager whenever the specified remote queue changes status. Print Manager
watches each redirected device or any active printer ports specified in
Control Panel.


Parameters

   hWnd
   Identifies the window that should be notified when the status of a job
   in the queue changes.

   szLocal
   Points to a null-terminated name of a local device (such as LPT1) that
   has been redirected to a network print queue.

   szUser
   Points to a null-terminated user name. If the szUser parameter is not
   NULL, the function only notifies Print Manager of changes involving jobs
   that belong to that user name.

   nQueue
   Specifies an arbitrary value to be used as the wParam value when
   notifying Print Manager of changes to the queue. This value allows Print
   Manager to determine which queue to refresh.


Return Value

The return value is one of the following values.

Value               Meaning
---------------------------------------------------------------------------

WN_ALREADY_LOCKED   Local device already being watched.

WN_BAD_LOCALNAME    Invalid local device name or local device not
                    redirected.

WN_BAD_POINTER      Invalid pointer.

WN_BAD_VALUE        Invalid window handle.

WN_NET_ERROR        Network error.

WN_NOT_SUPPORTED    Function not supported.

WN_OUT_OF_MEMORY    Out of memory.

WN_SUCCESS          Success.


Comments

The export ordinal for this function is 8.



WNetWriteJob

    WORD WNetWriteJob(hJob, lpData, lpcbData)
    HANDLE hJob;
    LPSTR lpData;
    LPINT lpcbData;

The WNetWriteJob function writes to a print job opened using the
WNetOpenJob function.


Parameters

   hJob
   Identifies the print job. It must have been previously created using the
   WNetOpenJob function. This handle does not need to be a file handle; it
   may now be any 16-bit number defined by the network driver.

   lpData
   Points to the data buffer.

   lpcbData
   Points to the variable containing the buffer size, in bytes. The network
   driver updates this value to the number of bytes actually written to the
   print job.


Return Value

The return value is one of the following values.

Value          Meaning
---------------------------------------------------------------------------

WN_NET_ERROR   A network error occurred.

WN_SUCCESS     At least one byte was successfully written to the print job.


Comments

The export ordinal for this function is 24.

If WNetWriteJob is not supported by the network driver, Windows will
continue to assume that the handle returned by WNetOpenJob is a file handle
and use the MS-DOS write handle function to output data to the print job.

This function is not used in the current version of Windows.


See Also

WNetOpenJob


5.4 Long-Filename Function Reference

The following is a complete alphabetical listing of the long-filename
functions for the network driver functions.



LFNCopy

    WORD LFNCopy(lpSource, lpDest, lpfnAbort)
    LPSTR lpSource;
    LPSTR lpDest;
    FARPROC lpfnAbort;

The LFNCopy function copies a file from the lpSource parameter to the
lpDest parameter.


Parameters

   lpSource
   Points to a null-terminated string specifying the full path of the file
   to copy.

   lpDest
   Points to a null-terminated string specifying either the full path of
   the file to be created or the full name of the directory to receive the
   file.

   lpfnAbort
   Points to the appropriate callback function to terminate a copy
   operation.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

2       File not found.

5       Access denied.

17      Not same device.


Comments

The export ordinal for this function is 105.

The LFNCopy function must support intra- and inter-volume copies for both
long filename servers and standard MS-DOS filenaming conventions for
volumes, including local drives. If the user is attempting to copy a file
with a long name to a volume that supports only standard names, File
Manager will prompt the user to enter a file specification consistent with
standard naming conventions. Therefore, the network DLL does not need to
map long names to standard names.

The function specified by the lpfnAbort parameter may be called during long
copy operations if the network driver wishes to allow the copy operation to
be terminated in the middle of a file. This callback function will return
TRUE if the user cancels the operation.


See Also

LFNMove



LFNDelete

    WORD LFNDelete(lpFile)
    LPSTR lpFile;

The LFNDelete function deletes the file specified by the lpFile parameter.


Parameters

   lpFile
   Points to a null-terminated string specifying the name of the file to
   delete.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

2       File not found.

3       Path not found.

5       Access denied.


Comments

The export ordinal for this function is 107.


See Also

LFNMove



LFNFindClose

    WORD LFNFindClose(hDir)
    HANDLE hDir;

The LFNFindClose function ends the search for files in a given directory.
It deallocates the search handle specified by the hDir parameter,
originally returned by the LFNFindFirst function.


Parameters

   hDir
   Identifies is the directory to search. The handle must have been
   previously created using the LFNFindFirst function.


Return Value

The return value is zero, if successful. Otherwise, it is a nonzero value.


Comments

The export ordinal for this function is 102.


See Also

LFNFindFirst, LFNFindNext



LFNFindFirst

    WORD LFNFindFirst(lpFileSpec, wAttr, lpnEntries, lphDir, cbBuffer, lpFindBuf)
    LPSTR lpFileSpec;
    WORD wAttr;
    LPINT lpnEntries;
    LPINT lphDir;
    WORD cbBuffer;
    PFINDFILEBUF2 lpFindBuf;

The LFNFindFirst function searches for the first occurrence of a file
matching the specification in the lpFileSpec parameter.


Parameters

   lpFileSpec
   Points to a null-terminated string specifying the name of a file or
   files to search for.

   wAttr
   Specifies what types of files (directories, hidden files, and so on)
   should be included in the file enumeration. It is defined the same way
   as the corresponding parameter to the MS-DOS Find First File (Interrupt
   21h, Function 4Eh) function.

   lpnEntries
   Points to a 16-bit variable containing the maximum number of files to
   return. Upon successful return, this 16-bit variable is updated with the
   number of files actually returned in the buffer.

   lphDir
   Points to a 16-bit variable that receives a handle. The handle is used
   on subsequent calls to the LFNFindNext function. This handle can be
   freed using the LFNFindClose function.

   cbBuffer
   Specifies the size (in bytes) of the structure pointed to by the
   lpFindBuf parameter.

   lpFindBuf
   Points to a FILEFINDBUF2 structure that receives information about
   files. The FILEFINDBUF2 structure has the following form:

         typedef struct _FILEFINDBUF2 {  /* findbuf2 */
             FDATE   fdateCreation;
             FTIME   ftimeCreation;
             FDATE   fdateLastAccess;
             FTIME   ftimeLastAccess;
             FDATE   fdateLastWrite;
             FTIME   ftimeLastWrite;
             ULONG   cbFile;
             ULONG   cbFileAlloc;
             USHORT  attrFile;
             ULONG   cbList;
             UCHAR   cchName;
             CHAR    achName[CCHMAXPATHCOMP];
         } FILEFINDBUF2;

Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

2       File not found.

3       Path not found.

18      No more files to be found.


Comments

The export ordinal for this function is 100.


See Also

LFNFindClose, LFNFindNext



LFNFindNext

    WORD LFNFindNext(hDir, lpnEntries, cbBuffer, lpFindBuf)
    HANDLE hDir;
    LPINT lpnEntries;
    WORD cbBuffer;
    PFILEFINDBUF2 lpFindBuf;

The LFNFindNext function carries out the MS-DOS Find Next File (Interrupt
21h, Function 4Fh) function.


Parameters

   hDir
   Identifies is the directory to search. The handle must have been
   previously created using the LFNFindFirst function.

   lpnEntries
   Points to a 16-bit variable containing the number of entries to return.
   The function updates the value with the number of structures actually
   returned.

   cbBuffer
   Specifies the size (in bytes) of the FILEFINDBUF2 structure.

   lpFindBuf
   Points to a FILEFINDBUF2 structure that receives the file information.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

2       File not found.

3       Path not found.

12      No more files to be found.


Comments

The export ordinal for this function is 101.


See Also

LFNFindFirst, LFNFindClose



LFNGetAttributes

    WORD LFNGetAttributes(lpFile, lpAttr)
    LPSTR lpFile;
    LPINT lpAttr;

The LFNGetAttributes function retrieves a field of attribute bits into the
16-bit variable specified by the lpAttr parameter for the file specified by
the lpFile parameter.


Parameters

   lpFile
   Points to a null-terminated string specifying the name of a file.

   lpAttr
   Points to a 16-bit variable that receives the attributes of the
   specified file. The attributes can be a combination of the following
   values.

     Value   Meaning
     ----------------------------------------------------------------------

     0       File can be read from or written to.

     1       File can be read but not written to.

     2       File or directory is hidden and does not appear in a directory
             listing.

     4       File or directory is a system file.

     8       Filename is the current volume label for the media.

     16      Filename identifies a directory, not a file.

     32      File has been archived.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

1       Invalid function.

2       File not found.

3       Path not found.

5       Access denied.


Comments

The export ordinal for this function is 103.


See Also

LFNSetAttributes



LFNGetVolumeLabel

    WORD LFNGetVolumeLabel(iDrive, lpLabel)
    WORD iDrive;
    LPSTR lpLabel;

The LFNGetVolumeLabel function returns the volume label of the drive
specified by the iDrive parameter.


Parameters

   iDrive
   Specifies a one-based drive number. The parameter is 1 for drive A, 2
   for drive B, and so on.

   lpLabel
   Points to the buffer that receives the volume label. The buffer length
   must be at least 12 bytes.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

1       Invalid function.

2       File not found.

5       Access denied.


Comments

The export ordinal for this function is 110.


See Also

LFNSetVolumeLabel



LFNMKDir

    WORD LFNMKDir(lpDir)
    LPSTR lpDir;

The LFNMKDir function creates the directory specified by the lpDir
parameter.


Parameters

   lpDir
   Points to a null-terminated string specifying the name of the directory
   to create.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

2       File not found.

3       Path not found.

5       Access denied.


Comments

The export ordinal for this function is 108.


See Also

LFNRMDir



LFNMove

    WORD LFNMove(lpSource, lpDest)
    LPSTR lpSource;
    LPSTR lpDest;

The LFNMove function moves or renames the file specified by the lpSource
parameter to the path specified by the lpDest parameter. This will always
be intravolume on a network drive.


Parameters

   lpSource
   Points to a null-terminated string specifying the full path of the file
   to move.

   lpDest
   Points to a null-terminated string specifying either the full name of
   the directory to receive the moved file or the new name for the file. If
   you are renaming the file, the path must include the new name of the
   file.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

2       Path not found.

5       Access denied.

17      Not same device.


Comments

The export ordinal for this function is 106.


See Also

LFNCopy



LFNParse

    WORD LFNParse(lpFile, lpMask, lpResult)
    LPSTR lpFile;
    LSPTR lpMask;
    LPSTR lpResult;

The LFNParse function parses a long filename.


Parameters

   lpFile
   Points to a null-terminated string specifying the path to parse. The
   path can consist of long names, or a combination of both standard and
   long filenaming conventions.

   lpMask
   Points to null-terminated string specifying one or more components of a
   full path. The function uses these components as substitutes when
   forming the resulting path. Furthermore, if the last component of the
   lpMask parameter contains wildcards, the wildcards are combined with the
   filename component of the lpFile parameter to produce the resulting
   filename. If lpMask is NULL, the full path is copied to the lpResult
   parameter without substitution.

   lpResult
   Points to the buffer to receive the resulting path. If the lpResult
   parameter is NULL, the function returns the resulting path type but does
   not copy the path itself.


Return Value

The function returns one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       All components of the fully qualified path, including filename,
        conform to the MS-DOS standard filename specification. This means
        the file is accessible by MS-DOS and Windows applications.

1       The path conforms to the MS-DOS standard filename specification
        except for case.

2       The filename is a long filename.


Comments

The export ordinal for this function is 112.

The return value is 1 when a user types MS-DOS standard filenames in
lowercase. In general, these names should be mapped to uppercase unless
explicitly quoted.



LFNRMDir

    WORD LFNRMDir(lpDir)
    LPSTR lpDir;

The LFNRMDir function removes the directory specified by the lpDir
parameter.


Parameters

   lpDir
   Points to a null-terminated string specifying the name of the directory
   to remove.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

3       Path not found.

16      Current directory.


Comments

The export ordinal for this function is 109.


See Also

LFNMKDir



LFNSetAttributes

    WORD LFNSetAttributes(lpFile, wAttr)
    LPSTR lpFile;
    WORD wAttr;

The LFNSetAttributes function sets the attributes of a given file to the
bitfield specified by the wAttr parameter. This function may modify hidden,
system, read only, and archive but not volume or directory.


Parameters

   lpFile
   Points to a null-terminated string specifying the name of a file.

   wAttr
   Specifies the attributes for the specified file. The attributes can be a
   combination of the following values.

     Value   Meaning
     ----------------------------------------------------------------------

     0       File can be read from or written to.

     1       File can be read from but not written to.

     2       File is hidden and does not appear in a directory listing.

     4       File is a system file.

     32      File has been archived.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

1       Invalid function.

2       File not found.

3       Path not found.

5       Access denied.


Comments

The export ordinal for this function is 104.


See Also

LFNGetAttributes



LFNSetVolumeLabel

    WORD LFNSetVolumeLabel(iDrive, lpLabel)
    WORD iDrive;
    LPSTR lpLabel;

The LFNSetVolumeLabel function sets the volume label of the drive specified
by the iDrive parameter.


Parameters

   iDrive
   Specifies a one-based drive number. The parameter is 1 for drive A, 2
   for drive B, and so on.

   lpLabel
   Points to the buffer that contains the new volume label. The buffer
   length must be at least 12 bytes.


Return Value

The return value is one of the following values.

Value   Meaning
---------------------------------------------------------------------------

0       Success.

1       Invalid function.

2       File not found.

5       Access denied.


Comments

The export ordinal for this function is 111.

Support for this function is not critical, but is included for
completeness. A driver may return the value for returned value that is
denied access so users cannot affect network volume labels.


See Also

LFNGetVolumeLabel



LFNVolumeType

    WORD LFNVolumeType(iDrive, lpwType)
    WORD iDrive;
    LPINT lpwType;

The LFNVolumeType function specifies whether a given volume supports MS-DOS
standard filenaming conventions or long filenames.


Parameters

   iDrive
   Specifies a one-based drive number. The parameter is 1 for drive A, 2
   for drive B, and so on.

   lpwType
   Points to a 16-bit variable that receives the volume type. The type can
   be one of the following values.

     Value              Meaning
     ----------------------------------------------------------------------

     VOLUME_STANDARD    MS-DOS standard filenaming conventions volume. 8
                        characters for the filename, and 3 for the
                        extension.

     VOLUME_LONGNAMES   Long-filename volumes.


Return Value

The return value is zero if successful. Otherwise, it returns a nonzero
value.


Comments

The export ordinal for this function is 113.


5.5 Structure Reference

The following is a complete alphabetical listing of the network-driver
structures.



FDATE

    typedef struct _FDATE {         /* fdate */
        unsigned day     : 5;
        unsigned month   : 4;
        unsigned year    : 7;
    } FDATE;

Members

   day
   Specifies the day of the month. It must be a value in the range 1 to 31.

   month
   Specifies the month. It must be a value in the range 1 (for January) to
   12 (for December).

   year
   Specifies the year.


See Also

LFNFindFirst



FILEFINDBUF2

    typedef struct _FILEFINDBUF2 {  /* findbuf2 */
        FDATE   fdateCreation;
        FTIME   ftimeCreation;
        FDATE   fdateLastAccess;
        FTIME   ftimeLastAccess;
        FDATE   fdateLastWrite;
        FTIME   ftimeLastWrite;
        ULONG   cbFile;
        ULONG   cbFileAlloc;
        USHORT  attrFile;
        ULONG   cbList;
        UCHAR   cchName;
        CHAR    achName[CCHMAXPATHCOMP];
    } FILEFINDBUF2;
The FILEFINDBUF2 structure contains file information.


Members

   fdateCreation
   Specifies the date the file was created.

   ftimeCreation
   Specifies the time the file was created.

   fdateLastAccess
   Specifies the date the file was last opened.

   ftimeLastAccess
   Specifies the time the file was last opened.

   fdateLastWrite
   Specifies the date the file was last written to.

   ftimeLastWrite
   Specifies the time the file was last written to.

   cbFile
   Specifies the size (in bytes) of the file.

   cbFileAlloc
   Specifies the number of bytes allocated for the file on the storage
   device.

   attrFile
   Specifies the file attributes. This member can be a combination of the
   following values.

     Value   Meaning
     ----------------------------------------------------------------------

     0       File can be read from or written to.

     1       File can be read from but not written to.

     2       File or directory is hidden and does not appear in a directory
             listing.

     4       File or directory is a system file.

     8       Filename is the current volume label for the media.

     16      Filename identifies a directory not a file.

     32      File has been archived.

   cbList
   Specifies the size (in bytes) of the buffer for extended attributes.

   cchName
   Specifies the number of characters in the filename.

   achName
   Specifies the name of the file. This member contains a null-terminated
   filename having the number of characters specified by the cchName
   member.


Comments

File Manager uses the values in the fdateLastWrite and ftimeLastWrite
members when it displays the date and time for a given file; it ignores the
other date and time values. Also, File Manager use the cbFile member as the
file size, ignoring cbFileAlloc and cbList.

File Manager assumes that the achName member is truncated to just the
length of the filename and the zero terminator. For example, if another
FILEFINDBUF2 structure immediately follows the first, the pointer to the
second structure is computed as follows:

    (PFILEFINDBUF2)((LPSTR)lpFindBuf + sizeof(FILEFINDBUF2) -
    CCHMAXPATHCOMP + lpFindBuf->cchName + 1)

See Also

LFNFindFirst



FTIME

    typedef struct _FTIME {         /* ftime */
        unsigned twosecs : 5;
        unsigned minutes : 6;
        unsigned hours   : 5;
    } FTIME;

Members

   twosecs
   Specifies the seconds as if divided by 2. It must be in the range 0 to
   29. A value of 1 represents 2 seconds, a value of 29 represents 59
   seconds.

   minutes
   Specifies the minute in the hour. It must be a value in the range 0 to
   59.

   hours
   Specifies the hour in the day. It must be a value in the range 0 to 23.


See Also

LFNFindFirst



JOBSTRUCT

    typedef struct _jobstruct {
        WORD  pjId;             /* job ID                         */
        WORD  pjUsername;       /* submitting user name (offset)  */
        WORD  pjParms;          /* implementation string (offset) */
        WORD  pjPosition;       /* position of job in the queue   */
        WORD  pjStatus;         /* job status                     */
        DWORD pjSubmitted;      /* time when job was submitted    */
                                /*   (from 1970-1-1 in seconds)   */
        DWORD pjSize;           /* job size in bytes              */
                                /*   (-1L means not available)    */
        WORD  pjCopies;         /* number of copies               */
                                /*   (0 means not available)      */
        WORD  pjComment;        /* comment for this job (offset)  */
    } JOBSTRUCT;
The JOBSTRUCT structure contains information about print jobs.


Members

   pjId
   Specifies the job identifier.

   pjUsername
   Specifies the offset (relative to the beginning of the QUEUESTRUCT
   structure containing this JOBSTRUCT structure) to the submitting user
   name.

   pjParms
   Specifies the offset (relative to the beginning of the QUEUESTRUCT
   structure containing this JOBSTRUCT structure) to the implementation
   string.

   pjPosition
   Specifies the position of job in the queue.

   pjStatus
   Specifies the job status. It can be a combination of one Queue Status
   value and one Device Status value, as described by the following.

   Queue Status

     Value                        Meaning
     ----------------------------------------------------------------------

     WNPRJ_QS_QUEUED (0x0000)     Job queued.

     WNPRJ_QS_PAUSED (0x0001)     Job paused.

     WNPRJ_QS_SPOOLING (0x0002)   Job spooling.

     WNPRJ_QS_PRINTING (0x0003)   Job printing.

   Device Status

     Value                           Meaning
     ----------------------------------------------------------------------

     WNPRJ_DS_COMPLETE (0x0008)      Complete.

     WNPRJ_DS_INTERV (0x0010)        Intervention required.

     WNPRJ_DS_ERROR (0x0020)         Printer error.

     WNPRJ_DS_DESTOFFLIN (0x0040)    Printer offline.

     WNPRJ_DS_DESTPAUSED (0x0080)    Printer paused.

     WNPRJ_DS_NOTIFY (0x0100)        Notify owner.

     WNPRJ_DS_DESTNOPAPER (0x0200)   Printer out of paper.

     WNPRJ_DS_DESTFORMCHG (0x0400)   Form change required.

     WNPRJ_DS_DESTCRTCHG (0x0800)    cartridge change required.

     WNPRJ_DS_DESTPENCHG (0x1000)    Pen change required.

   pjSubmitted
   Specifies the time when job was submitted in seconds since January 1,
   1970.

   pjSize
   Specifies the job size in bytes. If it is -9, the size is not available.

   pjCopies
   Specifies the number of copies. If it is zero, the number is not
   available.

   pjComment
   Specifies the offset (relative to the beginning of the QUEUESTRUCT
   structure containing this JOBSTRUCT structure) to the comment for this
   job.


Comments

For more information about the mechanism that stores the strings referenced
by JOBSTRUCT, see Section 5.2.6, Passing Buffers, earlier in this chapter.
For example, assuming that lpQS is the LPQUEUESTRUCT returned by
WNetLockQueueData, the expression

    (LPSTR) lpQS + lpQS -> pqComment
points to the queue comment. All offsets are relative to the beginning of
the buffer, not the beginning of an individual JOBSTRUCT structure.


See Also

WNetLockQueueData



QUEUESTRUCT

    typedef struct _queuestruct {
        WORD pqName;        /* queue name (offset)            */
        WORD pqComment;     /* queue comment string (offset)  */
        WORD pqStatus;      /* queue status                   */
        WORD pqJobcount;    /* number of JOBSTRUCTs following */
        WORD pqPrinters;    /* number of printers for queue   */
                            /*   (zero if not available)      */
    } QUEUESTRUCT;

    typedef QUEUESTRUCT FAR * LPQUEUESTRUCT;
The QUEUESTRUCT structure contains information about a print queue.


Members

   pqName
   Specifies the offset (relative to the beginning of the structure) to the
   null-terminated queue name.

   pqComment
   Specifies the offset (relative to the beginning of the structure) to the
   null-terminated queue comment string.

   pqStatus
   Specifies the queue status. It can one of the following values.

     Value                    Meaning
     ----------------------------------------------------------------------

     WNPRQ_ACTIVE (0x0000)    Queue is active.

     WNPRQ_PAUSE (0x0001)     Queue is paused.

     WNPRQ_ERROR (0x0002)     Network error.

     WNPRQ_PENDING (0x0003)   Queue has been deleted. The queue remains
                              until the current jobs are done, but no new
                              jobs may be started.

     WNPRQ_PROBLEM (0x0004)   All printers are stopped.

   pqJobcount
   Specifies the number of JOBSTRUCT structures immediately following the
   QUEUESTRUCT structure.

   pqPrinters
   Specifies the number of printers for the queue. It is zero if not
   available.


Comments

For more information about the mechanism that stores the string referenced
by QUEUESTRUCT, see Section 5.2.6, Passing Buffers, earlier in this
chapter. For example, assuming that lpQS is the LPQUEUESTRUCT returned by
WNetLockQueueData, the expression

    (LPSTR) lpQS + lpQS -> pqComment
points to the queue comment. All offsets are relative to the beginning of
the buffer, not the beginning of an individual JOBSTRUCT structure.


See Also

WNetLockQueueData


5.6 Return Values

Most network driver functions return zero if successful and unique nonzero
values for various error conditions. The following is a list of the
possible return values.

Value                  Meaning
---------------------------------------------------------------------------

WN_ACCESS_DENIED       Security violation.

WN_ALREADY_CONNECTED   Local device already connected to a remote resource.

WN_ALREADY_LOCKED      Queue specified is already locked; from LockQueue
                       function.

WN_BAD_HANDLE          Not a valid file handle, or handle not to network
                       print file opened by driver.

WN_BAD_JOBID           Invalid job ID.

WN_BAD_LOCALNAME       Invalid local device name.

WN_BAD_NETNAME         Network name is invalid.

WN_BAD_PASSWORD        Incorrect password specified.

WN_BAD_POINTER         Invalid pointer specified.

WN_BAD_QUEUE           Name given does not correspond to a network queue
                       name or a redirected local device.

WN_BAD_USER            Invalid user name specified.

WN_BAD_VALUE           Invalid value specified.

WN_CANCELLED           Operation canceled at user's request.

WN_CANT_SET_COPIES     Warning: cannot set number of copies, printing just
                       one.

WN_CONNECTION_CLOSED   Indicates that a permanently maintained connection
                       is defined for the device, but that the device is
                       not currently connected to any network resource.
                       This return value is defined for those network
                       drivers that export the WNetRestoreConnection
                       function. The only way a permanent connection can be
                       closed is if the device could not be connected when
                       starting up.

WN_CONTINUE            Used by functions to indicate a situation distinct
                       from both WN_CANCELLED and WN_SUCCESS where File
                       Manager does not need to post a message to the user.

WN_DEVICE_ERROR        Specifies that a connection exists on the given
                       device, but that the connection is in an error state
                       and should be disconnected and reconnected before it
                       is accessed again. Generally, File Manager will
                       attempt to reconnect such devices by calling the
                       WNetRestoreConnection function.

WN_FUNCTION_BUSY       Function can't be reentered and is currently being
                       used.

WN_JOB_NOT_FOUND       No job found with this ID.

WN_JOB_NOT_HELD        Job cannot be released because it is not currently
                       held.

WN_MORE_DATA           Warning: buffer too small.

WN_NET_ERROR           Miscellaneous network error.

WN_NO_ERROR            No error status available.

WN_NOT_CONNECTED       Device is not redirected.

WN_NOT_SUPPORTED       Function not supported.

WN_OPEN_FILES          Connection couldn't be canceled, files are still
                       open.

WN_OUT_OF_MEMORY       Out of memory.

WN_SUCCESS             Success.

Chapter 6  Keyboard Drivers

The Microsoft Windows keyboard driver processes all keyboard input for
Windows and Windows applications. It directly accesses the keyboard
hardware, yet provides hardware-independent keyboard input by translating
scan codes to virtual-key codes.


6.1 About the Keyboard Driver

The keyboard driver consists of two parts: the main driver and a set of
language-specific dynamic-link libraries. The main driver services the
keyboard hardware and translates scan and virtual-key codes using default
translation tables for U.S. keyboards. The language-specific libraries
contain translation tables for different types of keyboards (that is,
tables for other countries and other physical keyboard layouts). The main
driver loads the appropriate language-specific library and retrieves its
tables when Windows enables the keyboard driver.

The Windows keyboard driver consists of the following:

o   Keyboard-interrupt handler

o   Virtual-key translation functions and tables

o   ANSI-character translation functions and tables

o   Keyboard-service functions

Windows requires the keyboard to generate an interrupt whenever the user
presses or releases a key. In response to an interrupt, the driver's
keyboard-interrupt handler translates corresponding scan codes (and
corresponding shift state) to Windows virtual-key codes. The keyboard
passes both scan codes and virtual-key codes to Windows for generating
keyboard messages, or for initiating some other action.


6.1.1 Initializing the Driver

Windows initializes the keyboard driver by calling the driver's
initialization routine when it first loads the driver. Windows also calls
the driver's Inquire function to retrieve information about the driver in
the KBINFO structure.

The initialization routine typically retrieves the computer-type identifier
from ROM BIOS and determines whether the Windows is running with MS-DOS or
another environment, such as the MS-DOS compatibility box with IBM OS/2.
The driver uses the computer-type identifier to determine which translation
tables to use when translating scan codes. The driver adapts its processing
of keystrokes. For example, if running with OS/2, it passes CTRL+ESC key
combinations to OS/2 rather than Windows.

The Inquire function fills the KBINFO structure. The function also
specifies the size of the state array Windows must support. Windows calls
the ToAscii function to translate scan codes to ANSI character codes.

For more information about your keyboard and ROM BIOS, see the
documentation from your computer manufacturer.


6.1.2 Enabling and Disabling the Driver

When Windows is ready to receive keyboard input, it enables the driver by
calling the Enable function. When Windows no longer requires keyboard input
(when terminating or switching to a full-screen MS-DOS application, for
example), it disables the driver by calling the Disable function.

The Enable function is responsible for:

o   Saving the address of the keyboard-event callback function

o   Initializing the Windows virtual-key state array

o   Installing the keyboard-interrupt handler

o   Installing language- and keyboard-specific translation tables

When Windows calls Enable, it passes the address of the keyboard-event
callback function. Enable saves this address--the keyboard-interrupt
handler uses it to pass scan and virtual-key codes back to Windows.

Windows also passes the address of its 256-element, virtual-key state array
(sometimes called the keyboard-state vector) to Enable. The elements in
this array specify the state of the virtual keys. Windows sets bit 7 in an
element if the corresponding virtual key is down, and clears the bit if the
key is up. Similarly, Windows toggles bit zero each time the virtual key is
pressed. Although Windows maintains the key-state array, Enable initializes
the array to reflect to current state of the SHIFT, CTRL, ALT, NUMLOCK,
CAPSLOCK, and SCROLLLOCK keys as specified by the keyboard flags in the RAM
area used by the ROM BIOS. (On most computers, the keyboard flags are at
address 40h:17h.)

NOTE  If the keyboard driver reads data from the ROM BIOS, it must use the
special segment selector, __ROMBIOS, to create ROM BIOS addresses. The
selector (exported by the Windows kernel as KERNEL.173) corresponds to ROM
BIOS address 0F0000H.

To install the driver's own keyboard-interrupt handler, the Enable function
first saves the existing keyboard-interrupt handler. (On most computers,
the keyboard interrupt is Interrupt 9.) The original handler address is
saved to allow the Disable function to restore it as well as to allow the
driver to call the original handler for certain actions. Enable should also
save the address of the Keyboard Service routine (Interrupt 16h). The
Enable and other functions use this address to set the keyboard lights.

Finally, Enable installs the proper language- and keyboard-specific
translation tables. To do so, the function reads the type, subtype,
KEYBOARD.DLL, and OEMANSI.BIN settings from the [Keyboard] section of the
SYSTEM.INI file. The Windows Setup program or Control Panel establish the
values for these settings. Enable uses the values to determine which type
and subtype of keyboard to support as well as with language-specific
support libraries to load. If the values are not given in the SYSTEM.INI
file, the keyboard must choose default values based on the computer-type
identifier and keyboard-type identifier (if the ROM BIOS provides one).

NOTE  To support computers in which the keyboard and mouse use the same
interrupt, Windows disables and enables both the keyboard and mouse drivers
when switching to and from a full-screen MS-DOS application. Windows always
enables the drivers in the reverse order in which it disables the drivers.


6.1.3 Keyboard-Interrupt Handler

The keyboard-interrupt handler services hardware interrupts generated by
the keyboard. The handler retrieves scan codes from the keyboard,
translates the scan codes into virtual-key codes, and passes the scan and
virtual-key codes to Windows through the keyboard-event callback function.
It also updates the keyboard flags (usually at 40h:17h in the RAM area of
the ROM BIOS) and checks for special keys or key combinations.

When the interrupt handler receives control, such as when the user presses
or releases a key, the handler retrieves the current input from the
keyboard data port and determines whether the input is a scan code or a
command byte. If it is a command byte, it passes control to the original
keyboard-interrupt handler. Otherwise, it continues to process the scan
code.

When processing the scan code, the handler checks for key combinations,
such as CTRL+ALT+DELETE, and passes control to the original
keyboard-interrupt handler to carry out the corresponding actions. It also
checks for the ALT+PRINTSCREEN and SHIFT+PRINTSCREEN key combinations and
translates these into the VK_SNAPSHOT virtual-key code. When Windows
receives this virtual-key code, it takes a snapshot of the active window or
the entire screen. The handler indicates which snapshot to take by setting
the BX register to zero for the active window (ALT+PRINTSCREEN) and to 1
for the entire screen (SHIFT+PRINTSCREEN).

To support debugging, the interrupt handler checks for the CTRL+ALT+SYSREQ
key and eithers simulates a nonmaskable interrupt (NMI) (to pass control to
a debugger) or jumps to the CVWBreak function (KERNEL.205) to carry out a
controlled break. If Windows is running with OS/2, the handler ignores the
CTRL+ALT+SYSREQ key combination.

To complete processing the scan code, the handler sets the interrupt flag
using the SetInterruptFlag (sti) instruction. Before doing so, it makes
sure a subsequent keyboard interrupt does not invoke the handler again as
only one interrupt can be handled at a time. If Windows is running in
enhanced mode, this may require masking out the keyboard interrupt (usually
IRQ1) at the interrupt controller.

If Windows is running with OS/2, the interrupt handler checks for the
ALT+ESC and CTRL+ESC key combinations. If either of these key combinations
is carried out, the interrupt handler passes the scan codes to the original
keyboard-interrupt handler so that OS/2 can switch from Windows to OS/2
programs. However, the Windows keyboard-interrupt handler only passes these
scan codes if screen-switching is enabled. The display driver specifies
when screen-switching is enabled or disabled by calling the
ScreenSwitchEnable function. The display driver disables switching whenever
it enters a critical section. If switching is disabled, the Windows
keyboard-interrupt handler ignores the ALT+ESC and CTRL+ESC key
combinations.


6.1.4 Keyboard-Event Callback Function

The keyboard-interrupt handler calls the keyboard-event callback function
when it has scan and virtual-key codes to pass back to Windows. The
registers must be set as follows:

Register   Value
---------------------------------------------------------------------------

AL         Virtual key code. For more information about the specific
           values, see Section 6.1.7, Virtual-Key Codes.

AH         80h if the key is up, or 00h if the key is down.

BL         Scan code. This is an OEM-dependent value.

BH         01h if the key is an enhanced key (that is, if the prefix 0E0h
           preceded this scan code), or 00h if the key is not enhanced.

DI:SI      Address of extra message information. If extra message
           information isn't used, set the DI and SI registers to 0.

An enhanced key is one of a set of duplicate keys, such as the ENTER,
INSERT, DELETE, and direction keys, found on some keyboards such as the IBM
enhanced keyboard. On the IBM keyboard, an enhanced key has the same scan
code as its corresponding nonenhanced key, but the keyboard inserts the
0E0h prefix byte to indicate that the enhanced key generated the code. In
this case, the keyboard-interrupt handler sets the BH register to 1 before
calling the keyboard-event callback function. On the IBM enhanced keyboard,
the following are enhanced keys: Direction keys, INSERT, HOME, PAGE UP,
DELETE, END, PAGE DOWN, DIVIDE (on numeric keypad), and ENTER (on numeric
keypad).

For keyboards that have extended keys with special scan codes instead of
prefixes, Windows will not generate the proper WM_KEYUP or WM_KEYDOWN
message unless the interrupt handler converts the scan codes to the
corresponding IBM scan codes on the IBM enhanced keyboard and sets the BH
register to 1 before calling the keyboard-event callback function.


6.1.5 Initialization File Entries for Keyboard

The [Keyboard] section in the SYSTEM.INI file specifies information the
keyboard driver uses to adapt its operation. The driver reads the type,
subtype, KEYBOARD.DLL, and OEMANSI.BIN settings from the SYSTEM.INI file
using the GetPrivateProfileInt and GetPrivateProfileString functions
(KERNEL.127 and KERNEL.128). The driver uses the values to prepare
translation tables and to modify driver operation.

The type setting specifies which type of keyboard layout the driver must
support. If the keyboard type is not the driver's default type, the driver
loads the language-specific keyboard library specified by the KEYBOARD.DLL
setting and calls that library's GetKbdTable function to install the
appropriate translation tables. If a subtype setting is given, the driver
also may use it to determine which translation tables to load. However,
since this setting specifies whether a keyboard of a given type has special
attributes, drivers most often use the subtype setting to determine whether
to test for certain special cases.

For many keyboards, the Windows Setup program automatically determines the
keyboard type and sets the appropriate value in the SYSTEM.INI file. If the
type for a given keyboard can not be accurately determined, a driver
developer can supply a modified SETUP.INF file which allows the user to
manually select the keyboard type during installation.


6.1.6 Translations

The keyboard driver carries out the following translations:

o   Scan codes to virtual-key codes (keyboard-interrupt handler)

o   Virtual-key codes to ANSI characters (ToAscii)

o   ANSI characters to OEM characters (AnsiToOem and AnsiToOemBuff)

o   OEM characters to ANSI characters (OemToAnsi and OemToAnsiBuff)

o   OEM or ANSI characters to virtual-key codes (OemKeyScan, VkKeyScan, and
    MapVirtualKey)

o   Virtual-key codes to scan codes (MapVirtualKey)

The keyboard-interrupt handler converts scan codes to virtual-key codes
before sending keystrokes to Windows. Windows calls the ToAscii function to
convert virtual-key codes to ANSI characters when generating WM_CHAR
messages. Windows applications call the AnsiToOem and OemToAnsi functions
to convert ANSI characters to OEM-specific characters, and OEM-specific
characters to ANSI characters. Windows and Windows applications call
OemKeyScan and VkKeyScan to generate scan and virtual-key codes for given
OEM or ANSI characters.


6.1.7 Virtual-Key Codes

The virtual-key codes provide a hardware- and language-independent method
of identifying keyboard keys. Each virtual-key code represents a unique
keyboard key and also identifies the purpose of that key. The keyboard
driver must provide a translation table that maps keyboard scan codes to
the appropriate virtual-key codes.


6.1.7.1 Required Virtual Keys

The complete virtual-key code set consists of 256 byte values in the range
0 to 255. Most, but not all, of the values used by standard drivers are in
the range 0 to 127. There is a loose distinction between standard keys,
which do not vary much, and OEM keys, which do vary from keyboard to
keyboard.

For full Windows functionality, a keyboard driver must provide the
following virtual keys:

Virtual-key code       Description
---------------------------------------------------------------------------

VK_0 through VK_9      Number keys (not on numeric keypad): 0 through 9

VK_A through VK_Z      Letter keys: A through Z

VK_BACK                BACKSPACE key

VK_CONTROL             CTRL key

VK_DELETE              DELETE key

VK_DOWN                Down direction key

VK_END                 END key

VK_ESCAPE              ESC key

VK_F1 through VK_F10   F1 through F10 keys

VK_HOME                HOME key

VK_INSERT              INSERT key

VK_LEFT                Left direction key

VK_MENU                ALT key

VK_NEXT                PAGE DOWN key

VK_PRIOR               PAGE UP key

VK_RIGHT               Right direction key

VK_SHIFT               Left and right SHIFT keys

VK_SNAPSHOT            PRINTSCREEN key

VK_SPACE               SPACE key

VK_TAB                 TAB key

VK_UP                  Up direction key

Shift keys must be available in the combinations unshifted, SHIFT, CTRL,
and CTRL+ALT.

Most keyboards, the virtual-key codes VK_INSERT, VK_DELETE, VK_HOME,
VK_END, VK_PRIOR, and VK_NEXT are generated on the numeric keypad only if
NUMLOCK is off.


6.1.7.2 Optional Virtual Keys

If a keyboard has a numeric pad, the numeric keys are frequently used as
cursor-control and editing keys if NUMLOCK is off. If NUMLOCK is on, the
virtual-key codes VK_NUMPAD0 through VK_NUMPAD9 are used for the digits.
Keyboards with a DELETE key that also generates the decimal point (period
or comma) use VK_DELETE and VK_DECIMAL to distinguish between the two uses
of the key.

Keyboards commonly contain various lock keys, such as VK_CAPITAL and
VK_NUMLOCK. If a keyboard driver generates ANSI characters on the numeric
keypad using ALT + numeric-pad keys, it must do this translation only if
NUMLOCK is on. The cursor and editing keys on IBM-compatible keyboards do
not produce this translation.

Other keys may vary from keyboard to keyboard. The following set of
virtual-key codes is generally used for punctuation keys, accented letter
keys, and dead keys in the main section of a keyboard:

    VK_OEM_1 .. VK_OEM_8
    VK_OEM_102
    VK_OEM_PLUS, VK_OEM_MINUS, VK_OEM_COMMA, VK_OEM_PERIOD
If a keyboard has more than 16 function keys, the virtual-key codes in the
range VK_F17 through VK_F24 should be used for the extra function keys.

Windows internally generates the mouse-button virtual-key codes VK_LBUTTON,
VK_RBUTTON, VK_MBUTTON, and VK_CANCEL. These virtual-key codes are
generated internally by Windows and are never generated by keyboard or
mouse drivers.

Keyboard drivers should not generate VK_EXECUTE or VK_SEPARATER.


6.1.7.3 Virtual Keys for 122-Key Keyboards

For keyboards with 122 keys, the mapping for the first 101 keys is the same
as described in previous sections.

The function keys F13 through F24 should use VK_F13 through VK_F24.

The remaining keys should be mapped to the following virtual-key codes:

VK_ATTN     VK_OEM_CLEAR

VK_CRSEL    VK_PA1

VK_EREOF    VK_PLAY

VK_EXSEL    VK_ZOOM


6.1.7.4 Virtual-Key Code Definitions

The following table includes the virtual-key codes that are defined for
Windows. The key code values 0 and 0FFh are not used.

---------------------------------------------------------------------------
Name             Value   Comment
---------------------------------------------------------------------------

VK_LBUTTON       01h     Left mouse button.

VK_RBUTTON       02h     Right mouse button.

VK_CANCEL        03h     Used for control-break processing.

VK_MBUTTON       04h     Middle mouse button (3-button mouse).

                         05h through 07h undefined.

VK_BACK          08h     

VK_TAB           09h     

                         0Ah and 0Bh undefined.

VK_CLEAR         0Ch     

VK_RETURN        0Dh     

                         0Eh and 0Fh undefined.

VK_SHIFT         10h     

VK_CONTROL       11h     

VK_MENU          12h     

VK_PAUSE         13h     

VK_CAPITAL       14h     

                         15h through 1Ah undefined.

VK_ESCAPE        1Bh     

                         1Ch through 1Fh undefined.

VK_SPACE         20h     

VK_PRIOR         21h     Page up.

VK_NEXT          22h     Page down.

VK_END           23h     

VK_HOME          24h     

VK_LEFT          25h     

VK_UP            26h     

VK_RIGHT         27h     

VK_DOWN          28h     

VK_SELECT        29h     

VK_PRINT         2Ah     Only used by Nokia.

VK_EXECUTE       2Bh     Never used.

VK_SNAPSHOT      2Ch     SYSREQ key starting with Windows 3.0.

VK_INSERT        2Dh     

VK_DELETE        2Eh     

VK_HELP          2Fh     

VK_0             30h     

VK_1             31h     

VK_2             32h     

VK_3             33h     

VK_4             34h     

VK_5             35h     

VK_6             36h     

VK_7             37h     

VK_8             38h     

VK_9             39h     

                         3Ah though 40h undefined.

VK_A             41h     

VK_B             42h     

VK_C             43h     

VK_D             44h     

VK_E             45h     

VK_F             46h     

VK_G             47h     

VK_H             48h     

VK_I             49h     

VK_J             4Ah     

VK_K             4Bh     

VK_L             4Ch     

VK_M             4Dh     

VK_N             4Eh     

VK_O             4Fh     

VK_P             50h     

VK_Q             51h     

VK_R             52h     

VK_S             53h     

VK_T             54h     

VK_U             55h     

VK_V             56h     

VK_W             57h     

VK_X             58h     

VK_Y             59h     

VK_Z             5Ah     

                         5Bh through 5Fh undefined.

VK_NUMPAD0       60h     

VK_NUMPAD1       61h     

VK_NUMPAD2       62h     

VK_NUMPAD3       63h     

VK_NUMPAD4       64h     

VK_NUMPAD5       65h     

VK_NUMPAD6       66h     

VK_NUMPAD7       67h     

VK_NUMPAD8       68h     

VK_NUMPAD9       69h     

VK_MULTIPLY      6Ah     

VK_ADD           6Bh     

VK_SEPARATER     6Ch     Never generated by keyboard driver.

VK_SUBTRACT      6Dh     

VK_DECIMAL       6Eh     

VK_DIVIDE        6Fh     

VK_F1            70h     

VK_F2            71h     

VK_F3            72h     

VK_F4            73h     

VK_F5            74h     

VK_F6            75h     

VK_F7            76h     

VK_F8            77h     

VK_F9            78h     

VK_F10           79h     

VK_F11           7Ah     

VK_F12           7Bh     

VK_F13           7Ch     

VK_F14           7Dh     

VK_F15           7Eh     

VK_F16           7Fh     

VK_F17           80h     

VK_F18           81h     

VK_F19           82h     

VK_F20           83h     

VK_F21           84h     

VK_F22           85h     

VK_F23           86h     

VK_F24           87h     

                         88h through 8Fh unassigned.

VK_NUMLOCK       090h    NUMLOCK on all keyboards.

VK_OEM_SCROLL    091h    SCROLL LOCK on all keyboards.

                         92h through B9h unassigned.

VK_OEM_1         0BAh    Punctuation.

VK_OEM_PLUS      0BBh    Punctuation.

VK_OEM_COMMA     0BCh    Punctuation.

VK_OEM_MINUS     0BDh    Punctuation.

VK_OEM_PERIOD    0BEh    Punctuation.

VK_OEM_2         0BFh    Punctuation.

VK_OEM_3         0C0h    Punctuation.

                         C1h through DAh unassigned.

VK_OEM_4         0DBh    Punctuation.

VK_OEM_5         0DCh    Punctuation.

VK_OEM_6         0DDh    Punctuation.

VK_OEM_7         0DEh    Punctuation.

VK_OEM_8         0DFh    Punctuation.

VK_F17           0E0h    F17 key on Olivetti extended keyboard (internal
                         use only).

VK_F18           0E1h    F18 key on Olivetti extended keyboard (internal
                         use only).

VK_OEM_102       0E2h    < or | on IBM-compatible 102 enhanced keyboard
                         (non-U.S.).

VK_ICO_HELP      0E3h    Help key on Olivetti extended keyboard (internal
                         use only).

VK_ICO_00        0E4h    00 key on Olivetti extended keyboard (internal use
                         only).

                         E5h unassigned.

VK_ICO_CLEAR     0E6h    Olivetti extended keyboard (internal use only).

                         E7h and E8h unassigned.

VK_OEM_RESET     0E9H    Only used by Nokia.

VK_OEM_JUMP      0EAH    Only used by Nokia.

VK_OEM_PA1       0EBH    Only used by Nokia.

VK_OEM_PA2       0ECH    Only used by Nokia.

VK_OEM_PA3       0EDH    Only used by Nokia.

VK_OEM_WSCTRL    0EEH    Only used by Nokia.

VK_OEM_CUSEL     0EFH    Only used by Nokia.

VK_OEM_ATTN      0F0H    Only used by Nokia.

VK_OEM_FINNISH   0F1H    Only used by Nokia.

VK_OEM_COPY      0F2H    Only used by Nokia.

VK_OEM_AUTO      0F3H    Only used by Nokia.

VK_OEM_ENLW      0F4h    Only used by Nokia.

VK_OEM_BACKTAB   0F5h    Only used by Nokia.

VK_ATTN          0F6H    

VK_CRSEL         0F7H    

VK_EXSEL         0F8H    

VK_EREOF         0F9H    

VK_PLAY          0FAH    

VK_ZOOM          0FBH    

VK_NONAME        0FCH    

VK_PA1           0FDH    

VK_OEM_CLEAR     0FEH    

---------------------------------------------------------------------------


6.1.8 ANSI Characters

Windows and Windows applications call the ToAscii function to translate
virtual-key codes to ANSI characters. The keyboard driver translate these
key codes by checking the state of the virtual-shift keys (such as the
VK_SHIFT, VK_CONTROL, and VK_MENU) and mapping the virtual-key code and
shift state to the appropriate character. For example, on most U.S.
keyboards if the VK_SHIFT key is up, the VK_2 virtual key code maps to the
number 2 (ANSI 50); if VK_SHIFT is down, VK_2 maps to the at sign (@) (ANSI
64). For foreign-language keyboards, the keyboard also checks for a
previously typed dead key before translating the virtual-key code.

Windows passes the address of the key-state array to the ToAscii function,
giving the keyboard driver access to the current state of all virtual keys
including the shift keys. The key-state array also contains the shift state
of the mouse buttons (that is, the corresponding virtual-key codes
VK_LBUTTON, VK_RBUTTON, VK_CANCEL, and VK_MBUTTON).

The keyboard driver must provide translation tables to map virtual keys to
ANSI characters. Since the meaning of a virtual key depends on the state of
the shift keys, the driver should provide tables for each possible
shift-key combination (for example, no shift key, VK_SHIFT, VK_CONTROL, and
VK_MENU and VK_CONTROL combined). Windows does not require that all virtual
keys map to ANSI characters for all shift-key combinations. Therefore, not
all translation tables need to map the complete virtual-key set.

The keyboard type and language also affects the translation of virtual-key
codes to ANSI characters. The keyboard driver must adapt its translation
tables for a specific-language by loading translation tables from the
corresponding language-specific library.


6.1.9 OEM Characters

Windows and Windows applications call the AnsiToOem and OemToAnsi functions
to convert ANSI characters to OEM characters and OEM characters to ANSI
characters. The functions allow Windows applications to prepare text for
the MS-DOS environment.

The keyboard code page affects the translation of ANSI and OEM characters.
The keyboard driver must adapt its translation tables for specific code
pages by loading translation tables from the corresponding
translation-table file. Windows specifies the translation table to load
using the OEMANSI.BIN setting in the [Keyboard] section of the SYSTEM.INI
file.


6.1.10 Scan Codes

Windows applications send characters to other Windows applications with the
WM_KEYDOWN and WM_KEYUP messages. These messages are expected to get the
appropriate virtual-key codes to send by using the VkKeyScan, OemKeyScan,
or MapVirtualKey function. The applications must not assume any fixed
translation of the VK_OEM_* keys. To support these functions, the keyboard
driver can scan existing translation tables to locate the given ANSI or OEM
character code and subsequently identify the scan code.


6.1.11 Key-Translation Tables

In the Microsoft retail keyboard driver, several of the translation tables
are associative tables that map a virtual-key code or a combination of a
virtual-key code and some other value (for example, shift state) into an
ANSI character. All such tables in these drivers are assembled using
special macros that arrange the tables so that the first column of the
table is a single vector, which may be searched with a single-string scan
instruction.

Table          Description
---------------------------------------------------------------------------

keyTrTab       Maps scan codes to Windows virtual-key codes. Some entries
               in this table in TABS.ASM may be overlaid when a
               language-specific library is loaded.

USTransPatch   Maps selected scan codes to virtual-key codes. This table
               contains that part of the default keyTrTab table that can be
               overlaid by language-specific libraries. The driver uses
               this table to restore the default keyTrTab if an error
               occurs while changing translation tables.

Most of the remaining tables are either in a discardable segment in the
driver or in a language-specific library. If they are in the driver,
functions such as ToAscii that use the tables ensure that the table segment
is loaded by calling the GetTableSeg function.

The tables in the driver are for the U.S. keyboard. Several of the
following tables are blank for the U.S. keyboard since it has no dead keys
or CTRL+ALT keys.

In the language-specific versions of these tables, there is often padding
(with zeros) at the end of a table to allow for overlaying the tables.

Associative Table            Description
---------------------------------------------------------------------------

AscControlVK, AscControl     This table translates the virtual-key code +
                             CTRL to a control character, when the
                             virtual-key code is not one for a letter. For
                             letters, the table is not used.

AscCtlAltVK, AscCtlAlt       This table translates the virtual-key code +
                             CTRL + ALT to an ANSI character. This is empty
                             for the U.S. keyboard.

AscShCtlAltVK, AscShCtlAlt   This table translates the virtual-key code +
                             CTRL + ALT + SHIFT to an ANSI character. This
                             table is empty for the U.S. keyboard.

AscTranVK, AscTran           This table translates the virtual-key codes to
                             ANSI for unshifted and shifted key
                             combinations. AscTranVK is a byte array of
                             virtual-key codes; AscTran is a WORD array of
                             their translations. In each WORD, the low byte
                             is the unshifted translation, and the high
                             byte is the shifted translation. If the
                             virtual-key code is one for a letter (A..Z),
                             this table is bypassed.

CapitalTable                 This table is a list of the virtual keys for
                             which the CAPSLOCK key is effective, in
                             addition to the letter keys (VK_A .. VK_Z).
                             This table is empty for the U.S. keyboard.

DeadKeyCode, DeadChar        This table translates a combination of a dead
                             key and a letter into an accented letter. This
                             table is accessed when the key after a dead
                             key is pressed. If a translation is not found
                             in this table, ToAscii will return two
                             characters in its output buffer: the dead key
                             plus the second character. This table is empty
                             for the U.S. keyboard.

Morto, MortoCode             This table is searched to check if a
                             particular virtual-key code and shift
                             combination is for a dead key. If it is, the
                             dead-key value is returned by ToAscii, with a
                             negative-character count. This table is empty
                             for the U.S. keyboard.

SGCapsVK, SGTrans            This table has entries only in the DLL for
                             Swiss-German keyboards. It handles a special
                             case where keys with SHIFT LOCK are translated
                             differently from shifted keys.


6.1.12 Language-Specific Libraries

The translation tables for the language-specific libraries are in files
that contain data in two segments: the CODE segment, which is load-on-call
and discardable, and the DATA segment, which is fixed. Data from the CODE
segment of the DLL is used to overlay the tables in the DATA segment of the
main driver. Data in the DATA segment of the library is not copied;
instead, a pointer in the driver is set to the library's DATA segment
address.

The initial values in the tables in the library's DATA segment are for
enhanced keyboards. For other keyboard types, the tables in the library's
DATA segment must be patched or overlaid from tables in the CODE segment.

The GetKbdTable function performs the copying or overlaying. The driver
calls the function after the driver loads the library. Once GetKbdTable is
called, the driver accesses the library's fixed DATA segment directly.
After initialization, the tables in the CODE segment of the library are no
longer used.

A header, containing offsets and sizes of the various tables in the
library's DATA segment, is always copied to the driver no matter what type
of keyboard is installed.

Some language-specific libraries contain the function GetKeyString. The
keyboard's GetKeyNameText function calls GetKeyString to obtain key name
strings in the language appropriate to the keyboard.


6.1.13 Miscellaneous Keyboard Services

The keyboard driver provides a number of additional services to Windows and
Windows applications. These miscellaneous services are provided by the
following functions:

EnableKBSysReq   GetKeyboardType

GetBIOSKeyProc   GetKeyNameText

GetKBCodePage    SetSpeed


6.2 Function Reference

The following is an alphabetical listing of keyboard-driver functions.

AnsiToOem

    WORD AnsiToOem(lpSrc, lpDst)
    LPSTR lpSrc;
    LPSTR lpDst;

The AnsiToOem function translates a string in the ANSI character set to a
string in the OEM character set. For most computers, the OEM character set
is code page 437.


Parameters

   lpSrc
   Points to the input ANSI string.

   lpDst
   Points to the output OEM string.


Return Value

The return value is always 0FFFF in the AX register if the function is
successful.


Comments

The export ordinal for this function is 5.

The lpSrc and lpDst parameters may point to the buffer.

The code page used to translate the character depends on the current code
page (as set when Windows calls the Enable function). For most drivers, the
default translation is code page 437 (the standard U.S. IBM-PC character
set).

Strings longer than 64K may be translated.


See Also

AnsiToOemBuff, OemToAnsi



AnsiToOemBuff

    void AnsiToOemBuff(lpSrc, lpDst, nCount)
    LPSTR lpSrc;
    LPSTR lpDst;
    WORD nCount;

The AnsiToOemBuff function translates a string of ANSI characters to OEM.
However, use this function to translate fixed-length byte arrays, such as
database records, which may contain null characters.


Parameters

   lpSrc
   Points to the input ANSI string.

   lpDst
   Points to the output OEM string.

   nCount
   Specifies the byte count.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 134.

The lpSrc and lpDst parameters may point to the same buffer.


See Also

AnsiToOem, OemToAnsiBuff



Disable

    void Disable(void)

The Disable function restores the original keyboard-interrupt handler when
exiting Windows.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 3.

The Disable function restores the keyboard-interrupt vector (usually
Interrupt 9) to the keyboard handler that was previously installed.

Disable is called when exiting Windows and before starting or switching to
a full-screen, MS-DOS application running under standard-mode Windows.

When Disable is called, the BIOS keyboard flags (40h:17h in most
IBM-compatible systems) must reflect the state of the SHIFT LOCK, NUMLOCK,
and SCROLL LOCK keys. Normally, the keyboard driver's hardware-interrupt
handler will handle this.

The keyboard and mouse Enable functions are always called in the reverse
order of the keyboard and mouse Disable functions because some mouse
drivers may hook into the keyboard interrupt.


See Also

Enable



Enable

    void Enable(eventProc, lpKeyState)
    FARPROC eventProc;
    LPBYTE lpKeyState;

The Enable function installs the hardware interrupt for Windows, and
performs the necessary initialization of the driver.


Parameters

   eventProc
   Points to Windows keyboard-event function.

   lpKeyState
   Points to the 256-byte, Windows virtual key-state array.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 2.

The Enable function saves the address of the original keyboard
hardware-interrupt handler in static memory. The driver maintains the shift
and numeric lock state, and the state of indicator lights. Linkage with a
language-specific keyboard library should be established (if one exists).

Enable is called once when you start Windows. It is also called when
returning to Windows from a full-screen application for which the keyboard
was disabled.


See Also

Disable



EnableKBSysReq

    WORD EnableKBSysReq(fWord)
    WORD fWord;

The EnableKBSysReq function enables and disables the CTRL+ALT+SYSREQ trap
to the debugger or Microsoft CodeView(R) (CVW).


Parameters

   fWord
   Specifies the action to take. This parameter can be one of the following
   values.

              Value   Meaning
              -------------------------------------------------------------

              01h     Enables Interrupt 2

              02h     Disables Interrupt 2

              04h     Enables CVW Break

              08h     Disables CVW Break


Return Value

The return value is the state of the SYSREQ key traps. The return value
consists of the following bit values.

Bit   Meaning
---------------------------------------------------------------------------

0     Set to 1 to indicate Interrupt 2 enabled; 0 indicates that INT 2 is
      disabled.

1     Set to 1 to indicate CVW Break enabled; 0 indicates that CVW Break is
      disabled.

All other bits are reserved.


Comments

The export ordinal for this function is 136.

The initial behavior is to ignore CTRL+ALT+SYSREQ. If both Interrupt 2 and
CVW are enabled, then CVW overrides.



GetKBCodePage

    WORD GetKBCodePage(void)

The GetKBCodePage function identifies which OEM/ANSI translation table and
code page the keyboard driver is using.


Parameters

This function has no parameters.


Return Value

The return value is the current code page in the AX register. The code page
indicates which OEM/ANSI translation-table file is loaded.


Comments

The export ordinal for this function is 132.

The following lists the possible code pages and corresponding OEM/ANSI
translation-table files.

Value   Meaning and Filename
---------------------------------------------------------------------------

437     Default (U.S., most countries. No OEMANSI.BIN file)

860     Portugal (XLATPO.BIN)

863     French Canada (XLATCA.BIN)

865     Norway/Denmark (XLATNO.BIN)

850     International code page (XLAT850.BIN)

If the OEMANSI.BIN setting in the [Keyboard] section of the SYSTEM.INI file
specifies an OEMANSI translation-table file, the keyboard driver loads the
file and sets the code page to the specified code page.

Because code page 437 is the default, if the OEMANSI.BIN setting is blank,
the keyboard driver uses the default translation table and code page. For
most drivers, the default code page is 437.



GetKbdTable

    LPSTR GetKbdTable(iType, lpKeyTrTab, lpHeader)
    WORD iType;
    LPSTR lpKeyTrTab;
    LPSTR lpHeader;

The GetKbdTable function copies translation tables and translation-table
headers into the keyboard driver. The function must be exported by each
language-specific keyboard library. The keyboard driver calls the function
when it first loads the language-specific library.


Parameters

   iType
   Specifies the keyboard type. It can be one of the following values.

     Value   Meaning
     ----------------------------------------------------------------------

     1       XT, M24 83 key

     2       Olivetti M24 102 key ICO

     3       AT 84 or 86 key

     4       RT Enhanced 101 or 102 key

     5       Nokia 1050

     6       Nokia

   lpKeyTrTab
   Points to to the KeyTrTab table in the keyboard driver.

   lpHeader
   Points to the header for the translation tables.


Return Value

The return value is the address of the language-specific library's DATA
segment in the DX:AX register pair.


Comments

The export ordinal for this function is 1.

The function patches the translation table and copies the data to the
keyboard driver.

This function is in a load-on-call discardable segment, which means its
memory may be reclaimed. The DATA segment is fixed.


See Also

GetKeyString, NewTable



GetKeyboardType

    WORD GetKeyboardType(wWhich)
    WORD wWhich;

The GetKeyboardType function identifies the type of keyboard.


Parameter

   wWhich
   Specifies whether the function returns a keyboard type or an OEM
   subtype. If the parameter is 0, the function returns the basic type. If
   the parameter is 1, the function returns the OEM subtype.


Return Value

The return value is a keyboard type or an OEM subtype, depending on the
value of the wWhich parameter.


Comments

The export ordinal for this function is 130.

If a keyboard type is requested (wWhich is 0), the function returns one of
the following keyboard types.

Value   Meaning
---------------------------------------------------------------------------

1       IBM PC, XT or compatible (83 key)

2       Olivetti M24 ICO (102 key)

3       IBM AT (84 keys) or similar

4       IBM Enhanced (101 or 102 keys)

5       Nokia 1050

6       Nokia

If a keyboard subtype is requested (wWhich is 1), the function returns a
nonzero OEM-dependent subtype or zero to indicate that no subtypes are
available.



GetKeyString

    int GetKeyString(nString, lpStringOut, iSize)
    int nString;
    LPSTR lpStringOut;
    WORD iSize;

The GetKeyString function copies the name of a specified key to the given
buffer. The function must be exported by each language-specific keyboard
library. The keyboard driver calls the function when the driver's
GetKeyNameText function has been called by an application.


Parameters

   nString
   Specifies the string list index.

   lpStringOut
   Points to the buffer to receive the null-terminated key name.

   iSize
   Specifies the maximum number of bytes the buffer can hold. The
   lpStringOut parameter points to this buffer


Return Value

The return value is the size of the string (excluding the terminating zero
byte) in the AX register.


Comments

The export ordinal for this function is 2.

The GetKeyNameText function checks for this function in the
language-specific library to obtain the local version of the key name.



GetTableSeg

    int GetTableSeg(void)

The GetTableSeg function returns the segment address of the keyboard
driver's discardable table segment.

This function is intended for use within the keyboard driver only.


Parameters

This function has no parameters.


Return Value

The return value is the segment address of a discardable keyboard table
segment. It also copies the segment address to the driver's TableSeg
parameter.


Comments

The export ordinal for this function is 126.

The keyboard driver calls this function only when a language-specific
library does not exist. Windows automatically loads the discardable segment
containing the default translation tables when this function is called,
ensuring that the keyboard driver can update its translation tables using
this default data.



Inquire

    int Inquire(lpKBInfo)
    LPKBINFO lpKBInfo;

The Inquire function fills the KBINFO structure with information about the
keyboard hardware.


Parameters

   lpKBInfo
   Points to the KBINFO structure to receive the keyboard information. The
   structure has the following form:

         typedef struct tagKBINFO {
             BYTE  Begin_First_range;            /* used for KANJI */
             BYTE  End_First_range;              /* used for KANJI */
             BYTE  Begin_Second_range;           /* used for KANJI */
             BYTE  End_Second_range;             /* used for KANJI */
             int   StateSize;                    /* size of ToAscii state block*/
         } KBINFO;

Return Value

The return value is the number of bytes copied to the KBINFO structure.


Comments

The export ordinal for this function is 1.



Keyboard_Event

    mov     ah, UpDownFlag   ; 00h for down stroke, 80h for up stroke
    mov     al, VirtualKey   ; Windows virtual-key code
    mov     bh, PrefixFlag   ; 00h if no prefix, 1 if 0E0h prefix byte
    mov     bl, ScanCode     ; hardware scan code

    mov     si, word ptr [ExtraInfo]
    mov     di, word ptr [ExtraInfo+2]
                             ; extra information

    call    [Keyboard_Event]    ; keyboard-event function
The Keyboard_Event function records a keystroke. The keystroke may
subsequently be used to generate a WM_KEYUP or WM_KEYDOWN message.

The keyboard driver's interrupt handler calls this function.


Parameters

   UpDownFlag
   Specifies whether the key is up or down. The parameter is 0x00h for a
   down stroke and 80h for an up stroke.

   VirtualKey
   Specifies a virtual-key code. The code must be a value in the range 1 to
   254.

   PrefixFlag
   Specifies whether the scan code was preceded by the 0E0h prefix byte.
   The parameter is 00h if there was no prefix byte, and is 1 if there was
   a prefix byte.

   ScanCode
   Specifies the hardware-scan code for the key.

   ExtraInfo
   Specifies an additional 32-bit value associated with the key stroke.


Return Value

This function has no return value.


Comments

Although the keyboard driver passes the hardware-scan code (which is
OEM-dependent) to Windows, Windows does not use the code. Instead, Windows
subsequently passes the scan code to the ToAscii function, which may use it
for special purposes. The interrupt handler sets the up/down bit in the
scan code to 0.

This interrupt handler may process some keystrokes without passing them to
Windows through the keyboard-event callback function. In particular, the
handler processes CTRL+ALT+SYSREQ keytrokes and generates a nonmaskable
interrupt (NMI). Under certain circumstances, the driver's interrupt
handler passes keystrokes to the original keyboard-interrupt handler. This
is the case for CTRL+ALT+DELETE key combination and for the PAUSE key.

Use the PRINTSCREEN key to take a screen snapshot, which is saved in the
Windows clipboard. This is handled in the interrupt routine by calling the
event procedure with VK_SNAPSHOT in the AL register, with the value equal
to 0 (for full-screen snapshot) or 1 (for active-window snapshot) in the BL
register.


See Also

Enable



MapVirtualKey

    int MapVirtualKey(wCode, wMapType)
    WORD wCode;
    WORD wMapType;

The MapVirtualKey function maps scan codes to virtual-key codes, and
virtual-key codes to either scan codes or ANSI character values. This
function is intended to be used by the Program Information File (PIF)
Editor and Windows to get information about keyboard mapping.


Parameters

   wCode
   Specifies the input scan code or virtual-key code.

   wMapType
   Specifies which mapping to carry out. This parameter can be one of the
   following values.

     Value   Meaning
     ----------------------------------------------------------------------

     0       Map virtual key to scan code.

     1       Map scan code to virtual key.

     2       Map virtual key to ASCII characters.


Return Value

The return value (in the AX register) is a nonzero scan code or virtual-key
code, if it is successful. Otherwise, the return value is zero if mapping
cannot be performed.


Comments

The export ordinal for this function is 131.

For the first two mappings, the scan code to virtual-key code translation
table is examined to determine the translations. Some valid codes may not
be translated in this table.

For the third type of mapping, uppercase letters A through Z are returned
for VK_A through VK_Z. ASCII characters are returned for the top-row
numeric keys VK_0 through VK_9. For punctuation and dead keys in the main
part of the keyboard, the unshifted character will be returned.


See Also

OemToAnsi, AnsiToOem



NewTable

    void NewTable(void)

The NewTable function determines the keyboard type and attempts to load a
language-specific keyboard library.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 127.

The NewTable function determines the type of keyboard installed by reading
settings from the [Keyboard] section of the SYSTEM.INI file. The function
sets the internal keyboard-type variables and if a language-specific
keyboard library is specified it loads the library and saves its handle.
The driver subsequently uses this handle to determine whether to use the
tables in the discardable table segment or the language-specific library's
tables.

If the settings in the [Keyboard] section are not found or have no value,
the default type is determined by the type of system for which the
particular driver is designed.



OEMKeyScan

    DWORD OEMKeyScan(wOemChar)
    WORD wOemChar;

The OEMKeyScan function maps OEM codes (0 through 0FFH) into scan codes and
shift states. This function provides information that enables a program to
send OEM text to another program by simulating keyboard input. Windows,
when running in 386 enhanced mode, uses it specifically for this purpose.


Parameter

   wOemChar
   Specifies the ASCII character.


Return Value

The return value is the scan code in the AX register and the shift state in
the DX register. If the character is not defined in the tables, the return
value is -1 in both the DX and AX registers.


Comments

The export ordinal for this function is 128.

The bits in the shift state returned in the DX register have the following
meaning.

Bit   Value
---------------------------------------------------------------------------

1     1 if the SHIFT key is down; 0 otherwise.

2     1 if CTRL and SHIFT is down; 0 otherwise.

This function does not provide translations for characters that require the
CTRL+ALT key combination or dead keys.

This function calls VkKeyScan.


See Also

VkKeyScan



OemToAnsi

    int OemToAnsi(lpSrc, lpDst)
    LPSTR lpSrc;
    LPSTR lpDst;

The OemToAnsi function translates a string in the current OEM character set
to ANSI.


Parameters

   lpSrc
   Points to the input ANSI string.

   lpDst
   Points to the output OEM string.


Return Value

The return value is 0FFFF in the AX register.


Comments

The export ordinal for this function is 6.

The lpSrc and lpDst parameters may point to the same buffer.

The code page used to translate the character depends on the current code
page (as set when Windows calls the Enable function). For most drivers, the
default translation is code page 437 (the standard U.S. IBM-PC character
set).

Strings longer than 64K may be translated.


See Also

AnsiToOem, OemToAnsiBuff



OemToAnsiBuff

    void OemToAnsiBuff(lpSrc, lpDst, nCount)
    LPSTR lpSrc;
    LPSTR lpDst;
    WORD nCount;

The OemToAnsiBuff function translates a string of OEM characters to ANSI.
However, use this function to translate fixed-length byte arrays, such as
database records, which may contain NULL bytes.


Parameters

   lpSrc
   Points to the input ANSI string.

   lpDst
   Points to the output OEM string.

   nCount
   Specifies the length in bytes of the input string.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 135.

The lpSrc and lpDst parameters may point to the same buffer.

The code page used to translate the character depends on the current code
page (as set when Windows calls the Enable function). For most drivers, the
default translation is code page 437 (the standard U.S. IBM-PC character
set).


See Also

OemToAnsi, AnsiToOemBuff



ScreenSwitchEnable

    void ScreenSwitchEnable(wEnable)
    WORD wEnable;

The ScreenSwitchEnable function enables or disables screen switching under
OS/2. It does not apply to running with MS-DOS.


Parameter

   wEnable
   Specifies what action to take. It is zero to disable the switch; nonzero
   to enable it.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 100.

The display driver calls this function to inform the keyboard driver that
the display driver is in a critical section and, therefore, it should
ignore all OS/2 screen switches until the display driver leaves the
critical section.

The parameter is saved as a flag that is tested in the interrupt function;
if it is zero, the OS/2 key combination for screen switching is ignored.

When Windows first starts, the screen switches are enabled.



SetSpeed

    int SetSpeed(Rate)
    int Rate;

The SetSpeed function sets the repeat rate of the keyboard. This function
is intended to be used by Control Panel and by the initialization of
Windows.


Parameter

   Rate
   Specifies the repeat rate. The lowest 5 bits define the desired repeat
   rate. If Rate is -1, the return value is a value indicating
   speed-setting capability.


Return Value

The return value is the repeat rate, or a value specifying whether the
repeat rate can be set.

If Rate is a repeat rate (not -1), the return value is the repeat rate
actually set on the keyboard if it is successful. If it could not set a new
rate, the return value is -1.

If Rate is -1, the return value is 0 if the repeat rate speed can be set.
Otherwise, it is -1.


Comments

The export ordinal for this function is 7.

This function is used in conjunction with Control Panel for setting the
keyboard repeat rate.

If the keyboard speed cannot be set from software, this function may be
reduced to a stub which always returns -1. In that case, Control Panel will
not display a menu selection for setting keyboard speed.



ToAscii

    int ToAscii(VirtKey, Scancode, lpKeyState, lpState, KeyFlags)
    WORD VirtKey;
    WORD Scancode;
    LPSTR lpKeyState;
    LPSTR lpState;
    WORD KeyFlags;

The ToAscii function translates the virtual-key code passed to it, along
with the current keyboard state, to an ANSI character.


Parameters

   VirtKey
   Specifies a virtual-key code.

   Scancode
   Specifies a hardware-scan code in the low-order byte, and a shift state
   in the high-order byte. The bits in the shift state have the following
   meaning.

   Bit   Meaning
   ------------------------------------------------------------------------

   15    1 if the key is up; 0 if the key is down.

   14    1 if the key was previously up; 0 if the key was previously down.

   13    1 if the ALT key is down.

   12    1 if Windows displays a menu.

   11    1 if Windows displays a dialog box.

   10    Not used.

   9     Not used.

   8     1 if the key is extended; 0 if it is not.

   Bits 0 through 6 are the hardware-scan code (used mainly in the
   translation of ALT+number-pad character code input). Bit 7 is generally
   0.

   lpKeyState
   Points to virtual key-state array maintained by Windows.

   lpState
   Points to state block. This is used mainly for the output of ANSI
   characters.

   KeyFlags
   Specifies duplicate shift-state information. The bits have the following
   meaning.

   Bit   Meaning
   ------------------------------------------------------------------------

   0     1 if a menu is display, 0 if not.

   1     1 if an extended key, 0 if not.


Return Value

The return value is the number of characters returned in the state block.
The number of characters, 1 byte per WORD is returned in the AX register.
The lpState parameter points to the state block.

The return value is one of the following values.

Value   Description
---------------------------------------------------------------------------

2       Two characters are returned (mainly an accent and a dead-key
        character, when a dead key cannot be translated otherwise).

1       One ANSI character is returned.

0       This virtual-key code has no translation (for the current state of
        shift keys, and so on).

-1      This key is a dead key. The character returned is normally an ANSI
        accent character representing the dead key.


Comments

The export ordinal for this function is 4.

The ToAscii function is called mainly whenever TranslateMessage is called
to translate a virtual-key code (for example, for WM_KEYDOWN messages).

The given parameters of ToAscii are not necessarily sufficient to translate
the virtual-key code. This is because a previous dead key is stored
internally in the driver. Also, the MS-DOS shift-state byte is accessed by
ToAscii.

ToAscii is responsible for maintaining the state of the keyboard LED
indicator lights. For most AT-compatible computers, this is done by making
a ROM BIOS interrupt 16H call; for others, I/O must be done directly
through the keyboard.

ToAscii also has a special case which, if it is called with the virtual-key
code equal to 0, will only set the keyboard lights according to the state
of the appropriate entries in the keyboard-state vector. This function is
intended to be called from the SetKeyboardState function and not directly
used by applications. The Scancode parameter is ignored. The vector pointed
to by lpState should be different from the one used by ToAscii calls in the
USER module. The vector should be at least 4 bytes long.

Most translations are made on the basis of the Windows virtual-key code.
However, the Scancode parameter's sign bit is used to distinguish key
depressions (sign cleared) from key releases (sign set). Also, the scan
code is used in the translation of ALT + number-key translations.

The lpKeyState parameter points to a 256-byte array indexed by the
virtual-key code. In each byte, the high-order bit indicates the state of
the key and the low-order bit is toggled each time the key is pressed. The
CAPSLOCK key is handled in a special manner for some European keyboards.

The lpState parameter points to a data buffer that contains the translated
character(s) and state information. The Inquire function in the KBINFO
structure returns the size required for this state buffer.


See Also

Inquire



VkKeyScan

    int VkKeyScan(wChar)
    WORD wChar;

The VkKeyScan function translates an ANSI character code into a virtual-key
code and a shift state. It is intended for applications that send text to
other applications by simulating keyboard input.


Parameter

   wChar
   Specifies an ANSI character.


Return Value

The return value is a virtual-key code in the AL register, and a shift
state in the AH register if it is successful. Otherwise, it returns -1 in
the AX register.


Comments

The export ordinal for this function is 129.

The returned shift state is one of the following values:

Value   Meaning
---------------------------------------------------------------------------

0       No shift.

1       Character is shifted.

2       Character is CTRL character.

6       Character is CTRL + ALT.

7       Character is SHIFT + CTRL + ALT.

The values 3, 4, and 5 are not used.

Virtual-key codes applying to the numeric pad (VK_NUMPAD0 through
VK_DIVIDE) are not returned. This is done to force a translation for the
main keyboard, if it exists.


See Also

OEMKeyScan


6.3 Structure Reference

The following is an alphabetical listing of keyboard-driver structures.



KBINFO

    typedef struct tagKBINFO {
        BYTE  Begin_First_range;            /* used for KANJI */
        BYTE  End_First_range;              /* used for KANJI */
        BYTE  Begin_Second_range;           /* used for KANJI */
        BYTE  End_Second_range;             /* used for KANJI */
        int   StateSize;                    /* size of ToAscii state block*/
    } KBINFO;
The KBINFO structure contains information about the keyboard.


Members

   Begin_First_range
   Specifies the low value in the range of valid lead-byte values for
   double-byte character sets (DBCS).

   End_First_range
   Specifies the high value in the range of valid lead-byte values for
   double-byte character sets (DBCS).

   Begin_Second_range
   Specifies the low value in the range of valid second-byte values for
   double-byte character sets (DBCS).

   End_Second_range
   Specifies the high value in the range of valid second-byte values for
   double-byte character sets (DBCS).

   StateSize
   Specifies the size (in bytes) of the ToAscii state block.


See Also

Inquire



OEMANSI

    OEMANSI struct
        oaLength    dw ?            ;number of bytes that follow (must be 258)
        oaCodePage  dw ?            ;code page
        oaTable     db 256 dup(?)   ;OEM/ANSI translation table
    OEMANSI ends
The OEMANSI file format specifies information needed to translate OEM
character values, in a given code page, to their corresponding ANSI
character values.


Members

   oaLength
   Specifies the size (in bytes) of the file except for the first two
   bytes. The size must be 258.

   oaCodePage
   Specifies the code page of the given translation table. It can be any
   one of the following values.

     Value   Description
     ----------------------------------------------------------------------

     437     Default (U.S.)

     860     Portugal

     863     French Canada

     865     Norway/Denmark

     850     International code page

   oaTable
   Specifies an array of translation values.


6.4 Keyboard-Initialization Setting Reference

The [Keyboard] section in the SYSTEM.INI file specifies hardware- and
language-specific information for use by keyboard drivers.



KEYBOARD.DLL

    KEYBOARD.DLL = dll-filename
The KEYBOARD.DLL setting names the language-specific keyboard library from
which to load virtual-key code translation tables.


Parameter

   dll-filename
   Specifies the name of the language-specific keyboard library.


Comments

This entry can be omitted for U.S. keyboards having types 1, 3 or 4.



OEMANSI.BIN

    OEMANSI.BIN = bin-filename
The OEMANSI.BIN setting names the file containing the code-page translation
table.


Parameter

   bin-filename
   Specifies the name of a code-page. For the retail Windows keyboard
   driver, it can be one of the following.

     File         Description
     ----------------------------------------------------------------------

     XLATNO.BIN   Norway/Denmark

     XLATPO.BIN   Portugal

     XLATES.BIN   Spain

     XLATCA.BIN   French Canada


Comments

This entry must be omitted for code page 437.



subtype

    subtype = subtype-number
The subtype setting specifies the keyboard subtype. A keyboard driver uses
the subtype to determine whether a keyboard has special attributes.


Parameter

   subtype-number
   Specifies the keyboard subtype. The subtype depends on the particular
   OEM driver.


Comments

In the retail Windows keyboard driver, the subtype setting is used only for
Olivetti and AT&T keyboards.



type

    type = type-number
The type setting identifies the keyboard layout. A keyboard driver uses the
value to determine which table to use for virtual-key code translations.


Parameter

   type-number
   Specifies the keyboard type. It can be one of the following values.

     Value   Meaning
     ----------------------------------------------------------------------

     1       XT keyboard

     3       AT keyboard

     4       Enhanced keyboard


Comments

The type-number parameter overrides any default type set by the keyboard
driver.

Chapter 7  Communication Drivers

The Microsoft Windows communications driver provides a set of functions
that Windows can use to open communication ports, set communication
configurations, read and write characters, and retrieve error and status
information. This chapter describes the communication-driver functions.


7.1 About the Communications Driver

The communication driver is a dynamic-link library (DLL) containing
functions that support opening, reading from, and writing to communications
devices. Although the communication driver exports several functions,
Windows-based applications do not directly call these functions. Instead,
the applications call functions in the USER module, such as the OpenComm
function, which in turn call the communications driver.

Unlike other Windows-based drivers, the communications driver does not
include the Enable and Disable functions, although it does include the WEP
function.


7.1.1 Base Address and IRQ Selection

The Windows 3.1 communications driver (COMM.DRV) accesses serial ports
COM1, COM2, COM3, and COM4 using base-address values specified in the BIOS
data area of a computer. If the BIOS data area does not specify values for
physical ports, Windows 3.1 will use the base address, 0x03E8, and IRQ4 for
COM3, but the base addresses and IRQs for the other ports must be set by
the user.

If the BIOS data area does not specify a value for a physical port, the
user can set the base address and IRQ values using Control Panel. Control
Panel displays an Advanced settings dialog box for each port. The dialog
box contains a selection box for base addresses and spin controls for IRQ
settings. The selected values are recorded as COMxBase and COMxIRQ settings
in the [386Enh] section of the SYSTEM.INI file.

The COMxBase and COMxIRQ settings are used for both standard- and 386
enhanced-mode operation. The COMxBase setting is used only if the BIOS data
area does not specify a value for the port; this setting never overrides
the BIOS data area values.


7.1.2 16550a UART FIFO Buffer

If a computer uses the 16550a Universal Asynchronous Receiver Transmitter
(UART) for its communication ports, the communications driver will enable
the onboard 16-byte first in, first out (FIFO) buffer allowing Windows to
perform reliable serial communications at speeds of 9600 baud and higher.
(Many computers that do not enable this buffer experience loss of
characters at 9600 baud, and most cannot communicate at speeds higher than
9600 baud.)

Before enabling the FIFO buffer, the communications driver checks the
SYSTEM.INI file to determine whether the user wants the buffers enabled.
The COMxFIFO settings in the [386Enh] section of the SYSTEM.INI file
specify whether the buffer for a given port should be enabled or disabled.
If the value of the setting is 1, the driver enables the FIFO buffer;
otherwise, it disables the buffer. If no setting is specified, the driver
will enable the buffer by default.

The virtual-communications device (VCD) does not virtualize the 16550a for
non-Windows applications.


7.1.3 CommWriteString and EnableNotification Functions

The communications driver exports the CommWriteString and
EnableNotification functions. The CommWriteString function writes a string
of one or more bytes to the given communications device.

The EnableNotification function enables or disables port status
notifications. If notifications are enabled, the communications driver
posts a WM_COMMNOTIFY message to a given window on certain events. This
eliminates the need for communications applications to set timers and use
the GetCommError, GetCommEventMask, and SetCommEventMask functions to
monitor port status changes.


7.1.4 Communication Escapes

The communications driver supports the RESETDEV, GETBASEIRQ, GETMAXLPT, and
GETMAXCOM communication escapes in its cextfcn function. These
communication escapes reset the printer (assert the reset line) and
retrieve parallel- and serial-port identifiers.


7.1.5 Baud-Rate Indexes

The communications driver supports very high baud rates, such as 128,000
and 256,000, by interpreting the BaudRate member of the DCB structure as a
baud-rate index whenever the high byte of the member is 0xFF. In such
cases, BaudRate can be one of the following values.

BaudRate   Value
---------------------------------------------------------------------------

110        CBR_110 (0xFF10)

300        CBR_300 (0xFF11)

600        CBR_600 (0xFF12)

1200       CBR_1200 (0xFF13)

2400       CBR_2400 (0xFF14)

4800       CBR_4800 (0xFF15)

9600       CBR_9600 (0xFF16)

14,400     CBR_14400 (0xFF17)

19,200     CBR_19200 (0xFF18)

38,400     CBR_38400 (0xFF1B)

56,000     CBR_56000 (0xFF1F)

128,000    CBR_128000 (0xFF23)

256,000    CBR_256000 (0xFF27)

NOTE  The CBR_ values are for standardization; drivers are not required to
support all indexed baud rates.

If the high byte of the BaudRate member is not 0xFF, BaudRate specifies the
actual baud rate for the communications device. In other words, values in
the range 2 through 65,279 (0xFEFF) are interpreted as baud rate values not
as indexes. This ensures compatibility with existing communications
drivers.


7.2 Function Reference

The following is an alphabetical listing of the communication-driver
functions.

cclrbrk

    int cclrbrk(cid)
    int cid;

The cclrbrk function restores character transmission and places the
communications device in a nonbreak state. USER calls this function
whenever an application calls the ClearCommBreak function (USER.211).


Parameters

   cid
   Identifies the communications device.


Return Value

The return value is zero if the function is successful. Otherwise, the
return value returns -1.


Comments

The export ordinal for this function is 14.


See Also

csetbrk



cevt

    LPWORD cevt(cid, evtmask)
    int cid;
    int evtmask;

The cevt function enables events in the event mask of the specified
communications device. USER calls this function whenever an application
calls the SetCommEventMask function (USER.208).


Parameters

   cid
   Identifies the communications device.

   evtmask
   Specifies which events are to be enabled. This parameter can be any
   combination of the following values.

        Value        Meaning
        -------------------------------------------------------------------

        EV_BREAK     Enables detection of a break upon input.

        EV_CTS       Enables detection of the clear-to-send (CTS) signal.

        EV_DSR       Enables detection of the data-set-ready (DSR) signal.

        EV_ERR       Enables detection of a line-status error. Line-status
                     errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.

        EV_PERR      Enables detection of a printer error on a parallel
                     device. Errors are CE_DNS, CE_IOE, CE_LOOP, and CE_PTO.

        EV_RING      Indicates the state of ring indicator during the last
                     modem interrupt. (Use EV_RINGTE to detect when a phone
                     ring has occurred.)

        EV_RLSD      Enables detection of the receive-line-signal-detect
                     (RLSD) signal.

        EV_RXCHAR    Enables detection of any character received and placed
                     in the receive queue.

        EV_RXFLAG    Enables detection of the event character received and
                     placed in the receive queue. The event character is
                     specified in the EvtChar member of the DCB structure.

        EV_TXEMPTY   Enables detection of when the last character in the
                     transmit queue is sent.


Return Value

The return value is a pointer to a 16-bit buffer if the function is
successful. Otherwise, the function returns zero if there is an error.


Comments

The export ordinal for this function is 11.

The communications driver sets one or more bits in the returned buffer
whenever one of the events specified by the evtmask parameter occurs.



cevtGet

    WORD cevtGet(cid, evtmask)
    int cid;
    int evtmask;

The cevtGet function retrieves and then clears the event mask for a
communications device. USER calls this function whenever an application
calls the GetCommEventMask function (USER.209).


Parameters

   cid
   Identifies the communications device.

   evtmask
   Specifies which events in the current event mask to disable. This
   parameter can be any combination of the following values.

        Value        Meaning
        -------------------------------------------------------------------

        EV_BREAK     Enables detection of a break upon input.

        EV_CTS       Enables detection of the clear-to-send (CTS) signal.

        EV_DSR       Enables detection of the data-set-ready (DSR) signal.

        EV_ERR       Enables detection of a line-status error. Line-status
                     errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.

        EV_PERR      Enables detection of a printer error on a parallel
                     device. Errors are CE_DNS, CE_IOE, CE_LOOP, and CE_PTO.

        EV_RING      Indicates the state of ring indicator during the last
                     modem interrupt. (Use EV_RINGTE to detect when a phone
                     ring has occurred.)

        EV_RLSD      Enables detection of the receive-line-signal-detect
                     (RLSD) signal.

        EV_RXCHAR    Enables detection of any character received and placed
                     in the receive queue.

        EV_RXFLAG    Enables detection of the event character received and
                     placed in the receive queue. The event character is
                     specified in the EvtChar member of the DCB structure.

        EV_TXEMPTY   Enables detection of when the last character in the
                     transmit queue is sent.


Return Value

The return value is the current event word as set by the cevt function.


Comments

The export ordinal for this function is 12.


See Also

cevt



cextfcn

    LONG  cextfcn(cid, fcn);
    int cid;
    int fcn;

The cextfcn function carries out the extended communications function
specified by the fcn parameter. USER calls this function when an
application calls the EscapeCommFunction function (USER.214).


Parameters

   cid
   Identifies the communications device.

   fcn
   Specifies the extended function to carry out. It can be one of the
   following values.

        Value        Meaning
        -------------------------------------------------------------------

        CLRDTR       Clears the data-terminal-ready (DTR) signal.

        CLRRTS       Clears the request-to-send (RTS) signal.

        GETBASEIRQ   Returns the base-port address and IRQ setting for the
                     COM port specified by the cid parameter. The low 16
                     bits of the return address specifies the base-port
                     address, and the high address specifies the IRQ
                     selection. If the high 16 bits is -1, then the port
                     does not exist; if it is zero, the installed COMM
                     driver does not support this escape.

        GETMAXBAUD   Returns a constant that indicates the highest baud
                     rate supported by the port specified by the cid
                     parameter. The following constants may be returned.

                                                      Value        Meaning
                                                      ---------------------

                                                      CBR_110      The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   110.

                                                      CBR_300      The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   300.

                                                      CBR_600      The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   600.

                                                      CBR_1200     The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   1200.

                                                      CBR_2400     The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   2400.

                                                      CBR_4800     The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   4800.

                                                      CBR_9600     The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   9600.

                                                      CBR_19200    The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   19,200.

                                                      CBR_38400    The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   38,400.

                                                      CBR_56000    The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   56,000.

                                                      CBR_128000   The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   128,000.

                                                      CBR_256000   The
                                                                   highest
                                                                   baud
                                                                   rate is
                                                                   256,000.

        GETMAXCOM    Returns the maximum COM port identifier supported by
                     the communications driver. This value ranges from 0x00
                     to 0x7F, such that 0x00 corresponds to COM1, 0x01 to
                     COM2, 0x02 to COM3, and so on. The communications
                     driver included in Windows 3.1 supports COM1 through
                     COM4, and will always return 0x03.

        GETMAXLPT    Returns the maximum LPT port ID supported by the
                     system. This value ranges from 0x80H to 0xFFH, such
                     that 0x80H corresponds to LPT1, 0x81H to LPT2, 0x82H
                     to LPT3, and so on.

        RESETDEV     Resets the printer device (that is, assert the reset
                     line) if the cid parameter specifies an LPT port. No
                     function is performed if cid specifies a COM port.

        SETDTR       Sets the data-terminal-ready (DTR) control line on.

        SETRTS       Sets the request-to-send (RTS) control line on.

        SETXOFF      Causes transmission to act as if an XOFF character has
                     been received.

        SETXON       Causes transmission to act as if an XON character has
                     been received.


Return Value

This return value is zero if successful. Otherwise, it is negative if the
fcn parameter does not specify a valid function code.


Comments

The export ordinal for this function is 9.

If the communications driver does not export the CommWriteString function,
Windows 3.1 intercepts and adjusts the return values for the GETBASEIRQ,
GETMAXBAUD, GETMAXLPT, and GETMAXCOM functions after the cextfcn function
returns.



cflush

    WORD cflush(cid, q)
    int cid;
    int q;

The cflush function flushes all characters from the transmit or receive
queue of the specified communications device.


Parameters

   cid
   Identifies the communications device.

   q
   Specifies which queue to flush. If the q parameter is 1, the function
   flushes the receive queue; if q is zero, it flushes the transmit queue.


Return Value

The return value is the most recent error value.


Comments

The export ordinal for this function is 10.



CommWriteString

    int CommWriteString(cid, pbuf, size)
    int cid;
    LPSTR pbuf;
    int size;

The CommWriteString function transmits a string of characters using the
specified communications device. USER calls this function whenever an
application calls the WriteComm function (USER.205).


Parameters

   cid
   Identifies the communication device.

   pbuf
   Points to the buffer containing the bytes to write.

   size
   Specifies the number of bytes to write.


Return Value

The return value is the number of bytes actually written.


Comments

The export ordinal for this function is 19.

During initialization, USER checks for this function to determine whether
the driver supports the extended functions new to Windows 3.1. If the
function is not present, Windows assumes that the driver is a Windows 3.0
driver and makes sure that all interaction with the driver is compatible
with Windows 3.0.



csetbrk

    int csetbrk(cid)
    int cid;

The csetbrk function suspends character transmission and places the
communications device in a break state. USER calls this function whenever
an application calls the SetCommBreak function (USER.210).


Parameters

   cid
   Identifies the communications device.


Return Value

The return value is zero if the function is successful. Otherwise, the
return value is -1.


Comments

The export ordinal for this function is 13.


See Also

cclrbrk



ctx

    WORD ctx(cid, ch)
    int cid;
    int ch;

The ctx function places a character in a special holding variable to ensure
it will be the next character to be transmitted. The function will return
an error code if the special holding variable already contains a character.
USER calls this function whenever an application calls the TransmitCommChar
function (USER.206).


Parameters

   cid
   Identifies the communications device.

   ch
   Specifies the character to transmit.


Return Value

The return value is zero if the function is successful. The return value is
one of the following values if there is an error.

Value    Meaning
---------------------------------------------------------------------------

0x8000   The function received an invalid cid parameter.

0x4000   The function could not write to the parallel port or there's
         already a character waiting for immediate transmission.


Comments

The export ordinal for this function is 6.


See Also

sndcom



EnableNotification

    int EnableNotification(cid, hWnd, wInTrigger, wOutTrigger)
    int cid;
    HWND hWnd;
    WORD wInTrigger;
    WORD wOutTrigger;

The EnableNotification function enables or disables communications message
posting. When enabled, the driver posts the WM_COMMNOTIFY message to the
specified window. USER calls this function when an application calls the
EnableCommNotification function (USER.245).


Parameters

   cid
   Identifies the communication device.

   hWnd
   Identifies the window to receive the WM_COMMNOTIFY message. If this
   parameter is NULL, the function disables the notification.

   wInTrigger
   Specifies the minimum number of bytes to be received in the
   communication device's input buffer before receive notification is sent.

   wOutTrigger
   Specifies the maximum number of bytes to remain in the communication
   device's output buffer before transmit notification is sent.


Return Value

The return value is TRUE if successful. Otherwise, the return value is
FALSE.


Comments

The export ordinal for this function is 100.

The WM_COMMNOTIFY message has the following parameters.

Parameter        Description
---------------------------------------------------------------------------

wParam           Specifies the communication-device identifier (the cid
                 parameter).

HIWORD(lparam)   Not used; must be zero.

LOWORD(lparam)   Specifies the notification status. It can be one of the
                 following values.

              Value         Meaning
              -------------------------------------------------------------

              CN_EVENT      An event enabled in the communication device's
                            event mask (specified by the SetCommEventMask
                            function) has occurred. The application should
                            call the function GetCommEventMask to determine
                            what event has occurred, and to clear the event.

                            This status is sent when the communication
                            device's event word changes. The application
                            clears the appropriate event to ensure
                            notification on subsequent events.

              CN_RECEIVE    At least wInTrigger bytes are in the
                            communication device's input buffer, or at
                            least 1 byte is in the input buffer.
                            Additionally, no more have been received before
                            the end of an internal timeout period. The
                            number of bytes in the input buffer must be
                            lower than wInTrigger bytes before this message
                            will be sent again.

              CN_TRANSMIT   Fewer than wOutTrigger bytes remain in the
                            communication device's output buffer to be
                            transmitted. The number of bytes in the output
                            buffer must exceed wOutTrigger bytes before
                            this message will be sent again.

The communication device event may be a line-status or printer error.
Applications can determine the cause by using the GetCommError function
immediately after the GetCommEventMask function (USER.209).



getdcb

    LPDCB getdcb(cid)
    int cid;

The getdcb function retrieves the device-control block (DCB) for the
specified device. USER calls this function whenever an application calls
the GetCommState function (USER.202).


Parameters

   cid
   Identifies the communications device.


Return Value

The return value is a pointer to a DCB structure.


Comments

The export ordinal for this function is 15.



inicom

    WORD inicom(lpdcb);
    DCB FAR *lpdcb;

The inicom function initializes the specified communications device. USER
calls this function whenever an application calls the OpenComm function
(USER.200).


Parameters

   lpdcb
   Points to a DCB structure.


Return Value

The return value is zero if the function is successful. Otherwise, the
return value is a nonzero (IE_*) value if there is an error.


Comments

The export ordinal for this function is 1.


See Also

trmcom



ReactivateOpenCommPorts

    void ReactivateOpenCommPorts(void)

The ReactivateOpenCommPorts function reactivates open communication ports.
WINOLDAP uses this function to reactivate communications ports after
switching back to Windows.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 18.


See Also

SuspendOpenCommPorts



reccom

    int reccom(cid)
    int cid;

The reccom function reads a byte from a communications device. USER calls
this function whenever an application calls the ReadComm function
(USER.204).


Parameters

   cid
   Identifies the communications device.


Return Value

The return value is the byte read. Otherwise, the return value is -2 if no
data is available, and -1 if there is an error.


Comments

The export ordinal for this function is 4.


See Also

sndcom



setcom

    WORD  setcom(lpdcb);
    DCB FAR *lpdcb;

The setcom function sets a communication device to the state specified by
the DCB structure. USER calls this function whenever an application calls
the SetCommState function (USER.201).


Parameters

   lpdcb
   Points to a DCB structure.


Return Value

The return value is zero if the function is successful. Otherwise, it is a
negative (IE_*) value if an error occurs.


Comments

The export ordinal for this function is 2.

This function reinitializes all hardware and controls as defined by the
lpdcb parameter, but does not clear transmit or receive queues.



setque

    int setque(cid, lpqdb)
    int cid;
    qdb FAR * lpqdb;

The setque function sets the transmit and receive queues. USER calls this
function whenever an application calls the OpenComm function (USER.200).


Parameters

   cid
   Identifies the communications device.

   lpqdb
   Points to a qdb structure.


Return Value

The return value is zero if the function is successful. Otherwise, the
return value is IE_BADID if the cid parameter is not valid.


Comments

The export ordinal for this function is 3.



sndcom

    WORD sndcom(cid, ch)
    int cid;
    int ch;

The sndcom function writes a byte to the specified communications device.
USER calls this function whenever an application calls the WriteComm
function (USER.205).


Parameters

   cid
   Identifies the communications device.

   ch
   Specifies the character to transmit.


Return Value

The return value is zero if the function is successful. Otherwise, the
return value is a nonzero value if there is an error.


Comments

The export ordinal for this function is 5.


See Also

reccom



stacom

    WORD stacom(cid, cs)
    int cid;
    COMSTAT FAR *cs;

The stacom function returns the most recent error value and copies the
current status for the specified device to the given structure. USER calls
this function whenever an application calls the GetCommError function
(USER.203).


Parameters

   cid
   Identifies the communications device.

   cs
   Points to a COMSTAT structure.


Return Value

The return value is the most recent error code.


Comments

The export ordinal for this function is 8.



SuspendOpenCommPorts

    void SuspendOpenCommPorts(void)

The SuspendOpenCommPorts function suspends open communication ports.
WINOLDAP uses this function to suspend communications ports before
switching to non-Windows applications.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 17.


See Also

ReactivateOpenCommPorts



trmcom

    int trmcom(cid)
    int cid;

The trmcom function closes the specified communications device and frees
any memory allocated for the device's transmit and receive queues. All
characters in the output queue are transmitted before the communications
device is closed unless an error occurs. The trmcom function returns an
error immediately if the cid parameter is not valid, and returns an error
if a timeout occurs while attempting to send the characters.

USER calls this function whenever an application calls the CloseComm
function (USER.207).


Parameters

   cid
   Identifies the communications device.


Return Value

The return value is zero if the function is successful. The function
returns -2 if an error occurred while transmitting the remaining characters
from the transmit queue. If the cid parameter is not valid, trmcom will
return 0x8000.


Comments

The export ordinal for this function is 7.

If the return value is -2, the function may have left some characters in
the transmit queue, but may have successfully sent others. If an
application subsequently calls the stacom through the GetCommError function
(USER.203), the driver should set the cbOutQue member in the COMSTAT
structure to allow the application to determine how many characters were
actually transmitted.


See Also

inicom


7.3 Structure Reference

The following is an alphabetical listing of the communication-driver
structures.



COMSTAT

    typedef struct tagCOMSTAT {
       BYTE fCtsHold: 1;
       BYTE fDsrHold: 1;
       BYTE fRlsdHold: 1;
       BYTE fXoffHold: 1;
       BYTE fXoffSent: 1;
       BYTE fEof: 1;
       BYTE fTxim: 1;
       WORD cbInQue;
       WORD cbOutQue;
    } COMSTAT;
The COMSTAT structure contains information about a communications device.


Members

   fCtsHold
   Specifies whether transmission is waiting for the clear-to-send (CTS)
   signal to be sent.

   fDsrHold
   Specifies whether transmission is waiting for the data-set-ready (DSR)
   signal to be sent.

   fRlsdHold
   Specifies whether transmission is waiting for the
   receive-line-signal-detect (RLSD) signal to be sent.

   fXoffHold
   Specifies whether transmission is waiting as a result of the XOFF
   character being received.

   fXoffSent
   Specifies whether transmission is waiting as a result of the XOFF
   character being transmitted. Transmission halts when the XOFF character
   is transmitted and used by systems that take the next character as XON,
   regardless of the actual character.

   fEof
   Specifies whether the end-of-file (EOF) character has been received.

   fTxim
   Specifies whether a character previously passed to the ctx function is
   waiting to be transmitted.

   cbInQue
   Specifies the number of characters in the receive queue.

   cbOutQue
   Specifies the number of characters in the transmit queue.


See Also

stacom



DCB

    typedef struct {
        char   Id;             /* internal device ID                 */
        ushort Baudrate;       /* operating speed                    */
        char   ByteSize;       /* transmit/receive byte size         */
        char   Parity;         /* 0,1,2,3, or 4                      */
        char   StopBits;       /* number of stop bits                */
        ushort RlsTimeout;     /* timeout for RLSD to be set         */
        ushort CtsTimeout;     /* timeout for CTS to be set          */
        ushort DsrTimeout;     /* timeout for DSR to be set          */
        ushort fBinary: 1;     /* binary-mode flag                   */
        ushort fRtsDisable: 1; /* disable RTS                        */
        ushort fParity: 1;     /* enable parity checking             */
        ushort fDummy: 5;
        ushort fOutX: 1;       /* enable output XON/XOFF             */
        ushort fInX: 1;        /* enable input XON/XOFF              */
        ushort fPeChar: 1;     /* enable parity-error replacement    */
        ushort fNull: 1;       /* enable null stripping              */
        ushort fChEvt: 1;      /* enable Rx character event          */
        ushort fDtrflow: 1;    /* enable DTR flow control            */
        ushort fRtsflow: 1;    /* enable RTS flow control            */
        ushort fDummy2: 1;
        char   XonChar;        /* transmit/receive XON character     */
        char   XoffChar;       /* transmit/receive XOFF character    */
        ushort XonLim;         /* transmit XON threshold             */
        ushort XoffLim;        /* transmit XOFF threshold            */
        char   PeChar;         /* parity error replacement character */
        char   EofChar;        /* end-of-input character             */
        char   EvtChar;        /* event-generating character         */
        ushort TxDelay;        /* amount of time between characters  */
    } DCB;
The DCB structure contains the RS-232 configuration parameters for a
communication device.


Members

   Id
   Specifies the device ID byte (COM1 = 0, COM2 = 1, and so on). This is
   also the value returned by the cOpen function, when successful.

   Baudrate
   Specifies the operating speed; any baud rate supported by the hardware.

   ByteSize
   Specifies the transmitting and receiving byte size; normally in the
   range 4 through 8.

   Parity
   Specifies the parity setting. The value can be one of the following
   values.

              Value   Meaning
              -------------------------------------------------------------

              0       None

              1       Odd

              2       Even

              3       Mark

              4       Space

   StopBits
   Specifies the number of stop bits. The value can be one of the following
   values.

              Value   Meaning
              -------------------------------------------------------------

              0       1 stop bit

              1       1.5 stop bits

              2       2 stop bits

   RlsTimeout
   Specifies the amount of time, in milliseconds, to wait for
   receiving-line-signal detect (RLSD) to become high. RLSD flow control
   can be achieved by specifying infinite timeout (0xFFFF).

   CtsTimeout
   Specifies the amount of time, in milliseconds, to wait for clear-to-send
   signal (CTS) to become high. CTS flow control can be achieved by
   specifying infinite timeout (0xFFFF).

   DsrTimeout
   Specifies the amount of time, in milliseconds, to wait for
   data-set-ready (DSR) to become high. DSR flow control can be achieved by
   specifying infinite timeout (0xFFFF).

   fBinary
   Specifies the binary-mode flag (0 is ASCII mode, 1 is binary). In ASCII
   mode, the end-of-file character (EOFCHAR) is recognized and remembered
   as the end of received data.

   fRtsDisable
   Disables the receive-transmission signal (RTS) line for as long as this
   device is open, if set. Normally, RTS is enabled when the device is
   opened and disabled when closed.

   fParity
   Enables parity checking, if set.

   fOutX
   Indicates that XON/XOFF flow control is to be used during transmission,
   if set. The transmitter halts when it receives an XOFF character, and
   starts again when it receives an XON character.

   fInX
   Indicates that XON/XOFF flow control is to be used during reception, if
   set.

   fPeChar
   Indicates that characters received with parity errors are to be replaced
   with the specified parity-checking characters (PECHAR), if set.

   fNull
   Specifies that the received null characters are to be discarded, if set.

   fChEvt
   Indicates that the reception of event-checking characters (EVTCHAR) are
   to be flagged as an event, if set.

   fDtrFlow
   Indicates that the data-terminal-ready signal (DTR) is to be used for
   receive flow control, if set.

   fRtsflow
   Indicates that the receive-transmission signal (RTS) is to be used for
   receive flow control, if set.

   XonChar
   Specifies the XON character for both transmit and receive.

   XoffChar
   Specifies the XOFF character for both transmit and receive.

   XonLim
   Specifies the threshold value for receive queue. When the receive queue
   comes within 10 characters of being full, it transmits an XOFF
   character. When the queue comes within 10 characters of being empty, an
   XON character will be transmitted.

   XoffLim
   Specifies the threshold value for send queue. When the number of
   characters in the receive queue exceeds this value, an XOFF character is
   sent (if XOFF flow control is enabled) and the data-terminal-ready
   signal (DTR) is dropped (if enabled).

   PeChar
   Specifies the character to be used as replacement when a parity error
   occurs.

   EofChar
   Specifies the character that signals the end of the input.

   EvtChar
   Specifies the character that triggers an event flag.

   TxDelay
   Specifies the minimum amount of time that must pass between transmission
   of characters.


See Also

getdcb, inicom, setcom



qdb

    typedef struct {
        char far    *pqRx;  /* pointer to Rx queue          */
        int         cbqRx;  /* size of Rx queue in bytes    */
        char far    *pqTx;  /* pointer to Tx queue          */
        int         cbqTx;  /* size of Tx queue in bytes    */
    } qdb;
The qdb structure contains information about the location and size of the
transmit and receive queues.


Members

   pqRx
   Points to the receive queue.

   cbqRx
   Specifies the size (in bytes) of the receive queue.

   pqTx
   Points to the transmit queue.

   cbqTx
   Specifies the size (in bytes) of the transmit queue.


See Also

setque

Chapter 8  Mouse Drivers

The Microsoft Windows mouse driver manages all mouse input for Windows
applications. The driver provides a set of functions that Windows uses to
enable the mouse, retrieve information about the mouse, and allow users to
modify the operation of the mouse through Control Panel. This chapter
describes the mouse-driver functions.


8.1 About the Mouse Driver

The mouse driver is a dynamic-link library (DLL) consisting of a
mouse-interrupt handler and a variety of functions that let Windows enable
and disable the handler as well as let users set the operating
characteristics of the mouse.


8.1.1 Mouse Initialization and the Interrupt Handler

Windows initializes the mouse driver by calling the driver's initialization
routine, and subsequently calling the driver's Enable function. The
initialization routine determines whether a mouse exists and whether an
MS-DOS mouse driver is present. If the initialization routine returns a
nonzero value, Windows assumes the mouse is present and calls the Inquire
function to retrieve information about the mouse hardware. This function
returns the mouse information in the form of a MOUSEINFO structure.

Windows calls the Enable function when it is ready to receive mouse input.
The Enable function installs the mouse-interrupt handler, replacing any
existing interrupt handler. Once installed, the handler retrieves the mouse
motion and button status and passes this information to Windows through a
mouse-event callback function. Windows passes the address of the
mouse-event callback function to the driver when it calls Enable. The
driver must save the callback function address and use it whenever it has
mouse input to send to Windows.

Windows calls the Disable function to remove the mouse-interrupt handler
and restore any previous handler. This occurs whenever the user switches to
a non-Windows application or when Windows quits. Windows calls Enable to
reinstall the interrupt handler when the user eventually switches back to
Windows.

The mouse driver includes the MouseGetIntVect function that Windows or
utilities can call to determine which interrupt vector the mouse hardware
is using.


8.1.2 Serial Port Usage

The msMouseCommPort member in the MOUSEINFO structure, new for Windows 3.1,
specifies which communications port Windows is using to reserve for the
mouse. The mouse driver must set this member to one of the following values
when processing the Enable function.

Value   Meaning
---------------------------------------------------------------------------

0       No port used.

1       Communications port 1 (COM1).

2       Communications port 2 (COM2).

3       Communications port 3 (COM3).

4       Communications port 4 (COM4).


8.1.3 Customizing the Mouse Dialog Box in Control Panel

In the past, users have had to use separate applications to set the
extended features of the mouse. In Windows 3.1, separate applications are
no longer necessary. Instead, users can now view and set the extended
features using Control Panel, and the mouse driver's custom mouse-settings
dialog box.

The following sections explain how to create an custom mouse-settings
dialog box for a mouse driver.


8.1.3.1 Mouse-Settings Dialog Box

The custom mouse-settings dialog box serves as a replacement for Control
Panel's standard mouse dialog box. When a mouse driver has a custom
mouse-settings dialog box, Control Panel displays it instead of the
standard dialog box when the user chooses the mouse icon in Control Panel.

To display the custom dialog box, Control Panel checks for the CplApplet
function in the mouse driver. If the function is present, Control Panel
calls CplApplet with the NEWINQUIRE function value. If this call fails,
Control Panel calls the CplApplet function with the INQUIRE function value.
This gives the driver two chances to display its custom dialog box. If
CplApplet does not contain the NEWINQUIRE or INQUIRE values, Control Panel
displays the standard dialog box.

Because Windows loads the mouse driver before USER.EXE, the driver must not
contain implicit links to USER functions such as DialogBox. This means that
if the mouse driver calls the DialogBox function, it must use the
GetProcAddress function to retrieve the address of the function. The mouse
driver cannot rely on Windows to automatically create the dynamic link when
Windows loads it.

One recommendation is to place all code required to display the custom
dialog box in a separate dynamic-link library. In this case, the CplApplet
function in the mouse driver loads the library and calls the function in
the library that displays the dialog box. One benefit of this approach is
that the dynamic-link library can also be used with Windows 3.0.


8.1.3.2 Control Panel Icon

Mouse vendors will be able to create their own pointing-device icon and
corresponding text title for display in the Control Panel window. This will
allow the mouse driver to display a graphic more appropriate to the
pointing device than the default icon.

When Control Panel runs, it calls the CplApplet function in the mouse
driver as follows:

    #define INQUIRE     3
    #define NEWINQUIRE  8

    if (CplApplet(hwndControlPanel, NEWINQUIRE, NULL, &newcplinfo)!=TRUE)
        if (CplApplet(hwndControlPanel, INQUIRE, NULL, &cplinfo)!=TRUE)
            /* Display standard dialog box */
Control Panel first calls CplApplet with a NEWINQUIRE function value,
giving a pointer to a NEWCPLINFO structure. This call allows the driver to
specify the help file or icon to use. In this case, the icon does not have
to reside as a resource in the driver as it does with the INQUIRE function
value. This call fails if the size member within the NEWCPLINFO structure
has an incorrect value.

If the CplApplet function with the NEWINQUIRE value fails, Control Panel
calls CplApplet with an INQUIRE function value, giving a pointer to a
CPLINFO structure that has the following form:

    typedef struct tag CPLINFO {
            int idIcon;
            int idName;
            int idInfo;     // not used
            LONG lData;     // not used
    } CPLINFO;
The driver fills in the CPLINFO structure with the resource identifiers of
its icon and description, and returns to Control Panel. Control Panel loads
the resource data specified by the icon and description identifiers, and
uses these in the Control Panel window instead of the icon. Note that the
idInfo and lData members are not used.


8.1.3.3 Standard Mouse Settings

The custom dialog box lets users set extended mouse features, but it also
must let users view and set the following standard mouse features:

o   Mouse-tracking speed

o   Double-click speed

o   Button swapping

During initialization, the dialog procedure for the custom dialog box uses
the SystemParametersInfo function to retrieve the current values for these
settings. If the user changes the settings, the dialog procedure uses the
SystemParametersInfo function to change the settings for the current
Windows session and update the corresponding settings in the WIN.INI file.

NOTE  The SystemParametersInfo function is not available with Windows 3.0.
If the custom dialog box is also intended for Windows 3.0, the mouse driver
must use functions such as ControlPanelInfo, SetDoubleClickSpeed, and
SwapMouseButton to change the standard mouse settings. Since these
functions do not modify the mouse setting in the WIN.INI file, the mouse
driver must use the WriteProfileString function to preserve these changes
for subsequent Windows sessions.


Mouse-Tracking Speed

The mouse-tracking speed defines how quickly the cursor moves relative to
the speed of the mouse. Windows uses three values to control mouse
tracking: MouseSpeed, MouseThreshold1, and MouseThreshold2. These values,
described in detail in the WININI.WRI file, define how and when to
accelerate the cursor motion. The cursor speed can remain constant, or it
can double or quadruple depending on the current mouse thresholds and
speed.

Control Panel uses a 7-position scroll bar to set the mouse-tracking value.
The 7 settings are as follows:

---------------------------------------------------------------------------
Scroll position   MouseSpeed   MouseThreshold1   MouseThreshold2
---------------------------------------------------------------------------

0                 0            0                 0

1                 1            10                0

2                 1            7                 0

3                 1            4                 0

4                 2            4                 12

5                 2            4                 9

6                 2            4                 6

---------------------------------------------------------------------------

Control Panel calculates these settings using to the following algorithm:

    switch (scrollPos) {
    case 0:
        MouseSpeed      = 0;
        MouseThreshold1 = 0;
        MouseThreshold2 = 0;
        break;
    case 1: case 2: case 3:
        MouseSpeed      = 1;
        MouseThreshold1 = 13 - 3 * scrollPos;
        MouseThreshold2 = 0;
        break;
    case 4: case 5: case 6:
        MouseSpeed      = 2;
        MouseThreshold1 = 4;
        MouseThreshold2 = 24 - 3 * scrollPos;
        break;
    }
When Control Panel displays the mouse dialog box, it calculates the initial
scroll bar position from the system values as follows:

    switch (MouseSpeed) {
    case 0:
        scrollPos = 0;
        break;
    case 1:
        scrollPos = (13 - MouseThreshold1) / 3;
        break;
    case 2:
        scrollPos = (24 - MouseThreshold2) / 3;
        break;
    }
If the user changes the mouse-tracking settings directly in the WIN.INI
file instead of through the dialog box, Control Panel checks for
out-of-bounds values and adjusts the values accordingly.


Double-Click Speed

The double-click time is the maximum number of milliseconds that may occur
between the first and second clicks of a double-click of the mouse button.
Control Panel uses a scroll bar to set double-click speed. The range is
from 100 to 900 milliseconds, with line-up and line-down increments 1/50 of
this range, and page-up and page-down increments 1/5 of this range. Windows
records the double-click speed using the DoubleClickSpeed setting in the
[Windows] section of the WIN.INI file.

A mouse driver can use the GetDoubleClickTime function to determine the
current double-click speed, and use the SystemParametersInfo function and
SPI_SETDOUBLECLICKSPEED option to change double-click time.


Swapping Left and Right Mouse Buttons

Button swapping lets Windows generate right-button mouse messages when the
left button is pressed, and left-button messages when the right button is
pressed. Control Panel uses a check box to switch mouse buttons. Windows
records the state of the buttons using the SwapMouseButtons setting in the
[Windows] section of the WIN.INI file.

A mouse driver can use the GetSystemMetrics function with the SM_SWAPBUTTON
option to determine whether the mouse buttons are currently reversed, and
use the SystemParametersInfo function and the SPI_SETMOUSEBUTTONSWAP option
to swap the mouse buttons.


8.1.3.4 Mouse Dialog Help

Control Panel displays Help information when the user presses the F1 key,
or chooses the Help button while viewing the Mouse dialog box. If the user
presses F1 or chooses Help while the driver's dialog box is displayed, the
mouse driver is responsible for displaying its own online Help.

To display Help, the dialog procedure for the mouse driver must register a
private message called ShellHelp during initialization. When the dialog
procedure receives this message, it can call the WinHelp function
specifying the appropriate Help file.

The following sample code illustrates how to incorporate Help support in
the dialog procedure:

    LONG FAR PASCAL AddOnDlgProc(HWND hDlg, WORD msg, WORD wParam,
                                 LONG lParam)
    {
        static WORD wHelpMessage;

        switch (msg) {

        case WM_INITDIALOG:
                .
                .
                .
            wHelpMessage = RegisterWindowMessage("ShellHelp");
            break;

        case WM_COMMAND:
            switch (wParam) {
            case IDD_HELP:          // from "Help..." button
                goto DoHelp;
                .
                .
                .
            case IDOK:
            case IDCANCEL:
                    .
                    .
                    .
                WinHelp(hDlg, szHelpFile, HELP_QUIT, 0L);
                EndDialog(hDlg, wParam);
                break;
                .
                .
                .
            }
            .
            .
            .

        default:
            if (msg == wHelpMessage) {
    DoHelp:
                WinHelp(hDlg, szHelpFile, HELP_CONTEXT, context_value);
                return TRUE;
            } else
                return FALSE;
        }
        return FALSE;
    }
The dialog procedure calls the WinHelp function with the HELP_QUIT option
just before calling the EndDialog function. This is required to ensure that
Help is shut down before the dialog box closes.


8.1.4 Windows for Pen Computing Compatibility

Microsoft Windows for Pen Computing includes tablet drivers for input from
a handwriting stylus device. An application can use the Windows 3.1
GetMessageExtraInfo function to distinguish between a mouse-generated event
(the return value is 0L) and a stylus generated mouse event (the return
value is non-zero).

Tablet drivers use the SI and DI registers to communicate extended event
information to Windows. For this reason, mouse drivers should set these
registers to zero before a function calls the Mouse_Event function in the
Windows 3.1 USER module. This will allow Windows and Pen-Computing based
applications to distinguish between mouse and tablet events.


8.1.5 Mouse Support for Non-Windows Applications

386 enhanced-mode Windows supports mouse input for non-Windows applications
running in a window. To provide this input, Windows works in conjunction
with an extended MS-DOS mouse driver. Windows sends information about the
Windows mouse to the MS-DOS driver and the driver provides this information
to the non-Windows application.

To support mouse input in a window, an MS-DOS mouse driver must:

o   Install an Interrupt 2Fh handler and watch for Mouse Device Call Out
    functions (Interrupt 2Fh Function 1607h)

o   Register a mouse-support callback function when Windows broadcasts the
    Mouse Device Call Out function

o   Respond appropriate to requests made by Windows through the
    mouse-support callback function


8.1.5.1 Registering the Mouse-Support Callback

An MS-DOS mouse driver must install an interrupt-handling routine for
Interrupt 2Fh when it is first loaded. The handler should watch for the
Mouse Device Call Out function (Interrupt 2Fh Function 1607h) that Windows
broadcasts when it starts up. When it detects the function, it should
respond with the address of its mouse-support callback function.

Windows sets the following registers and calls the Mouse Device Call Out
function as follows:

    mov ax, 1607h
    mov bx, 000Ch   ; virtual mouse device ID number
    mov cx, 0001h   ; mouse API extension number
    int 2Fh
The MS-DOS mouse driver must respond by setting the registers as follows:

    mov ax, seg Callback
    mov ds, ax
    mov si, offset Callback ; DS:SI contains address of mouse-support
                            ; callback
    mov ax, 0               ; zero indicates that support exists

8.1.5.2 Mouse-Support Callback Function

Windows calls the mouse-support callback function with requests and
information about the Windows mouse. The value in the AX registers
specifies what request Windows is passing to the callback function. The
following lists the requests.

AX      Action
---------------------------------------------------------------------------

0001h   Mouse move/button click

0002h   Disable mouse cursor drawing

0003h   Enable mouse cursor drawing

Before Windows calls, it disables interrupts and the trace flag. The
callback function must return by executing an iret instruction.


Mouse Movement and the Button

Whenever the mouse moves or a button is pressed, Windows calls the
mouse-support callback (in the proper virtual-machine context) with the
following parameters:

Register   Value
---------------------------------------------------------------------------

AX         0001h.

BX         x-coordinate in pixels of mouse.

CX         y-coordinate in pixels of mouse.

DX         Button state (see Interrupt 33h Function 0Ch).

SI         Mouse event flags (see Interrupt 33h Function 0Ch).

The driver should update its internal state appropriately and call any
user-installed mouse handler.


Disable Mouse Cursor Drawing

When a non-Windows application is going to run in a window, Windows
disables mouse cursor drawing to prevent two mouse cursors from being
drawn. The user's mouse Enable and Disable functions should behave
normally, but the mouse cursor should not be drawn by the MS-DOS driver.
The state variable that enables and disables mouse-cursor drawing should be
instanced so that each virtual-machine (VM) can have a different state.


Enable Mouse Cursor Drawing

This is the default state for a full-screen non-Windows application and
should be the initial state for the MS-DOS mouse driver. Windows makes this
request to re-enable the mouse cursor drawing when a non-Windows
application is switched from a window back to full screen.

NOTE Applications that draw their own cursors will still have two mouse
cursors in a window.

Applications which don't depend on the mouse driver will not have mouse
support in a window.


8.2 Function Reference

The following is an alphabetical listing of the mouse-driver functions.

CplApplet

    long CplApplet(hWnd, wCode, dw1, dw2)
    HWND hWnd;
    WORD wCode;
    DWORD dw1;
    DWORD dw2;

The CplApplet function carries out requests from Control Panel. Control
Panel calls this function when the user chooses an icon, such as the mouse
icon, to direct the corresponding driver to carry out some action.

A mouse driver that provides a custom mouse-setting dialog box must export
the CplApplet function.


Parameters

   hWnd
   Identifies the Control Panel window. The mouse driver uses the handle as
   the parent window handle for the settings dialog box.

   wCode
   Specifies the action to take. If the wCode parameter is 5, CplApplet
   displays the custom mouse-settings dialog box.

   dw1
   Reserved; do not use.

   dw2
   Reserved; do not use.


Return Value

The return value is TRUE if successful. Otherwise, it is FALSE.


Comments

The export ordinal for this function is 6.

If CplApplet returns FALSE, Control Panel displays its standard mouse
dialog box. If an error occurs, for example, the mouse driver cannot find
or load its dialog box, CplApplet displays an error message before
returning the FALSE value to Control Panel.



Disable

    VOID Disable(VOID);

The Disable function removes the existing interrupt procedure from the
mouse driver. After a call to this procedure, there will be no support for
interrupts from the mouse driver.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 3.


See Also

Enable



Enable

    VOID Enable(lpEventProc)
    LPFN lpEventProc;

The Enable function enables the mouse-interrupt procedure and specifies the
mouse-event callback function the procedure is to call when an interrupt
occurs.


Parameter

   lpEventProc
   Points to the callback function to call when a mouse interrupt occurs.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 2.


See Also

Disable



Inquire

    WORD Inquire(lpMouseInfo)
    LPMOUSEINFO lpMouseInfo;

The Inquire function returns information about the mouse hardware.


Parameter

   lpMouseInfo
   Points to a MOUSEINFO structure containing information about the mouse
   hardware that is present, the number of buttons on the mouse, and the
   rate at which the mouse can issue interrupts.

   The MOUSEINFO structure has the following form:

            typedef struct {
                char    msExist;
                char    msRelative;
                short   msNumButtons;
                short   msRate;
                short   msXThreshold;
                short   msYThreshold;
                short   msXRes;
                short   msYRes;
                short   msMouseCommPort;
            } MOUSEINFO;

Return Value

The return value is the number of bytes actually written into the MOUSEINFO
structure.


Comments

The export ordinal for this function is 1.

Before setting the msMouseCommPort member in the MOUSEINFO structure, the
mouse driver must check the Windows version number. For Windows version 3.1
or greater, the driver should set the member to specify the communication
port (if any) used by the mouse.


See Also

Enable



Mouse_Event

        mov     ax, [Status]        ; mouse motion and button status
        mov     bx, [deltaX]        ; change in x
        mov     cx, [deltaY]        ; change in y
        mov     dx, [ButtonCount]   ; number of buttons
        xor     di,di               ; DI must be zero
        xor     si,si               ; SI must be zero
        call    [Mouse_Event]       ; mouse-event function address
The Mouse_Event function records the mouse motion or button click. The
mouse-interrupt handler calls this function when it has a new mouse event
to report.


Parameters

   Status
   Specifies whether the user moved the mouse, pressed a mouse button, or
   released a mouse button. The bits in this parameter can be a combination
   of the following values.

        Value                 Meaning
        -------------------------------------------------------------------

        SF_MOVEMENT (0001h)   Movement occured.

        SF_B1_DOWN (0002h)    Button 1 (SW1) changed to down.

        SF_B1_UP (0004h)      Button 1 (SW1) changed to up.

        SF_B2_DOWN (0008h)    Button 2 (SW3) changed to down.

        SF_B2_UP (0010h)      Button 2 (SW3) changed to up.

        SF_ABSOLUTE (8000h)   The BX and CX registers contain normalized
                              absolute coordinates.

   The bits specifying the button status are set to indicate a change in
   status on an ongoing condition. For example, if button 1 is pressed and
   held down, SF_B1_DOWN is set only when button 1 is first pressed but not
   for subsequent motions. Similarly, SF_B1_UP is set only when the button
   is first released.

   deltaX
   Specifies the amount of motion along the x-axis. This parameter is
   either the number of mickeys moved (for relative devices), or the actual
   x-coordinate (for absolute devices).

   deltaY
   Specifies the amount of motion along the y-axis. This parameter is
   either the number of mickeys moved (for relative devices), or the actual
   y-coordinate (for absolute devices).

   ButtonCount
   Specifies the number of buttons.


Return Value

This function has no return value.


Comments

If there has been mouse motion (bit 0 of AX is set), the BX and CX
registers hold the integer values of motion since the last mouse interrupt
was generated for x and y, respectively.

If the SF_ABSOLUTE value is not specified in the Status parameter, the BX
and CX registers specify relative motions from the last reported position.
If this value is specified in Status, BX and CX contain normalized absolute
coordinates between 0 and 65535, which will be mapped by the event
procedure onto the display surface.

The DI and SI registers must be set to zero to ensure compatibility with
Microsoft Windows for Pen Computing.


See Also

Enable



MouseGetIntVect

    int MouseGetIntVect(VOID);

The MouseGetIntVect function returns the interrupt vector number used by
the mouse driver.


Parameters

This function has no parameters.


Return Value

The return value is the interrupt-vector number used by the mouse-interrupt
procedure. Otherwise, if no mouse is found, the function returns -1.


Comments

The export ordinal for this function is 4.


See Also

Inquire


8.3 Structure Reference

The following is an alphabetical listing of the mouse-driver structures.



MOUSEINFO

    typedef struct {
        char    msExist;
        char    msRelative;
        short   msNumButtons;
        short   msRate;
        short   msXThreshold;
        short   msYThreshold;
        short   msXRes;
        short   msYRes;
        short   msMouseCommPort;
    } MOUSEINFO;
The MOUSEINFO structure specifies information about the mouse, such as the
type of coordinates and the number of buttons.


Members

   msExist
   Specifies whether a mouse device exists. It is nonzero if the
   device-initialization code was able to find and initialize a mouse
   device.

   msRelative
   Specifies whether the mouse coordinates are absolute or relative. This
   member is zero if the mouse returns absolute coordinates.

   msNumButtons
   Identifies how many buttons are on the installed mouse. For the IBM PC
   with a Microsoft Mouse, this field is set to 2.

   msRate
   Specifies the maximum number of hardware interrupts per second that the
   mouse can generate. For the IBM PC with the bus version of the Microsoft
   Mouse, this field is 34.

   msXThreshold
   Reserved; do not use.

   msYThreshold
   Reserved; do not use.

   msXRes
   Reserved; do not use.

   msYRes
   Reserved; do not use.

   msMouseCommPort
   Specifies the communication port used by the mouse. It can be one of the
   following values.

        Value   Meaning
        -------------------------------------------------------------------

        0       No port used.

        1       Communications port 1 (COM1).

        2       Communications port 2 (COM2).

        3       Communications port 3 (COM3).

        4       Communications port 4 (COM4).


Comments

If a mouse driver sets the msMouseCommPort member, Windows reserves the
specified communications port exclusively for use by the mouse.


See Also

Inquire

Chapter 9  Miscellaneous Drivers

Microsoft Windows uses device drivers and dynamic-link libraries (DLL) to
support a variety of features, such as audio adapters and language-specific
sorting. Many such drivers incorporate the Microsoft Windows installable
driver interface, which allows Windows and Windows applications to install
and use a driver by using a generic set of functions.


9.1 About the Audio Drivers

An audio driver is a dynamic-link library that provides a set of functions
Windows applications can use to generate sounds through an audio device.

For more information about audio drivers, see the Microsoft Windows
Installation and Update Guide.


9.2 About the Language Libraries

A language library is a dynamic-link library that provides a set of
functions that Windows applications can use to sort characters in foreign
languages. Microsoft provides a default set of language libraries that
cover a wide range of languages.


9.3 About the Installable-Driver Interface

An installable driver is a dynamic-link library that exports a DriverProc
function and processes messages, such as DRV_OPEN and DRV_CONFIG, which are
sent to the function. Although the standard Windows device drivers, such as
the display, keyboard, mouse, and printer drivers, do not use this
interface, it is recommended that the interface be used in all other device
drivers. One advantage of using the installable driver interface is that a
driver can be installed using the Drivers icon in Control Panel. This
eliminates the need to develop a custom-installation program for each
driver.

For more information about the installable driver interface, see the
Microsoft Windows Programmer's Reference in the Microsoft Windows Software
Development Kit (SDK).

Chapter 10  Graphics Function Directory

The Microsoft Windows graphics functions generate device-specific output
for displays and printers. Every graphics driver consists of a set of
graphics functions that translate device-independent requests from the
graphics-device interface (GDI) into the commands and data of a given
device. Although the exact number and type of graphics functions in a
driver depends on the device technology and capabilities, most graphics
drivers export all the functions described in this chapter.

This chapter provides an alphabetical listing of the syntax, purpose,
parameters, and return values of the graphics functions that are common to
both display and printer drivers. For information about using these
functions in graphics drivers, see Chapter 2, Display Drivers, and Chapter
4, Printer Drivers.

BitBlt

    BOOL BitBlt(lpDestDev, wDestX, wDestY, lpSrcDev, wSrcX,
                wSrcY, wXext, wYext, Rop3, lpPBrush,
                lpDrawMode);
    LPPDEVICE lpDestDev;
    WORD wDestX;
    WORD wDestY;
    LPPDEVICE lpSrcDev;
    WORD wSrcX;
    WORD wSrcY;
    WORD wXext;
    WORD wYext;
    long Rop3;
    LPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;

The BitBlt function transfers bits from a rectangle to a source device to a
rectangle having the same dimensions to a destination device. The transfer
is controlled by a ternary raster operation value that specifies how
corresponding bits from the source, destination, and pattern in a brush are
combined to form the final bits in the destination.

A graphics driver must export the BitBlt function if the RC_BITBLT value is
set in the dpRaster member of the driver's GDIINFO structure.


Parameters

   lpDestDev
   Points to PDEVICE or PBITMAP structure specifying the destination device
   or bitmap.

   wDestX
   Specifies the x-coordinate (in device units) of the origin of the
   rectangle on the destination device to receive the transferred bits.

   wDestY
   Specifies the y-coordinate (in device units) of the origin of the
   rectangle on the destination device to receive the transferred bits.

   lpSrcDev
   Points to PDEVICE or PBITMAP structure specifying the source device or
   bitmap.

   wSrcX
   Specifies the x-coordinate (in device units) of the origin of the
   rectangle on the source device containing the bits to transfer.

   wSrcY
   Specifies the y-coordinate (in device units) of the origin of the
   rectangle on the source device containing the bits to transfer.

   wXext
   Specifies the width (in device units) of the rectangles on both the
   source and destination devices.

   wYext
   Specifies the height (in device units) of the rectangle on both the
   source and destination devices.

   Rop3
   Specifies a ternary raster-operation value. This value determines how
   BitBlt combines corresponding pixels from the source, destination, and
   brush to produce the final pixels in the destination rectangle. The Rop3
   parameter can be any one of 256 ternary raster-operation values; the
   following lists the most common values.

Value                      Meaning
---------------------------------------------------------------------------

SRCCOPY (0x00CC0020)       Copies source bits to the destination rectangle:
                           Destination = Source.

SRCPAINT (0x00EE0086)      Combines the source and destination bits using
                           the bitwise OR operator: Destination = Source |
                           Destination.

SRCAND (0x008800C6)        Combines the source and destination bits using
                           the bitwise AND operator: Destination = Source &
                           Destination.

SRCINVERT (0x00660046)     Combines the source and destination bits using
                           the bitwise exclusive OR operator: Destination =
                           Source ^ Destination.

SRCERASE (0x00440328)      Combines the source and inverse of destination
                           bits using the bitwise AND operator: Destination
                           = Source & (~ Destination).

NOTSRCCOPY (0x00330008)    Copies the inverse of the destination bits to
                           the destination rectangle: Destination = ~
                           Destination.

NOTSRCERASE (0x001100A6)   Combines the inverse of the source and
                           destination bits using the bitwise AND operator:
                           Destination = (~ Source) & (~ Destination).

MERGECOPY (0x00C000CA)     Combines the source and brush bits using the
                           bitwise AND operator: Destination = Source &
                           Pattern.

MERGEPAINT (0x00BB0226)    Combines the destination and inverse of the
                           source bits using the bitwise OR operator:
                           Destination = (~ Source) | Destination.

PATCOPY (0x00F00021)       Copies the brush bits to the destination
                           rectangle: Destination = Pattern.

PATPAINT (0x00FB0A09)      Combines the destination, pattern, and the
                           inverse of source bits using the bitwise OR
                           operator: Destination = (~ Source) | Pattern |
                           Destination.

PATINVERT (0x005A0049)     Combines the pattern and destination bits using
                           using the bitwise exclusive OR operator:
                           Destination = Pattern ^ Destination.

DSTINVERT (0x00550009)     Copies the inverse of the destination bits:
                           Destination = ~ Destination.

BLACKNESS (0x00000042)     Set all destination bits to black.

WHITENESS (0x00FF0062)     Set all bits to white.

   For more information about ternary-raster operations and a complete list
   of values, see Appendix A, Binary and Ternary Raster-Operation Codes.

   lpPBrush
   Points to a PBRUSH structure specifying a physical brush. BitBlt uses
   this brush only if the Rop3 parameter specifies a ternary-raster
   operation that requires the brush to be combined with source or
   destination or both.

   lpDrawMode
   Points to a DRAWMODE structure specifying the color information BitBlt
   needs to determine patterned brush colors and to carry color conversions
   and transparent copy operations. The structure has the following form:

    typedef struct tagDRAWMODE {
      short    Rop2;       /*binary-raster operations*/
      short    bkMode;     /*background mode*/
      PCOLOR   bkColor;    /*physical background color*/
      PCOLOR   TextColor;  /*physical text (foreground) color*/
      short    TBreakExtra;/*number of extra pixels to add to line*/
      short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
      short    BreakErr;   /*running error term*/
      short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
      short    BreakCount; /*number of breaks in the line*/
      short    CharExtra;  /*extra pixels for each character*/
      COLORREF LbkColor;   /*logical background color*/
      COLORREF LTextColor; /*logical text (foreground) color*/
    } DRAWMODE;

Return Value

This return value is TRUE if it is successful. Otherwise, it is FALSE.


Comments

The export ordinal for this function is 1.

The lpDestDev and lpSrcDev parameters can specify the same device, and
transferring bits from one part of a device to another is a valid
operation. If the source and destination rectangle overlap, BitBlt must
carefully transfer bits so that the transfer does not inadvertently
overwrite source bits before they have been transferred to the destination.

The Rop3 parameter specifies whether bits from the source, destination, and
brush are used in the transfer. If the ternary raster operation specified
by Rop3 does not include the source, BitBlt ignores the source bits. If the
operation does not include the destination, BitBlt replaces the original
destination bits without using them to form the final bits.

If Rop3 does not include the brush, BitBlt ignores the brush. If Rop3 does
include the brush, BitBlt must determine whether the brush is solid or
patterned (that is, has an associated bitmap). If the brush has a bitmap,
BitBlt must combine the corresponding bits of the bitmap with the source
and destination bits (as specified by the raster operation) to form the
final destination bits.

If the source and bitmap associated with the brush do not have the same
color format as the destination, BitBlt must convert the source and brush
bitmap to the destination's color format before transferring bits. BitBlt
uses the text (foreground) and background colors specified by the
lpDrawMode parameter to convert colors.

To convert a monochrome bitmap to a color bitmap, BitBlt converts white
bits (1) to the background color and converts black bits (0) to the text
(foreground) color.

To convert a color bitmap to a monochrome bitmap, BitBlt converts all
pixels that match the background color to white (1), and converts all other
pixels to black (0).

In some device drivers, BitBlt must check the bkMode member of the DRAWMODE
structure pointed to by the lpDrawMode parameter as well as the Rop3
parameter to determine how to carry out the transfer. If the bkMode member
specifies the background mode TRANSPARENT1, BitBlt must not transfer source
and brush bits that have the same color as the destination's background
color (as specified by the bkColor member of the DRAWMODE structure pointed
to by lpDrawMode). In other words, the corresponding destination bits must
be left unchanged. Other background modes do not affect the transfer. Only
device drivers that have set the C1_TRANSPARENT value in the dpCaps1 member
of the GDIINFO structure are required to check the background mode.


See Also

StretchBlt



BitmapBits

    BOOL BitmapBits(lpDevice, fFlags, dwCount, lpBits)
    LPPDEVICE lpDevice;
    DWORD fFlags;
    DWORD dwCount;
    LPSTR lpBits;

The BitmapBits function sets, retrieves, or copies bitmap data. A graphics
driver must export a BitmapBits function if the RC_DEVBITS bit is set in
the dpRaster member of the device driver's GDIINFO structure.


Parameters

   lpDevice
   Points to a PDEVICE or PBITMAP structure specifying a device or memory
   bitmap.

   fFlags
   Specifies whether to set, retrieve, or copy bitmap data. This parameter
   can be one of the following values.

Value          Meaning
---------------------------------------------------------------------------

DBB_SET (1)    Sets bitmap bits by copying data from the buffer pointed to
               by the lpBits parameter to the specified device.

DBB_GET (2)    Retrieves bitmap bits by copying data from the specified
               device to the buffer pointed to by lpBits.

DBB_COPY (4)   Copies bitmap bits from the bitmap pointed to by lpBits to
               the specified device.

   dwCount
   Specifies the number of bits to copy.

   lpBits
   Points to a buffer or a bitmap, depending on the value of the fFlags
   parameter. If fFlags is DBB_SET or DBB_GET, this parameter points to a
   buffer that contains or receives the bits for the specified bitmap. If
   fFlags is DBB_COPY, this parameter points to a device bitmap.


Return Value

The return value is the number of bits actually copied.


Comments

The export ordinal for this function is 30.


See Also

SelectBitmap



ColorInfo

    COLORREF ColorInfo(lpDestDev, dwColorin, lpPColor)
    LPPDEVICE lpDestDev;
    DWORD dwColorin;
    LPPCOLOR lpPColor;

The ColorInfo function converts a logical color (an RGB value) to a
physical color ( a physical color value) or converts a physical to a
logical color, depending on the value of the lpPColor parameter.

Every graphics device driver must export a ColorInfo function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   dwColorin
   Specifies either a logical or physical color, depending on the value of
   lpPColor parameter.

   lpPColor
   Points to a PCOLOR structure or is NULL. If lpPColor points to a PCOLOR
   structure, the function assumes that dwColorin specifies a logical color
   (an RGB value) and copies the physical color value that most closely
   matches the logical color to this structure. If lpPColor is NULL, the
   function assumes that dwColorin specifies a physical color and returns
   the logical color that matches the physical color.


Return Value

The return value is the logical color (RGB value) that most closely matches
the physical color either specified by dwColorin, or copied to the PCOLOR
structure pointed to by lpPColor.


Comments

The export ordinal for this function is 2.

When converting a logical color, ColorInfo chooses the best possible
physical color to match the logical color and return the RGB color value
that corresponds to this physical color.

GDI uses the physical colors returned by ColorInfo to set text colors,
background colors, and pixel colors using the Pixel function.

If dwColorin is a logical color, it may specify either an RGB value or a
color index. If dwColorin specifies a color index (high-order byte is
0xFF), ColorInfo should return the index without carrying out a conversion.
If dwColorin is a physical color, ColorInfo should return an RGB value only
for static colors and return color indexes for all other colors. If GDI
receives a color index from ColorInfo, it uses other functions to determine
the corresponding logical color.


See Also

Pixel



Control

    WORD Control(lpDestDev, wFunction, lpInData, lpOutData)
    LPPDEVICE lpDestDev;
    WORD wFunction;
    LPSTR lpInData;
    LPSTR lpOutData;

The Control function carries out the device-specific extension specified by
the wFunction parameter. GDI calls Control when an application calls the
Escape function (GDI.38). For this reason, the device-specific extensions
are also called escapes.

Every graphics driver must export a Control function.


Parameters

   lpDestDev
   Points to a PDEVICE structure specifying the destination device.

   wFunction
   Specifies the escape to carry out. Although the number of wFunction
   values and the meaning of each value depends on the driver, GDI reserves
   a number of values to specify predefined escapes. For more information
   about predefined escapes, see Chapter 11, Graphics-Driver Escapes.

   lpInData
   Points to escape-specific input data.

   lpOutData
   Points to escape-specific output data.


Return Value

The return value depends on the escape function specified by the wFunction
parameter. In general, positive values indicate success, negative values
indicate an error, and zero can indicate either an unimplemented escape or
a general error condition.


Comments

The export ordinal for this function is 3.

The Control function should always return zero for escapes that are
unimplemented or unrecognized. The function should return the number of
bytes copied if it copies data to a buffer pointed to by the lpOutData
parameter, or if the lpOutData parameter is NULL, it should return the size
in bytes of the buffer it requires to copy data.

GDI modifies some escapes before calling the Control function.



CreateDIBitmap

    WORD CreateDIBitmap(void)

The CreateDIBitmap function creates a device-independent bitmap.

A graphics-device driver must export the CreateDIBitmap function if the
RC_DI_BITMAP value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

This function has no parameters.


Return Value

The return value is always zero.


Comments

The export ordinal for this function is 20.

Since GDI does not currently use CreateDIBitmap, implement the function as
a stub function that carries out no action and always returns zero. GDI
does not currently call the CreateDIBitmap function.



DeviceBitmap

    WORD DeviceBitmap(lpDestDev, wCommand, lpBitmap, lpBits)
    LPPDEVICE lpDestDev;
    WORD wCommand;
    LPBITMAP lpBitmap;
    LPSTR lpBits;

Every graphics driver must export a DeviceBitmap function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wCommand
   Specifies a command number determining the action to take.

   lpBitmap
   Points to a PBITMAP structure containing a description of the device
   bitmap.

   lpBits
   Points to a buffer containing the bits for the device bitmap.


Return Value

The return value is zero.


Comments

The export ordinal for this function is 16.

Since GDI does not currently use DeviceBitmap, implement the function as a
stub function that carries out no action and always returns zero. The
DeviceBitmap function carries out a specified action on a device bitmap.
GDI does not currently call the DeviceBitmap function.



DeviceBitmapBits

    void DeviceBitmapBits(lpBitmap, fGet, iStart, cScans,
                          lpDIBits, lpBitmapInfo, lpDrawMode,
                          lpTranslate)
    LPPDEVICE lpBitmap;                 /* points to device-specific bitmap */
    WORD fGet;                          /* 0 to set bits, 1 to get bits     */
    WORD iStart;                        /* starting scan line               */
    WORD cScans;                        /* number of scan lines to copy     */
    LPSTR lpDIBits;                     /* points to the bitmap bits        */
    LPBITMAPINFO lpBitmapInfo;          /* points to bitmap information     */
    LPDRAWMODE lpDrawMode;            /* points to drawing-mode information */
    LPINT lpTranslate;                /* points to color-translation table  */

The DeviceBitmapBits function either copies device-independent bitmap to a
device-specific bitmap or copies a device-specific bitmap to a
device-independent bitmap. The fGet parameter specifies which operation to
carry out.

A graphics driver must export a DeviceBitmapBits function if the
RC_DI_BITMAP value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

   lpBitmap
   Points to a PBITMAP structure specifying a device-specific memory
   bitmap.

   fGet
   Specifies whether the function sets or retrieves bitmap bits. If this
   parameter is zero, the function sets the bits; if the parameter is 1,
   the function retrieves the bits.

   iStart
   Specifies the starting scan number.

   cScans
   Specifies the number of scans to set or retrieve.

   lpDIBits
   Points to a buffer that contains or receives the bitmaps bits. If the
   fGet parameter is zero, the function copies data from the buffer into
   the bitmap; if fGet is 1, the function copies the bits to the buffer
   from the bitmap. If the lpDIBits parameter is NULL, the function fills
   the biSizeImage member in the BITMAPINFO structure pointed to by the
   lpBitmapInfo parameter, but does not copy bitmap bits.

   lpBitmapInfo
   Points to a BITMAPINFO structure specifying the dimensions and format of
   the device-independent bitmap. The structure has the following form:

    typedef struct tagBITMAPINFO {
        BITMAPINFOHEADER    bmiHeader;
        RGBQUAD             bmiColors[1];
    } BITMAPINFO;
   The function must check the biPlanes and and biBitCount members. If
   biPlanes is not 1 or biBitCount is not 1, 4, 8, or 24, the function
   returns an error.

   The function compares the widths of the device-specific bitmap and the
   device-independent bitmap. If the widths are not equal, the function
   clips to the smaller of the two bitmaps.

   If the RLE_FORMAT_4 or RLE_FORMAT_8 values are set in the biCompression
   member of the BITMAPINFO structure, the device-independent bitmap is in
   run-length-encoded (RLE) format. In this case, the function must encode
   each scan line as it copies the scan line data to the buffer pointed to
   by lpDIBits or the function must decode the data as it retrieves it from
   the buffer.

   lpDrawMode
   Points to a DRAWMODE structure specifying the text (foreground) and
   background colors to use if color conversion is required. The structure
   has the following form:

    typedef struct tagDRAWMODE {
      short    Rop2;       /*binary-raster operations*/
      short    bkMode;     /*background mode*/
      PCOLOR   bkColor;    /*physical background color*/
      PCOLOR   TextColor;  /*physical text (foreground) color*/
      short    TBreakExtra;/*number of extra pixels to add to line*/
      short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
      short    BreakErr;   /*running error term*/
      short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
      short    BreakCount; /*number of breaks in the line*/
      short    CharExtra;  /*extra pixels for each character*/
      COLORREF LbkColor;   /*logical background color*/
      COLORREF LTextColor; /*logical text (foreground) color*/
    } DRAWMODE;
   lpTranslate
   Points to an array of color translation values for converting palette
   colors to actual device colors. This parameter is ignored by devices
   that do not use color palettes.


Return Value

The return value is the number of scan lines set or retrieved if the
function is successful. Otherwise, it is zero if there is an error or -1 if
the bits cannot be set or retrieved.


Comments

The export ordinal for this function is 19.

Depending on the operation specified by the fGet parameter,
DeviceBitmapBits either converts the bits pointed to by lpDIBits to the
format required by the bitmap specified by the lpBitmap parameter or
converts the bits pointed to by lpDIBits to the format required by
lpBitmap. To convert the bits, the function needs to compute the width and
height of the bitmap to copy, needs to determine if color conversion is
necessary, and needs to prepare for scan lines that cross the 64K
boundaries.

DeviceBitmapBits checks the color formats of the bitmap specified by
lpBitmap and the device-independent bitmap specified by lpBitmapInfo. If
the color formats are not the same, the function must convert the bitmap
pixels to the same format as the destination. For example, if the function
copies a device-independent bitmap to a monochrome bitmap, the function
must convert color pixels to monochrome. In this case, DeviceBitmapBits
converts all pixels that match the background color (as specified by the
lpDrawMode parameter) to white (1), and converts all other pixels to black
(0).

To prepare for color conversion when fGet is zero, the function maps
color-table information (if any) provided in the BITMAPINFO structure to
the device-specific colors. If the biClrUsed member is zero, the function
must use a default color table. The size of the default table depends on
the number of bits per pixel (that is, 16 colors for 4 bits-per-pixel, 256
colors for 8 bits-per-pixel, and so on). However, if biClrUsed is nonzero,
the member specifies the size of the table; this size cannot be more than
the default size. Since the default color table for a bitmap having 24 bits
per pixel is exceptionally large, the function carries out the color
mapping as it converts the bits rather than generating a table.

To prepare for color conversion when fGet is 1, the function creates the
logical-color table and copies it to the BITMAPINFO structure. If the
device driver does not support a color palette, the function fills the
logical-color table with whatever color it supports and use the
corresponding indexes in the bitmap. It must also set the number of colors
it is using in the biClrUsed member of the BITMAPINFO structure. For
example, if the display device is a 4-plane device (16 colors) but the
request is for a device-independent bitmap that has 8 bits-per-pixel (256
colors), the function can specify just 16 colors and set the biClrUsed
member to 16, or it can set remaining colors (entries 16 through 255) to
zero and set the biClrUsed member to zero.


See Also

SetDIBitsToDevice, StretchDIBits



DeviceMode

    void DeviceMode(hWnd, hInstance, lpDestDevType,
                      lpOutputfile)
    HWND hWnd;
    HANDLE hInstance;
    LPSZ lpDestDevType;
    LPSZ lpOutputfile;

The DeviceMode function sets the current settings (such as paper bin, paper
size, scaling, and orientation) for the device driver by prompting for
those modes with a dialog box. Control Panel calls the DeviceMode function
when the user requests the setting up the printer as part of printer
installation.

All printer drivers must export the DeviceMode function. Display drivers
that permit the user to change operating modes must export the DeviceMode
function.


Parameters

   hWnd
   Identifies the parent window to use for the dialog box.

   hInstance
   Identifies the module instance of the device driver.

   lpDestDevType
   Points to a null-terminated string containing the device name. The
   application passes the same device-type name as specified in the
   CreateDC function.

   lpOutputfile
   Points to a null-terminated string containing the name of an MS-DOS file
   or device port. The application passes the same device type name as
   given in the CreateDC function.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 13.

The DeviceMode function creates an application-modal dialog box using the
DialogBox function (USER.240). The dialog box must provide options for the
user to set the various settings of the device. DeviceMode does the
following:

1.  Initializes the dialog box settings by retrieving the current
    environment using the GetEnvironment function (GDI.133), or by reading
    the environment from the corresponding device-specific section in the
    WIN.INI file.

2.  Calls the DialogBox function to display the dialog box, then waits for
    the user to complete their changes. When the value returns from
    DialogBox, check the return value. Make subsequent updates only if the
    return value is IDOK.

3.  Updates the current device environment by using the SetEnvironment
    function (GDI.132). Also, the function updates the corresponding
    device-specific section in the WIN.INI file.

4.  Sends a WM_DEVMODE message to all applications informing them of a
    change to the device's operating modes.

The dialog box must provide at least a title bar and OK and Cancel buttons,
in addition to controls for the various operating modes. The title bar
should contain the name of the current printer model (if the driver
supports several models), but no other printer model information should be
presented in the dialog box. (The DeviceMode dialog box must not permit the
user to change printer models.)

If a device has too many options to fit in a single dialog box, DeviceMode
can provide nested dialog boxes, using buttons in the first dialog box to
access the others. In all cases, a dialog function for a DeviceMode dialog
box closes the dialog box if it receives a WM_COMMAND message with the
wParam parameter set to IDCANCEL. This message occurs when the user presses
the ESC key, or chooses the Cancel button in the dialog box, or when
Windows Help needs to close the dialog box in order to respond to a request
for help from another application.

Although Control Panel requires DeviceMode, most applications call the
ExtDeviceMode or AdvancedSetUpDialog function when the user makes a request
to set up the device. (Applications either directly or indirectly call
through the standard Printer Setup dialog box.) In drivers that provide
ExtDeviceMode, the DeviceMode typically calls ExtDeviceMode to set up the
device.


See Also

AdvancedSetUpDialog, ExtDeviceMode



Disable

    void Disable(lpDestDev)
    LPPDEVICE lpDestDev;

The Disable function disables the specified device. GDI calls this function
when it deletes a device or information context for an application, or when
it saves the context in preparation for Windows switching to a full-screen
application.

Every graphics driver must export a Disable function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 4.


See Also

Enable



Enable

    WORD Enable(lpDevInfo, wStyle, lpDestDevType,
                  lpOutputFile, lpData)
    LPVOID lpDevInfo;
    WORD wStyle;
    LPSTR lpDestDevType;
    LPSTR lpOutputFile;
    LPVOID lpData;

The Enable function returns information about the driver or initializes the
driver. GDI calls this function when it creates a device or information
context for an application, or when it restores the context after Windows
returns from a full-screen application.

Every graphics driver must export an Enable function.


Parameters

   lpDevInfo
   Points to a PDEVICE or GDIINFO structure depending on the value of the
   wStyle parameter.

   wStyle
   Specifies whether to return information or initialize the driver and
   device. This parameter can be one of the following values.

    Value    Meaning
    -----------------------------------------------------------------------

    0x0000   Initializes the driver and associated hardware, then copies
             device-specific information needed by the driver to the
             PDEVICE structure pointed to by the lpDevInfo parameter.

    0x0001   Copies the device driver information to the GDIINFO structure
             pointed to by lpDevInfo.

    0x8000   Initializes the PDEVICE structure pointed to by the lpDevInfo
             parameter, but does not initialize the driver and peripheral
             hardware.

    0x8001   Means the same as the 0x0001 value.

   GDI sets the high bit of wStyle if an application has requested an
   information context only.

   lpDestDevType
   Points to a null-terminated ASCII string specifying the device name.
   This string only applies to device drivers that support more than one
   model of the same device. The parameter can be NULL if only one model is
   supported.

   lpOutputFile
   Points to a null-terminated ASCII string specifying the name of the
   output port or file to receive output from the driver. The string must
   be a valid MS-DOS filename.

   For a display driver, if the lpOutputFile parameter is NULL, the output
   device is the system display.

   lpData
   Points a DEVMODE structure containing information Enable uses to
   initialize the device. It can be NULL if no such information is needed.


Return Value

The return value is zero if the function is unsuccessful (that is, the
hardware is not initialized). Otherwise, the function returns a nonzero
value.


Comments

The export ordinal for this function is 5.

For most devices, GDI calls Enable twice: first to retrieve the driver's
GDIINFO structure, and then to initialize the device and PDEVICE structure.
For a display driver, GDI typically calls the function each time the user
switches between Windows and a non-Windows application. When called for the
first time, however, Enable saves the current hardware context in static
storage (for example, in the PDEVICE structure) so that the driver can
restore that context when Windows terminates.

In some cases, GDI may request a raster device to write on a memory bitmap
without enabling the device first. This occurs only with raster devices
that can write to memory bitmaps.


See Also

Disable



EnumDFonts

    WORD EnumDFonts(lpDestDev, lpFaceName, lpCallbackFunc,
                      lpClientData)
    LPPDEVICE lpDestDev;    /* points to physical device or bitmap */
    LPSZ lpFaceName;        /* points to name of font face */
    FARPROC lpCallbackFunc; /* points to user-supplied callback function */
    LPVOID lpClientData;    /* points to user-supplied data */

The EnumDFonts function returns information about device fonts by passing
the information to the specified callback function. GDI calls this function
when processing the EnumFonts function (GDI.70) to determine what device
fonts are available.

Every graphics driver must export an EnumDFonts function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure.

   lpFaceName
   Points to the null-terminated string specifying the name of a font. If
   lpFaceName points to a name, EnumDFonts calls the callback function with
   information for the fonts having the same font name. If there are no
   fonts of that name, the function returns 1.

   If lpFaceName is NULL, EnumDFonts randomly selects one font of each name
   and calls the callback function with information for these fonts. If
   there are no fonts, the function returns 1.

   lpCallbackFunc
   Points to a user-supplied callback function. For more information about
   the callback function, see the following Comments section.

   lpClientData
   Points to a buffer containing user-supplied data. EnumDFonts does not
   use this data; instead it passes the data back to application through
   the callback function.


Return Value

The return value is the last value returned by the callback function. The
function returns 1 if there are no fonts having the specified font name.


Comments

The export ordinal for this function is 6.

EnumDFonts calls the callback function once for each font. It continues to
call the callback function until there are no more fonts, or the callback
function returns zero.

The callback function has the following form:

    WORD CallbackFunction(lpLogFont, lpTextMetrics,
                              wFontType, lpClientData)
    LPLFONT lpLogFont;
    LPTEXTMETRICS lpTextMetrics;
    WORD wFontType;
    LPVOID lpClientData;
Parameter       Description
---------------------------------------------------------------------------

lpLogFont       Points to a LFONT structure defining the logical attributes
                of a font. All sizes are in device units.

lpTextMetrics   Points to a TEXTMETRIC structure containing the same values
                that would be returned by the GetTextMetrics (GDI.93)
                function. All sizes are in device units.

wFontType       Specifies the type of the font. It can be one of the
                following values.

             Value                 Meaning
             --------------------------------------------------------------

             RASTER_FONTTYPE (1)   Font consists of raster bitmaps rather
                                   than vector strokes.

             DEVICE_FONTTYPE (2)   Font is provided by the device rather
                                   than GDI.

             ENGINE_FONTTYPE (4)   Font is provided by TrueType rather than
                                   GDI or device.

                Bit 3 in the wFontType parameter is reserved; must be zero.

lpClientData    Points to the user-supplied data passed to EnumDFonts.

The callback function must return a nonzero value to continue to receive
information about the fonts. If the callback function returns zero,
EnumDFonts stops enumerating the fonts and returns to GDI.

If the device can generated scaled, bold, or italicized fonts, EnumDFonts
should pass only the information about the base font to the callback
function. EnumDFonts should then leave it to the application to inquire
about the device's text transformation abilities.



EnumObj

    WORD EnumObj(lpDestDev, wStyle, lpCallbackFunc,
                   lpClientData)
    LPPDEVICE lpDestDev;
    WORD wStyle;
    FARPROC lpCallbackFunc;
    LPVOID lpClientData;

The EnumObj function enumerates the pens and brushes available on the
device. GDI calls EnumObj when an application calls the EnumObjects
function (GDI.71). For each object having the given style, EnumObj calls
the callback function with the logical information for that object. EnumObj
continues to call the callback function until there are no more objects or
the callback function returns zero.

Every graphics driver must export an EnumObj function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wStyle
   Specifies whether to enumerate pens or brushes. This parameter can be
   one of the following values.

             Value   Meaning
             --------------------------------------------------------------

             1       Enumerates pens

             2       Enumerates brushes

   EnumObj enumerates all objects of the given type. If there are no
   objects of the given type, the function must return 1.

   lpCallbackFunc
   Points to the user-supplied callback function.

   lpClientData
   Points to the user-supplied data.


Return Value

The return value is the last value returned by the callback function.
Otherwise, it is 1 if there are no objects of the given type.


Comments

The export ordinal for this function is 7.

The callback function has the following form:

    WORD CallbackFunction(lpLogObj, lpClientData)
    LPVOID lpLogObj;
    LPSTR lpClientData;
Parameter      Description
---------------------------------------------------------------------------

lpLogObj       Points to a LPEN or LBRUSH structure, depending on the
               wStyle parameter.

lpClientData   Points to the user-supplied data passed to EnumObj.

Before calling the callback function, EnumObj must fill the LPEN or LBRUSH
structure with the logical colors and other values that correspond to a
given physical pen or brush.

To support some older applications (such as Microsoft Excel for versions
earlier than 2.1), EnumObj specifies the 8 default EGA colors in the first
8 objects it enumerates.

EGA color   RGB value
---------------------------------------------------------------------------

Black       0,0,0

White       0xFF,0xFF,0xFF

Red         0xFF,0,0

Green       0,0xFF,0

Blue        0,0,0xFF

Yellow      0xFF,0xFF,0

Magenta     0xFF,0,0xFF

Cyan        0,0xFF,0xFF

If the driver supports additional colors, EnumObj can specify those colors
in any order. Since some applications end the enumeration after the first
16 colors, the second 8 colors to enumerated should be the most desirable
colors of the device.

EnumObj should enumerate solid pens before styled lines. Enumerating styled
pens is optional. The function should enumerate:

o   Solid pens

o   Styled pens (optional)

o   Solid brushes (no dithered colors)

o   Hatched brushes

EnumObj does not need to specify the background colors for hatched brushes.


See Also

EnumDFonts



ExtDeviceMode

    int ExtDeviceMode(hWnd, hDriver, lpDevModeOutput,
        lpDeviceName, lpPort, lpDevModeInput, lpProfile,
        wMode)
    HWND hWnd;
    HANDLE hDriver;
    LPDEVMODE lpDevModeOutput;
    LPSTR lpDeviceName;
    LPSTR lpPort;
    LPDEVMODE lpDevModeInput;
    LPSTR lpProfile;
    WORD wMode;

The ExtDeviceMode function retrieves or modifies device-initialization
information for a given graphics driver, or displays a driver-supplied
dialog box for configuring the graphics driver. Applications call the
ExtDeviceMode function when the user requests setting up the printer as
part of preparing for a print job.

All printer drivers must export the ExtDeviceMode function. Display drivers
that permit the user to change operating modes must export the
ExtDeviceMode function.


Parameters

   hWnd
   Identifies the parent window for the dialog box.

   hDriver
   Identifies the module instance of the device driver.

   lpDevModeOutput
   Points to a DEVMODE structure. The driver writes the initialization
   information supplied in the lpDevModeInput parameter to this structure.
   The structure has the following form:

        typedef struct _devicemode {    /* dm */
            char  dmDeviceName[CCHDEVICENAME];
            WORD  dmSpecVersion;
            WORD  dmDriverVersion;
            WORD  dmSize;
            WORD  dmDriverExtra;
            DWORD dmFields;
            short dmOrientation;
            short dmPaperSize;
            short dmPaperLength;
            short dmPaperWidth;
            short dmScale;
            short dmCopies;
            short dmDefaultSource;
            short dmPrintQuality;
            short dmColor;
            short dmDuplex;
            short dmYResolution;
            short dmTTOption;
        } DEVMODE;
   lpDeviceName
   Points to a null-terminated string that contains the name of the device,
   such as PCL/HP LaserJet.

   lpPort
   Points to a null-terminated string that contains the name of the port to
   which the device is connected, such as LPT1.

   lpDevModeInput
   Points to a DEVMODE structure containing initialization information set
   by the application.

   lpProfile
   Points to a null-terminated string that contains the name of the
   initialization file in which initialization information is recorded and
   read from. If this parameter is NULL, the [Model Name, Port] section of
   the WIN.INI file is the default.

   wMode
   Specifies which operations the function will perform. If the wMode
   parameter is zero, ExtDeviceMode returns the number of bytes required by
   the device driver's DEVMODE structure. Otherwise, wMode can be a
   combination of the following values.

    Value           Meaning
    -----------------------------------------------------------------------

    DM_UPDATE (1)   Writes the driver's current settings to the environment
                    and the WIN.INI initialization file.

    DM_COPY (2)     Writes the driver's current settings to the DEVMODE
                    structure identified by the lpDevModeOutput parameter.
                    The calling application must allocate a buffer
                    sufficiently large to contain the information. If this
                    bit is clear, lpDevModeOutput can be NULL.

    DM_PROMPT (4)   Presents the driver's dialog box and then changes the
                    current settings according to user specifications.

    DM_MODIFY (8)   Changes the printer driver's current settings to match
                    the partial initialization data in the DEVMODE
                    structure identified by lpDevModeInput before
                    prompting, copying, or updating the printer driver's
                    setting.


Return Value

If the wMode parameter is zero, the return value is the size of the DEVMODE
structure required to contain the printer-driver initialization data. If
the function displays the initialization-dialog box, the return value is
either IDOK or IDCANCEL, depending on which button the user chose. If the
function does not display the dialog box and was successful, the return
value is IDOK. The return value is less than zero if the function failed.


Comments

The export ordinal for this function is 90.

If wMode includes DM_PROMPT, the ExtDeviceMode function creates an
application-modal dialog box using the DialogBox function (USER.240). The
dialog box must provide options for the user to set the various settings of
the device. ExtDeviceMode does the following:

1.  Initializes the dialog box settings by using the environment specified
    by lpDevModeInput, by retrieving the current environment using the
    GetEnvironment function (GDI.133), or by reading the environment from
    the corresponding, device-specific section in the WIN.INI file.

2.  Calls the DialogBox box to display the dialog box, then waits for the
    user to complete their changes. When the value returns from DialogBox,
    check the return value. Make subsequent updates only if the return
    value is IDOK.

3.  Updates the current device environment by using the SetEnvironment
    function (GDI.132). Also, it updates the corresponding device-specific
    section in the WIN.INI file (or specified initialization file) if wMode
    includes DM_UPDATE.

4.  Sends a WM_DEVMODE message to all applications informing them of a
    change to the device's operating modes.

The dialog box must provide at least a title bar and OK and Cancel buttons
in addition to controls for the various operating modes. The title bar
should contain the name of the current printer model (if the driver
supports several models), but no other printer model information should be
presented in the dialog box. (The ExtDeviceMode dialog box cannot permit
the user to change device models.)

If a device has too many options to fit in a single dialog box,
ExtDeviceMode can provide nested dialog boxes, using buttons in the first
dialog box to access the others. In all cases, a dialog function for a
ExtDeviceMode dialog box must close the dialog box if it receives a
WM_COMMAND message with the wParam parameter set to IDCANCEL. This message
occurs when the user presses the ESC key, chooses the Cancel button in the
dialog box, or when Windows Help needs to close the dialog box in order to
respond to a request for help from another application.


See Also

AdvancedSetUpDialog, DeviceMode



ExtTextOut

    DWORD ExtTextOut(lpDestDev, wDestXOrg, wDestYOrg,
                       lpClipRect, lpString, wCount, lpFontInfo,
                       lpDrawMode, lpTextXForm, lpCharWidths,
                       lpOpaqueRect, wOptions)
    LPPDEVICE lpDestDev;
    WORD wDestXOrg;
    WORD wDestYOrg;
    LPRECT lpClipRect;
    LPSZ lpString;
    int wCount;
    LPFONTINFO lpFontInfo;
    LPDRAWMODE lpDrawMode;
    LPTEXTXFORM lpTextXForm;
    LPSHORT lpCharWidths;
    LPRECT lpOpaqueRect;
    WORD wOptions;

The ExtTextOut function writes text strings by converting characters in a
given string into raster, vector, or outline glyphs and copying the glyphs
to the given device or bitmap. Depending on the value of its parameters,
ExtTextOut also computes the x and y extents of the bounding rectangle of
the displayed string, clips the text to fit a given clipping rectangle,
fills a given rectangle with the specified background color before copying
glyphs, and overrides the default spacing of the glyphs using values
specified in an array of character widths. GDI may call ExtTextOut if an
application calls the TextOut function (GDI.33), the ExtTextOut function
(GDI.351), or GetTextExtent function (GDI.91).

A graphics driver must export the ExtTextOut function if the
RC_GDI20_OUTPUT value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the device or bitmap
   to receive the text output.

   wDestXOrg
   Specifies the x-coordinate (in device units) of the starting point for
   the string.

   wDestYOrg
   Specifies the y-coordinate (in device units) of the starting point for
   the string.

   lpClipRect
   Points to a RECT structure specifying the clipping rectangle.

   lpString
   Points to a null-terminated character string specifying the characters
   to display.

   wCount
   Specifies which action to carry out. It can be one of the following
   values.

    Value      Meaning
    -----------------------------------------------------------------------

    Negative   Compute the x and y extents of the smallest rectangle that
               completely encloses the displayed string, but do not
               generate output. In this case, the absolute value of wCount
               specifies the number of characters in the string. The
               function uses the current font, text justification, and
               other factors to compute the bounding rectangle, but does
               not apply the clipping rectangle. The function must update
               the BreakErr member specified by the lpDrawMode parameter.

    0          Fill the rectangle specified by lpOpaqueRect but only if
               wOptions is ETO_OPAQUE. In this case, the function does not
               generate text output.

    Positive   Draw the characters in the string. wCount specifies the
               number of characters to draw. The function uses the current
               font, text justification, escapement, rotation, and other
               factors to draw the characters, and it applies the clipping
               and opaque rectangles if specified. If the function modifies
               the BreakErr member specified by the lpDrawMode parameter,
               it must restore the member to its original value.

   lpFontInfo
   Points to a FONTINFO structure specifying the physical font to use.

   lpDrawMode
   Points to a DRAWMODE structure specifying the current text color,
   background mode, background color, text justification, and character
   spacing.

   lpTextXForm
   Points to a TEXTXFORM structure specifying additional information about
   the appearance of the characters when drawn.

   lpCharWidths
   Points to an array of character widths. If this parameter is not NULL,
   each element in the array is the advance width (in device units) of the
   corresponding character in the string. The function uses these widths
   (instead of the default character widths) to compute the position of the
   next character in the string. There must be one advance width for each
   character in the string.

   lpOpaqueRect
   Points to a RECT structure specifying the opaquing rectangle. This
   parameter can be NULL.

   wOptions
   Specifies which action to carry out. It can be a combination of the
   following values.

    Value             Meaning
    -----------------------------------------------------------------------

    ETO_OPAQUE (2)    Fills the rectangle specified by the lpOpaqueRect
                      parameter (and clipped to the lpClipRect parameter)
                      with the background color specified by the lpDrawMode
                      parameter. The function fills the rectangle
                      regardless of the whether lpDrawMode specifies opaque
                      or transparent background mode.

    ETO_CLIPPED (4)   Creates a new clipping rectangle by intersecting the
                      rectangles specified by lpOpaqueRect and lpClipRect.


Return Value

If the wCount parameter is nonzero, this function returns the x and y
extents of the string's bounding rectangle; the x extent is in the
low-order 16 bits and the y extent in the high-order 16 bits. If the x
extent exceeds the maximum value for an extent (0x7FFF), the function
returns 0x7FFF in the low-order 16 bits and wDestXorg in the high-order 16
bits.

If wCount is zero, the return value is TRUE if the specified rectangle was
filled with the background color. In all other cases, the return value is
0x80000000L if an error occurred or no output was generated.


Comments

The export ordinal for this function is 14.

ExtTextOut places the upper-left corner of the string at the point defined
by the DestYOrg parameter. This means that the characters in the string
appear below and to the right of the starting point. In some cases,
character glyphs may overlap, especially if widths specified in
lpCharWidths are less than the default widths or are negative.

ExtTextOut uses the drawing mode specified by lpDrawMode to determine the
current text color, the background mode, and the background color. The
background mode determines whether ExtTextOut draws an opaque bounding box
before drawing the characters. The background color determines what color
that box must be. The text color determines the color of the text in the
box. For raster glyphs, all 1 bits must be the text color; for vector and
outline glyphs, lines and filled areas must be the text color. ExtTextOut
does not use the binary-raster operation mode (specified by the Rop2 member
in the DRAWMODE structure pointed to by the lpDrawMode parameter) when
drawing text.

ExtTextOut clips text to the rectangle specified by lpClipRect, or to the
intersection of lpClipRect and lpOpaqueRect if wOptions specifies
ETO_CLIPPED. Only pixels within the rectangle are drawn. (Pixels that have
the same x-coordinate as the rectangle's right edge, or the same
y-coordinate as the rectangle's bottom edge are not in the rectangle.) For
example, no pixels are drawn if the clipping rectangle is empty (zero width
and height), and only one pixel is drawn if it has a width and height of 1.

ExtTextOut uses the lpTextXForm parameter only if the device supports the
additional text transformation capabilities. For example, if lpTextXForm
specifies a point size different from the one specified by lpFontInfo,
ExtTextOut should ignore the lpTextXForm point size unless the function can
size characters. Text transformation capabilities are specified in the
dpText member of the driver's GDIINFO structure.

If the TBreakExtra or CharExtra members in the DRAWMODE structure pointed
to by the lpDrawMode parameter is nonzero, ExtTextOut must adjust widths of
break characters or other characters using the following or similar
algorithm:

    int width;  /* width of character */

    for (i=0; i<wCount; i++) {

        /* Set width here using the default character for lpString[i]. */
        /* The default width and how to retrieve it depends */
        /* on the font. */

      if ((lpDrawMode->TBreakExtra != 0) &&
          (lpString[i]==lpFont->dfBreakChar)) {
          width = width + lpDrawMode->BreakExtra;
          lpDrawMode->BreakErr=lpDrawMode->BreakErr-lpDrawMode->BreakRem;
          if (lpDrawMode->BreakErr <= 0) {
                  width = width ++
                  BreakErr = BreakErr + BreakCount
          }
      }
      width = width + lpDrawMode->CharExtra;
    }

See Also

StrBlt



GetCharWidth

    WORD GetCharWidth(lpDestDev, lpBuffer, wFirstChar,
                      wLastChar, lpFontInfo, lpDrawMode,
                      lpFontTrans)
    LPPDEVICE lpDestDev;
    LPWORD lpBuffer;
    WORD wFirstChar;
    WORD wLastChar;
    LPFONTINFO lpFontInfo;
    LPDRAWMODE lpDrawMode;
    LPTEXTXFORM lpFontTrans;

The GetCharWidth function computes the widths of each character within the
given range, and copies the widths to the buffer pointed to by the lpBuffer
parameter. GDI calls this function when an application calls the
GetCharWidth function (GDI.350).

A graphics driver must export the GetCharWidth function if the
RC_GDI20_OUTPUT value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpBuffer
   Points to the buffer to receive the character widths. The buffer must be
   an array of 16-bit elements. There must be one element for each
   character in the range.

   wFirstChar
   Specifies the first character of the range.

   wLastChar
   Specifies the last character of the range.

   lpFontInfo
   Points to a FONTINFO structure that specifies the physical font from
   which to compute the character widths.

   lpDrawMode
   Points to a DRAWMODE structure that specifies the current text color,
   background mode, background color, text justification, and character
   spacing that may need to be applied to the font to compute a character
   width.

   lpFontTrans
   Points to a TEXTXFORM structure that specifies the any font
   transformations, such as scaling and italicizing, that may need to be
   applied to the font to compute a character width.


Return Value

The return value is 1 if the function is successful. Otherwise, it is zero
if there is an error.


Comments

The export ordinal for this function is 15.

The function assigns the default character to characters outside of the
font's range.

GetCharWidth is an optional function for printers, but highly recommended.


See Also

ExtTextOut



GetDriverResourceID

    int GetDriverResourceID(iResId, lpResType)
    int iResId;
    LPSTR lpResType;

The GetDriverResourceID function returns the resource identifier for a
given resource type. USER calls this function before loading the icon,
cursor, and bitmap, and OEMBIN resources to let the display driver map the
requested resource to a resource that better suits the display resolution.

Display drivers that provide resources in multiple resolutions must export
the GetDriverResourceID function.


Parameters

   iResId
   Specifies a resource identifier.

   lpResType
   Points to a null-terminated ASCII string specifying the name of the
   resource type. If the high word of the lpResType parameter is zero, the
   parameter is a value and not a pointer. In this case, the low 16 bits
   specifies the resource-type identifier.


Return Value

The return value is the identifier of a resource having the same type as
specified by lpResType. If the display driver has no better resource, the
return value is specified by the iResID parameter.


Comments

The export ordinal for this function is 450.

GetDriverResourceID must not attempt to map resources of different types.



GetPalette

    VOID GetPalette(nStartIndex, nNumEntries, lpPalette)
    WORD nStartIndex;
    WORD nNumEntries;
    LPRGBQUAD lpPalette;

The GetPalette function retrieves the logical colors (RGB values) for the
given color indexes. The function copies RGB structure color values to the
buffer pointed to by the lpPalette parameter.

A graphics driver must export the GetPalette function if the RC_PALETTE
value is set in the dpRaster member of the driver's GDIINFO structure.


Parameters

   nStartIndex
   Specifies the color index of the first color to retrieve.

   nNumEntries
   Specifies the total number of entries to retrieve from the device's
   hardware palette.

   lpPalette
   Points to the buffer to receive the RGB colors.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 23.


See Also

SetPalette



GetPalTrans

    void GetPalTrans(lpIndexes);
    LPWORD lpIndexes;        /* points to array of indexes */

The GetPalTrans functions copies the driver's translation table into the
array pointed to by the lpIndexes parameter.

A graphics driver must export the GetPalTrans function if the RC_PALETTE
value is set in the dpRaster member of the driver's GDIINFO structure.


Parameters

   lpIndexes
   Points to the array to receive color indexes. The number of indexes in
   the array is specified by the dpPalColors member in the device's GDIINFO
   structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 25.


See Also

SetPalTrans



Output

    WORD Output(lpDestDev, wStyle, wCount, lpPoints,
                lpPPen, lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    WORD wStyle;
    WORD wCount;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The Output function draws the lines and figures specified by the wStyle
parameter. GDI calls this function when an application calls functions,
such as LineTo (GDI.19), Rectangle (GDI.27), and Ellipse (GDI.24).

Every graphics driver must export an Output function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wStyle
   Specifies the type of output to draw. This parameter can be one of the
   following values.

    Value                 Meaning
    -----------------------------------------------------------------------

    OS_ARC (3)            Draws an arc.

    OS_SCANLINES (4)      Draws a set of horizontal line segments.

    OS_RECTANGLE (6)      Draws a rectangle.

    OS_ELLIPSE (7)        Draws an ellipse.

    OS_POLYLINE (18)      Draws a set of connected line segments.

    OS_WINDPOLYGON (20)   Draws a polygon and fill it using the
                          winding-number-filling method.

    OS_ALTPOLYGON (22)    Draws a polygon and fills it using the
                          alternate-filling method.

    OS_PIE (23)           Draws a closed figure consisting of an arc and
                          two line segments connecting the endpoints of the
                          arc to the centerpoint of the arc's bounding
                          rectangle.

    OS_CHORD (39)         Draws a closed figure consisting of an arc and
                          the chord connecting the endpoints of the arc.

    OS_CIRCLE (55)        Draws a circle.

    OS_ROUNDRECT (72)     Draws a rectangle with round corners.

    OS_BEGINNSCAN (80)    Begins a series of scan lines.

    OS_ENDNSCAN (81)      Ends a series of scan lines.

   For a full description of each style, see the subsequent Output
   description pages.

   wCount
   Specifies the number of POINT structures in the array pointed to by the
   lpPoints parameter.

   lpPoints
   Points to an array of POINT structures. The array has wCount elements.
   For most output styles, this parameter contains the device coordinates
   for each point in the figure.

   lpPPen
   Points to a PPEN structure specifying the physical pen to use to draw
   lines and borders. This parameter is NULL if no lines or borders are to
   be drawn.

   lpPBrush
   Points to a PBRUSH structure specifying the physical brush to use to
   fill the interiors of figures and draw scan lines. This parameter is
   NULL if no interiors or scan lines are to be drawn.

   lpDrawMode
   Points to a DRAWMODE structure containing information to use when
   drawing, such as binary-raster operation, background mode, and
   foreground and background color.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function is successful. Otherwise, it is zero
if the function encounters an unrecoverable error. The return value is -1
if the function does not support the given style and wants GDI to simulate
the output.


Comments

The export ordinal for this function is 8.

Output uses the binary-raster operation, background mode, and background
color specified by the DRAWMODE structure to draw lines and scan lines.
Output uses the binary-raster operation to determine how to combine pen or
brush colors with the existing color on the display surface. The function
uses background mode to determine how to fill gaps in styled lines or
hatched brushes. If the background mode is OPAQUE, Output combines the
background color with the existing color in the gaps. If the background
mode is TRANSPARENT, Output leaves the existing color unchanged. For all
pen or brush styles other than styled lines and hatched brushes, Output
draws as if the background mode is OPAQUE regardless of the actual
background mode.

Output uses the lpClipRect parameter only if the driver has set either the
CP_RECTANGLE or CP_REGION value in the dpClip member of the GDIINFO
structure. Output ensures that the coordinates specified by the lpClipRect
parameter do not extended beyond the boundaries of the display surface.


See Also

Output(OS_ALTPOLYGON), Output(OS_ARC), Output(OS_BEGINNSCAN),
Output(OS_CHORD), Output(OS_CIRCLE), Output(OS_ELLIPSE),
Output(OS_ENDNSCAN), Output(OS_PIE), Output(OS_POLYLINE),
Output(OS_RECTANGLE), Output(OS_ROUNDRECT), Output(OS_SCANLINES),
Output(OS_WINDPOLYGON)



Output(OS_ALTPOLYGON)

    WORD Output(lpDestDev, OS_ALTPOLYGON, wCount, lpPoints,
                lpPPen, lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    WORD wCount;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_ALTPOLYGON style specifies that the Output function draws a polygon
and fills it using the alternate-filling method. GDI calls Output with this
style when an application calls functions, such as the Polygon function
(GDI.36), and the current polygon-filling mode is ALTERNATE.

The graphics driver must support the OS_ALTPOLYGON style if the
PC_ALTPOLYGON bit is set in the dpPolygonals member of the GDIINFO
structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wCount
   Specifies the POINT structures in the array pointed to by the lpPoints
   parameter.

   lpPoints
   Points to an array of POINT structures containing wCount elements. Each
   point represents a vertex of the polygon.

   lpPPen
   Points to a PPEN structure that specifies the physical pen to draw the
   border of the polygon.

   lpPBrush
   Points to a PBRUSH structure that specifies the physical brush to fill
   the polygon.

   lpDrawMode
   Points to a DRAWMODE structure containing the drawing information to
   draw and fill the polygon.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function is successful. Otherwise, it is zero
if the function encounters an unrecoverable error. The return value is -1
if the function does not support the given style and wants GDI to simulate
the output.


Comment

The Output function fills the interior of the polygon first, then draws the
border.

To fill the polygon, Output calculates the polygon outline and fills it
according to the alternate-filling method. Alternate filling typically
fills every other closed area within a polygon. In general, a given area
should be filled if a horizontal ray, starting in the area and continuing
through the left edge of the polygon, crosses an odd number of polygon
sides.

To draw the border, Output draws a line segment from the first point in the
array to the second, from the second to the third, and so on. If the last
line segment does not end at the first point, Output draws this line
segment to ensure a closed figure.

Although the Output function can use device hardware to draw and fill
polygons, the function either must provide the same capability when drawing
to a main memory bitmap, or returns a value of -1 to direct GDI to simulate
the output using polylines and scan lines.


See Also

Output(OS_WINDPOLYGON)



Output(OS_ARC)

    WORD Output(lpDestDev, OS_ARC, 5, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_ARC style specifies that the Output function draws the arc that lies
between calculated endpoints on the specified ellipse.

A graphics driver must support the OS_ARC style if the CC_ELLIPSES or
CC_CIRCLES value is set in the dpCurves member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array containing five POINT structures. The elements of the
   array are defined as follows.

    Index   Description
    -----------------------------------------------------------------------

    0       Upper-left corner of the bounding rectangle.

    1       Lower-right corner of the bounding rectangle.

    2       Starting point for the arc.

    3       Ending point for the arc.

    4       Start and stop angles (reserved; do not use).

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw the arc.

   lpPBrush
   Points to a PBRUSH structure. This parameter is not used to draw an arc.

   lpDrawMode
   Points to a DRAWMODE structure containing drawing information to draw
   the arc.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the arc and chord. Otherwise,
it is zero if the function encounters an unrecoverable error. The return
value is -1 if the function cannot draw the specified arc and wants GDI to
simulate it.


Comments

Output draws an arc by drawing a portion of the ellipse contained in the
specified bounding rectangle. The function calculates the endpoints of the
arc using the starting and ending points; each endpoint is the intersection
of the ellipse and a ray drawn from the center of the bounding rectangle
through the specified starting or ending point. Output draws the arc in a
counterclockwise direction, from starting point up to, but not including,
the ending point.


See Also

Output(OS_CHORD), Output(OS_PIE)



Output(OS_BEGINNSCAN)

    WORD Output(lpDestDev, OS_BEGINNSCAN, 0, NULL, lpPPen,
                lpPBrush, lpDrawMode, NULL)
    LPPDEVICE lpDestDev;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;

The OS_BEGINNSCAN style specifies that the Output function prepares for a
subsequent series of calls to the Output function in which the OS_SCANLINES
style is specified.

Every graphics driver (for Windows versions 2.0 and later) should support
the OS_BEGINNSCAN style.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw
   subsequent scan lines. If it is NULL, no pen is used.

   lpPBrush
   Points to a PBRUSH structure specifying the physical brush to draw
   subsequent scan lines. If it is NULL, no brush is used.

   lpDrawMode
   Points to a DRAWMODE structure containing drawing information when
   drawing subsequent scan lines.


Return Value

The return value is 1.


Comments

GDI uses the OS_BEGINNSCAN and OS_ENDNSCAN styles to mark the beginning and
end of a series of scan lines that use the same pen, brush, and drawing
mode. GDI calls the Output function with the OS_BEGINNSCAN style to let the
driver prepare the drawing mode and physical pen and brush for use in
subsequent calls containing the OS_SCANLINE style. Drivers that preserve
these objects between calls to Output can improve performance by minimizing
the number of times the objects need to be set up. All subsequent calls
using the OS_SCANLINE style will use the same objects until GDI calls with
a matching OS_ENDNSCAN style.

If a driver does not support the OS_BEGINNSCAN style, the driver can ignore
the style. In all cases, GDI passes the physical pen, physical brush, and
drawing mode on each subsequent call to the Output function regardless of
whether the driver prepared these objects previously.


See Also

Output(OS_ENDNSCAN)



Output(OS_CHORD)

    WORD Output(lpDestDev, OS_CHORD, 5, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_CHORD style specifies that the Output function draws an arc and the
chord connecting the endpoints of the arc. Since the resulting figure is
closed, Output fills the figure as well as draws the border. GDI calls this
style when an application calls the Chord function (GDI.348).

A graphics driver must support this style if the CC_CHORD value is set in
the dpCurves member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array containing five POINT structures. The elements of the
   array are defined as follows.

    Index   Description
    -----------------------------------------------------------------------

    0       Upper-left corner of the bounding rectangle.

    1       Lower-right corner of the bounding rectangle.

    2       Starting point for the arc.

    3       Ending point for the arc.

    4       Start and stop angles (reserved; do not use).

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw the
   border.

   lpPBrush
   Points to a PBRUSH structure specifying the physical brush to fill the
   figure.

   lpDrawMode
   Points to a DRAWMODE structure containing information when drawing the
   border and filling the interior.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the arc and chord. Otherwise,
it is zero if the function encounters an unrecoverable error. The return
value is -1 if the function cannot draw the specified arc and chord and
wants GDI to simulate it.


Comments

Output draws the arc and chord by first filling the interior then drawing
the border.

Output draws an arc by drawing a portion of the ellipse contained in the
specified bounding rectangle. The function calculates the endpoints of the
arc using the starting and ending points; each endpoint is the intersection
of the ellipse and a ray drawn from the center of the bounding rectangle
through the specified starting or ending point. Output draws the arc in a
counterclockwise direction, from starting point up to, but not including,
the ending point.


See Also

Output(OS_ARC), Output(OS_PIE)



Output(OS_CIRCLE)

    WORD Output(lpDestDev, OS_CIRCLE, 2, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_CIRCLE style specifies that the Output function draws a circle.
Since the resulting figure is closed, Output fills the figure as well as
draws the border. GDI calls this function when an application calls the
Ellipse function (GDI.24) with a bounding rectangle that is square.

A graphics driver must support this style if the CC_CIRCLES value is set in
the dpCurves member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array containing two POINT structures. The elements of the
   array are defined as follows.

    Index   Description
    -----------------------------------------------------------------------

    0       Upper-left corner of the bounding rectangle.

    1       Lower-right corner of the bounding rectangle.

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw the
   border.

   lpPBrush
   Points to a PBRUSH structure specifying the physical brush to fill the
   circle.

   lpDrawMode
   Points to a DRAWMODE structure containing information when drawing the
   border and filling the interior.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the circle. Otherwise, it is
zero if the function encounters an unrecoverable error. The return value is
-1 if the function cannot draw the specified circle and wants GDI to
simulate it.


Comments

Output draws the circle by first filling the interior then drawing the
border. The center of the circle is at the center of the bounding
rectangle; the radius is equal to half the width of the rectangle.

If a graphics driver can draw ellipses and has set the CC_ELLIPSES value in
the dpCurves member, it does not need to set the CC_CIRCLES value in the
dpCurves member. In such cases, GDI calls Output with the OS_ELLIPSE style
when an application draws a circle.


See Also

Output(OS_ELLIPSE)



Output(OS_ELLIPSE)

    WORD Output(lpDestDev, OS_ELLIPSE, 2, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_ELLIPSE style specifies that the Output function draws an ellipse.
Since the resulting figure is closed, Output fills the figure as well as
draws the border. GDI calls this function when an application calls the
Ellipse function (GDI.24).

A graphics driver must support this style if the CC_ELLIPSES value is set
in the dpCurves member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array containing two POINT structures. The elements of the
   array are defined as follows.

    Index   Description
    -----------------------------------------------------------------------

    0       Upper-left corner of the bounding rectangle.

    1       Lower-right corner of the bounding rectangle.

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw the
   border.

   lpPBrush
   Points to a PBRUSH structure specifying the physical brush to fill the
   ellipse.

   lpDrawMode
   Points to a DRAWMODE structure containing information when drawing the
   border and filling the interior.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the ellipse. Otherwise, it is 0
if the function encounters an unrecoverable error. The return value is -1
if the function cannot draw the specified circle and wants GDI to simulate
it.


Comments

Output draws the ellipse by first filling the interior then drawing the
border. The center of the ellipse is at the center of the bounding
rectangle; the semi-major and semi-minor axes of the ellipse are equal to
half the width and height of the rectangle.


See Also

Output(OS_CIRCLE)



Output(OS_ENDNSCAN)

    WORD Output(lpDestDev, OS_ENDNSCAN, 0, NULL, NULL, NULL,
                NULL, NULL)
    LPPDEVICE lpDestDev;

The OS_ENDNSCAN style specifies that the Output function carries out any
action needed to complete a series of scan line output. GDI calls this
function to mark the end of a series of calls to the Output function in
which the OS_SCANLINES style is specified. GDI marks the start of the
series with a matching OS_BEGINNSCAN style.

Every graphics driver (for versions 2.0 and later) should support the
OS_ENDNSCAN style.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.


Return Value

The return value is 1.


See Also

Output(OS_BEGINNSCAN)



Output(OS_PIE)

    WORD Output(lpDestDev, OS_PIE, 5, lpPoints, lpPPen, lpPBrush,
                lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_PIE style specifies that the Output function draws an arc and two
line segments that connect the endpoints of the arc to the center of the
arc's bounding rectangle. Since the resulting figure is closed, Output
fills the figure as well as draws the border. GDI calls this function when
an application calls the Pie function (GDI.26).

A graphics driver must support the OS_PIE style if the CC_PIE value is set
in the dpCurves member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array containing five POINT structures. The elements of the
   array are defined as follows.

    Index   Description
    -----------------------------------------------------------------------

    0       Upper-left corner of the bounding rectangle.

    1       Lower-right corner of the bounding rectangle.

    2       Starting point for the arc.

    3       Ending point for the arc.

    4       Start and stop angles. Reserved; do not use.

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw the arc
   and line segments.

   lpPBrush
   Points to a PBRUSH structure specifying the brush to fill the figure.

   lpDrawMode
   Points to a DRAWMODE structure containing drawing information to draw
   the border and fill the figure.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the figure. Otherwise, it is
zero if the function encounters an unrecoverable error. The return value is
-1 if the function cannot draw the specified figure and wants GDI to
simulate it.


Comments

Output draws the pie-shaped figure by first filling the interior then
drawing the border.

Output draws an arc by drawing a portion of the ellipse contained in the
specified bounding rectangle. The function calculates the endpoints of the
arc using the starting and ending points; each endpoint is the intersection
of the ellipse and a ray drawn from the center of the bounding rectangle
through the specified starting or ending point. Output draws the arc in a
counterclockwise direction, from starting point up to, but not including,
the ending point.

Output draws the two line segments from the endpoints of the arc to the
point at the center of the bounding rectangle.


See Also

Output(OS_ARC), Output(OS_CHORD)



Output(OS_POLYLINE)

    WORD Output(lpDestDev, OS_POLYLINE, wCount, lpPoints, lpPPen,
                NULL, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    WORD wCount;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_POLYLINE style specifies that the Output function draws a set of
line segments. Although the line segment may create a closed figure, Output
never fills the figure. GDI calls this function when an application calls
functions such as the Polyline function (GDI.37).

Every graphics driver (for Windows version 2.0 and later) must support the
OS_POLYLINE style.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wCount
   Specifies the number of POINT structures in the array pointed to by the
   lpPoints parameter. The wCount parameter must be at least two.

   lpPoints
   Points to an array of POINT structures specifying the endpoints of the
   lines segments. The array has wCount elements.

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw lines.

   lpDrawMode
   Points to a DRAWMODE structure containing information when drawing, such
   as binary raster operation, background mode, and foreground and
   background color.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the figure. Otherwise, it is
zero if the function encounters an unrecoverable error. The return value is
-1 if the function cannot draw the specified figure and wants GDI to
simulate it.


Comments

Output draws each line segment from its starting point up to, but not
including, its end point. If more than one line segment is drawn, each new
segment starts at the end point of the previous segment.

Since Output does not use a physical brush to draw the lines, the lpPBrush
parameter is usually NULL.


See Also

Output(OS_ALTPOLYGON), Output(OS_WINDPOLYGON)



Output(OS_RECTANGLE)

    WORD Output(lpDestDev, OS_RECTANGLE, 2, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_RECTANGLE style specifies that the Output function draws a rectangle
and fills it using a specified brush. GDI calls this function when an
application calls the Rectangle function (GDI.27).

The graphics driver must support the OS_RECTANGLE style if the PC_RECTANGLE
value is set in the dpPolygonals member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array of two POINT structures representing the corners of
   the rectangle.

   lpPPen
   Points to a PPEN structure that specifies the physical pen to draw the
   border of the rectangle.

   lpPBrush
   Points to a PBRUSH structure that specifies the physical brush to fill
   the rectangle.

   lpDrawMode
   Points to a DRAWMODE structure containing the drawing information to
   draw and fill the rectangle.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the figure. Otherwise, it is
zero if the function encounters an unrecoverable error. The return value is
-1 if the function cannot draw the specified figure and wants GDI to
simulate it.


Comments

The Output function fills the interior of the rectangle first, then draws
the border. Before filling and drawing, Output must subtract one from the
bottom and right coordinates. GDI requires that rectangles are drawn so
that the border lies one pixel within the specified right and bottom edges.


See Also

Output(OS_ALTPOLYGON), Output(OS_WINDPOLYGON)



Output(OS_ROUNDRECT)

    WORD Output(lpDestDev, OS_ROUNDRECT, 3, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_ROUNDRECT style specifies that the Output function draws and fills a
rectangle having rounded corners. GDI calls this function when an
application calls the RoundRect function (GDI.28).

The graphics driver must support the OS_ROUNDRECT style if the CC_ROUNDRECT
value is set in the dpCurves member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   lpPoints
   Points to an array of three POINT structures representing the corners of
   the rectangle and the width and height of the ellipse used to draw the
   corners.

   lpPPen
   Points to a PPEN structure that specifies the physical pen to draw the
   border of the rectangle.

   lpPBrush
   Points to a PBRUSH structure that specifies the physical brush to fill
   the rectangle.

   lpDrawMode
   Points to a DRAWMODE structure containing the drawing information to
   draw and fill the rectangle.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the figure. Otherwise, it is
zero if the function encounters an unrecoverable error. The return value is
-1 if the function cannot draw the specified figure and wants GDI to
simulate it.


Comments

The Output function fills the interior of the rectangle first, then draw
the border. Before filling and drawing, Output must subtract one from the
bottom and right coordinates. GDI requires that rectangles are draw so that
the border lies one pixel within the specified right and bottom edges.


See Also

Output(OS_ALTPOLYGON), Output(OS_RECTANGLE), Output(OS_WINDPOLYGON)



Output(OS_SCANLINES)

    WORD Output(lpDestDev, OS_SCANLINES, wCount, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    WORD wCount;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_SCANLINES style specifies that the Output function draws a series of
horizontal line segments at a specified vertical position. GDI calls this
function when simulating output such as filling a polygon.

Every graphics driver should support the OS_SCANLINES style.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wCount
   Specifies the number of POINT structures in the array pointed to by the
   lpPoints parameter.

   lpPoints
   Points to an array of POINT structures containing the scan line
   coordinates. The y member in the first POINT structure specifies the
   y-coordinate to draw the scan lines. In each subsequent structure, the x
   member specifies the x-coordinate of a scan line's starting point and
   the y member specifies the x-coordinate of the ending point.

   lpPPen
   Points to a PPEN structure specifying the physical pen to draw scan
   lines.

   lpPBrush
   Points to a PBRUSH structure specifying the physical brush to draw the
   scan lines.

   lpDrawMode
   Points to a DRAWMODE structure containing information to use when
   drawing, such as binary-raster operation, background mode, and
   foreground and background color.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function is successful. Otherwise, it is zero
if the function encounters an unrecoverable error.


Comments

Output draws a scan line from the starting point up to, but not including,
the ending point. The function draws all lines with the brush pointed to by
the lpPBrush parameter, or by the pen pointed to by the lpPPen parameter if
lpPBrush is NULL. If Output uses the pen to draw the scan lines, it should
not dither the pen color.


See Also

Output(OS_BEGINNSCAN), Output(OS_ENDNSCAN)



Output(OS_WINDPOLYGON)

    WORD Output(lpDestDev, OS_WINDPOLYGON, wCount, lpPoints, lpPPen,
                lpPBrush, lpDrawMode, lpClipRect)
    LPPDEVICE lpDestDev;
    WORD wCount;
    LPPOINT lpPoints;
    LPPPEN lpPPen;
    LPPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClipRect;

The OS_WINDPOLYGON style specifies that the Output function draws a polygon
and fills it using the winding-number-filling method. GDI calls Output with
this style when an application calls functions, such as the Polygon
function (GDI.36), and the current polygon-filling mode is WINDING.

The graphics driver must support the OS_WINDPOLYGON style if the
PC_WINDPOLYGON value is set in the dpPolygonals member of the GDIINFO
structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wCount
   Specifies the number of POINT structures in the array pointed to by the
   lpPoints parameter.

   lpPoints
   Points to an array of POINT structures containing wCount elements. Each
   point represents a vertex of the polygon.

   lpPPen
   Points to a PPEN structure that specifies the physical pen to draw the
   border of the polygon.

   lpPBrush
   Points to a PBRUSH structure that specifies the physical brush to fill
   the polygon.

   lpDrawMode
   Points to a DRAWMODE structure containing the drawing information to
   draw and fill the polygon.

   lpClipRect
   Points to a RECT structure containing coordinates for the clipping
   rectangle. If the lpClipRect parameter is NULL, the clipping rectangle
   is the entire display surface.


Return Value

The return value is 1 if the function draws the figure. Otherwise, it is
zero if the function encounters an unrecoverable error. The return value is
-1 if the function cannot draw the specified figure and wants GDI to
simulate it.


Comments

The Output function should fill the interior of the polygon first, then
draw the border.

To fill the polygon, Output calculates the polygon outline and fill
according to the winding-number-filling method. Winding-number filling
depends on the direction (down or up) that each side of the polygon is
drawn. With winding-number filling, a given closed area within a polygon
should be filled if a horizontal ray, starting in the area and continuing
through the left edge of the polygon, crosses an unequal number of upwardly
and downwardly drawn sides.

To draw the border, Output draws a line segment from the first point in the
array to the second, from the second to the third, and so on. If the last
line segment does not end at the first point, Output draws this line
segment to ensure a closed figure.

Although the Output function can use device hardware to draw and fill
polygons, the function either must provide the same capability when drawing
to a main memory bitmap, or return -1 to direct GDI to simulate the output
using polylines and scan lines.


See Also

Output(OS_ALTPOLYGON)



Pixel

    DWORD Pixel(lpDestDev, X, Y, dwPhysColor, lpDrawMode)
    LPPDEVICE lpDestDev;
    WORD X;
    WORD Y;
    DWORD dwPhysColor;
    LPDRAWMODE lpDrawMode;

The Pixel function sets or retrieves the color of the specified pixel. The
function sets the given pixel to the color given by the dwPhysColor
parameter if the lpDrawMode parameter specifies a binary-raster operation.
Pixel returns the physical color of the pixel if the lpDrawMode parameter
is NULL. GDI calls this function when simulating output or when an
application calls the SetPixel or GetPixel function (GDI.31 or GDI.83).

Every graphics driver must export a Pixel function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   X
   Specifies the x-coordinate of the pixel to retrieve or set.

   Y
   Specifies the y-coordinate of the pixel to retrieve or set.

   dwPhysColor
   Specifies the physical color value used to set the pixel.

   lpDrawMode
   Points to a DRAWMODE structure specifying the binary-raster operation to
   use to combine the physical color with the existing pixel color.

   If lpDrawMode is NULL, Pixel retrieves and returns the current color of
   the specified pixel.


Return Value

The return value is either the physical color of the specified pixel or 1
depending on whether lpDrawMode is NULL, if the function is successful.
Otherwise, the function returns 0x80000000L.


Comments

The export ordinal for this function is 9.



RealizeObject

    DWORD RealizeObject(lpDestDev, wStyle, lpInObj, lpOutObj,
                        lpTextXForm)
    LPPDEVICE lpDestDev;
    WORD wStyle;
    LPVOID lpInObj;
    LPVOID lpOutObj;
    LPTEXTXFORM lpTextXForm;

The RealizeObject function creates or deletes a physical object. The
function creates a physical object by filling a structure provided by GDI
with device-specific data that corresponds to the attributes of a given
logical pen, brush, bitmap, or font; it deletes the physical object by
removing any memory or resources it allocated when creating the object. GDI
may call this function when an application calls functions such as CreateDC
(GDI.53), SelectObject (GDI.45), and DeleteObject (GDI.69).

Every graphics driver must export the RealizeObject function.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the device or bitmap
   to create the physical object for.

   wStyle
   Specifies the type of object to be realized. This parameter can be one
   of the following values.

    Value             Meaning
    -----------------------------------------------------------------------

    OBJ_PEN (1)       Realizes a physical pen.

    OBJ_BRUSH (2)     Realizes a physical brush.

    OBJ_FONT (3)      Realizes a device font. If the device has no device
                      fonts or cannot realize the requested font, the
                      RealizeObject function returns zero.

    OBJ_PBITMAP (5)   Realizes a device bitmap. GDI passes this value only
                      if the RC_DEVBITS value is set in the dpRaster member
                      of the driver's GDIINFO structure.

   If the wStyle parameter is negative, the function deletes the specified
   object.

   lpInObj
   Points to a LPEN, LBRUSH, LFONT, or PBITMAP structure specified by the
   wStyle parameter. The structure describes the logical attributes of the
   object to be realized.

   If wStyle is negative, the lpInObj parameter points to the PPEN, PBRUSH,
   FONTINFO, or PBITMAP structure, specifying the physical object to be
   deleted.

   lpOutObj
   Points to a buffer to receive the realized object, or points to the
   physical object to delete. Its meaning depends on the value of the
   wStyle parameter.

   If wStyle is positive, the lpOutObj parameter points to a buffer. The
   function fills the buffer with device-specific data that defines a
   physical object corresponding to the logical object pointed to by the
   lpInBuf parameter. If lpOutObj is NULL, the function returns the size
   (in bytes) of the physical object.

   If wStyle is negative, lpOutBuf points to the physical object to delete.
   Although GDI frees the memory pointed to by lpOutBuf when the function
   returns, the RealizeObject function must free any other memory or
   resources associated with the physical object.

   lpTextXForm
   Points to a TEXTXFORM structure or specifies a POINT structure as
   specified by the wStyle parameter.

   If wStyle is OBJ_BRUSH, the lpTextXForm parameter is a POINT structure
   containing the x- and y-coordinates (relative to an 8-bit boundary) on
   which to align the start of the brush's pattern.

   If wStyle is OBJ_FONT, lpTextXForm points to a TEXTXFORM structure
   containing information about the appearance of a realized font. Both the
   realized font and the contents of the TEXTXFORM structure are later
   passed to the ExtTextOut function, allowing more capable devices to make
   changes to the standard font.


Return Value

The return value is the size, in bytes, of the physical object, if
successful. Otherwise, it returns zero if it cannot realize the object.

If wStyle is OBJ_PBITMAP, the return value can be zero to direct GDI to
create a main memory bitmap instead of a device bitmap. The return value
will be 0x80000000L to indicate an error, and prevent GDI from creating a
main memory bitmap.


Comments

The export ordinal for this function is 10.

GDI manages the physical object and makes the object available to the the
device driver as needed to draw output. When GDI no longer needs the
object, it directs RealizeObject to delete the object.

To create an object, GDI calls this function twice. It first requests the
size in bytes of the physical object, then it allocates space for the
object and calls RealizeObject again passing a pointer to the allocated
space. The lpOutObj parameter specifies which action to take. If it is
NULL, the function returns the size; if it is not NULL, the function fills
the corresponding structure.

The format and content of a physical object depends entirely on the device
driver. For pens and brushes, the recommended formats are the PPEN and
PBRUSH structures. For fonts, the structure must contain the dfType through
dfFace members of the FONTINFO structure, and dfDevice and dfFace must have
valid pointers to device and font strings.

When realizing pens, GDI may request a width or styled line even though the
driver does not support such pens. (The dpCurves and dpLines members in the
driver's GDIINFO structure specify whether the driver supports wide and
styled lines.) In such cases, the RealizeObject function should create a
nominal pen, that is, a physical pen that is solid and one-pixel wide. GDI
uses this nominal pen to carry out its own styling and wide-line
operations.

When realizing brushes, RealizeObject sets the foreground and background
colors for hatch and solid brushes, but not for patterned brushes if the
patterned brush uses a monochrome bitmap. For these patterned brushes, GDI
provides a DRAWMODE structure that specifies the foreground and background
colors for the brush. If the color specified for a solid brush does not
exactly match a physical color, the function can create a dithered color
for the brush. The function realizes hollow brushes. When a hollow brush is
passed to a drawing routine, the driver does no filling at all.

If the lpTextXForm parameter specifies a POINT structure, it represents the
physical object's pattern reference point. This reference point specifies
where to start a patterned brush (relative to a 8-bit boundary) so that the
brush pattern aligns with areas previously filled using the brush. The
parameter contains values, in the range 0 to 7, that specify on which bits
to start the pattern.

Display drivers generally do not realize fonts. Instead, they require GDI
to realize the fonts to be used with the display. In this case, the display
driver's RealizeObject must returns zero whenever wStyle is OBJ_FONT.

When realizing bitmaps, RealizeObject must create a device bitmap, storing
the bitmap bits in device memory (such as RAM on the device adapter) rather
than main memory. When GDI requests the size of the physical bitmap, the
function must include space for at least a PBITMAP structure, but any
additional space is up to the driver. Although no space for the bitmap bits
is required, RealizeObject must include some value to indicate the location
of the bitmap bits in device memory. GDI intercepts all requests to create
monochrome bitmaps. This means RealizeObject is never called to create a
monochrome device bitmap.



ScanLR

    WORD ScanLR(lpDestDev, X, Y, dwPhysColor, Style)
    LPPDEVICE lpDestDev;
    WORD X;
    WORD Y;
    PCOLOR dwPhysColor;
    WORD Style;

The ScanLR function scans the display surface horizontally from the given
pixel, looking for the first pixel having the given color or a pixel that
has any other color. The scan can be left or right. GDI calls this function
when an application calls the FloodFill or ExtFloodFill function (GDI.25 or
GDI.372).

A graphics driver must export the ScanLR function if it sets the
DT_RASDISPLAY value in the dpTechnology member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   X
   Specifies the x-coordinate of the starting pixel.

   Y
   Specifies the y-coordinate of the starting pixel.

   dwPhysColor
   Specifies a physical color value.

   Style
   Specifies the action to take. The parameter can be a combination of the
   following values.

    Value    Meaning
    -----------------------------------------------------------------------

    0x0001   Scans for a pixel with color matching the dwPhysColor
             parameter. If this value is not given, the function scans for
             a pixel with color that does not match.

    0x0002   Scans to the left. If this value is not specified, the
             function scans to the right.


Return Value

The return value is the x-coordinate of the first qualifying pixel.
Otherwise, it is -1 if no qualifying pixel is found. The return value is
0x8000 if the X or Y parameters specify coordinates that exceed the display
surface or bitmap boundaries.


Comments

The export ordinal for this function is 12.



SelectBitmap

    BOOL SelectBitmap(lpDevice, lpPrevBitmap, lpBitmap, fFlags)
    LPPDEVICE lpDevice;
    LPBITMAP lpPrevBitmap;
    LPBITMAP lpBitmap;
    DWORD fFlags;

The SelectBitmap function selects a bitmap into the specified device,
replacing the previous bitmap. If the driver supports device bitmaps, GDI
calls this function when an application calls the SelectObject function
(GDI.45) to select a bitmap.

A graphics device driver must export the SelectBitmap function if the
RC_DEVBITS value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the device for which the bitmap
   is to be selected.

   lpPrevBitmap
   Points to a PBITMAP structure specifying the previously selected device
   bitmap.

   lpBitmap
   Points to a PBITMAP structure specifying the device bitmap to select.

   fFlags
   Specifies the actions to take while selecting the bitmap. Support for
   this parameter is not currently implemented; the parameter must be zero.


Return Value

This function returns 1 if it is successful. Otherwise, it is zero.


Comments

The export ordinal for this function is 29.

The lpPrevBitmap and lpBitmap parameters may point to either main memory or
device bitmaps. The SelectBitmap function must determine the bitmap type
and carry out any device-specific operations to select or cancel the
selected device bitmaps.


See Also

BitmapBits, RealizeObject



SetAttribute

    WORD SetAttribute(lpDestDev, wStateNum, wIndex, wAttribute)
    LPPDEVICE lpDestDev;
    WORD wStateNum;
    WORD wIndex;
    WORD wAttribute;

The SetAttribute function sets an attribute for a specified device state.
GDI does not currently call the SetAttribute function.

A graphics driver must export a SetAttribute function if the
RC_GDI20_OUTPUT value is set in the dpRaster member of the GDIINFO
structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wStateNum
   Specifies the device state.

   wIndex
   Specifies which attribute to set.

   wAttribute
   Specifies the attribute value.


Return Value

The return value is zero.


Comments

The export ordinal of this function is 18.

Although GDI does not currently call the SetAttribute function, the
function should always return zero, but carry out no other function.



SetDIBitsToDevice

    WORD SetDIBitsToDevice(lpDestDev, X, Y, iScan, cScans,
                      lpClipRect, lpDrawMode, lpDIBits, lpBitmapInfo,
                      lpTranslate)
    LPPDEVICE lpDestDev;       /* points to device                       */
    WORD X;                    /* top left corner x-coordinate         */
    WORD Y;                    /* top left corner y-coordinate         */
    WORD iScan;                /* start scan line in the DIB buffer      */
    WORD cScans;               /* number of scans to copy                */
    LPRECT lpClipRect;         /* points to clip rectangle on screen     */
    LPDRAWMODE lpDrawMode;     /* points to drawing mode information     */
    LPSTR lpDIBits;            /* points to the DIB buffer               */
    LPBITMAPINFO lpBitmapInfo; /* points to bitmap information           */
    LPINT lpTranslate;         /* points to conversion-translation table */

The SetDIBitsToDevice function copies device-independent bitmap data
directly to the given device. The function converts the bitmap data to the
appropriate device-specific format and copies the resulting bits to the
device. GDI calls this function whenever an application calls the
SetDIBitsToDevice function (GDI.443).

A graphics device driver must export the SetDIBitsToDevice function if the
RC_DIBTODEV value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

   lpDestDev
   Points to a PDEVICE structure specifying the device to receive the
   device-independent bitmap.

   X
   Specifies the x-coordinate (in device units) to receive the top left
   corner of the device-independent bitmap.

   Y
   Specifies the y-coordinate (in device units) to receive the top left
   corner of the device-independent bitmap.

   iScan
   Specifies the starting scan line.

   cScans
   Specifies the number of scan lines to copy.

   lpClipRect
   Points to a RECT structure specifying the clip rectangle. The structure
   has the following form:

        typedef struct tagRECT {
            short left;
            short top;
            short right;
            short bottom;
        } RECT;
   lpDrawMode
   Points to a DRAWMODE structure specifying the background mode and
   background color to use while copying the bitmap. The structure has the
   following form:

        typedef struct tagDRAWMODE {
          short    Rop2;       /*binary-raster operations*/
          short    bkMode;     /*background mode*/
          PCOLOR   bkColor;    /*physical background color*/
          PCOLOR   TextColor;  /*physical text (foreground) color*/
          short    TBreakExtra;/*number of extra pixels to add to line*/
          short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
          short    BreakErr;   /*running error term*/
          short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
          short    BreakCount; /*number of breaks in the line*/
          short    CharExtra;  /*extra pixels for each character*/
          COLORREF LbkColor;   /*logical background color*/
          COLORREF LTextColor; /*logical text (foreground) color*/
        } DRAWMODE;
   lpDIBits
   Points to a buffer containing the device-independent bitmap bits.

   lpBitmapInfo
   Points to a BITMAPINFO structure specifying the dimensions and format of
   the device-independent bitmap. The structure has the following form:

        typedef struct tagBITMAPINFO {
            BITMAPINFOHEADER    bmiHeader;
            RGBQUAD             bmiColors[1];
        } BITMAPINFO;
   If the RLE_FORMAT_4 or RLE_FORMAT_8 values are set in the biCompression
   member, the bitmap is in run-length-encoded (RLE) format. In this case,
   the function must decode the data as it retrieves it from the buffer
   pointed to by the lpDIBits parameter.

   lpTranslate
   Points to an array of color-translation values for converting palette
   colors to actual device colors. This parameter is ignored by devices
   that do not use color palettes.


Return Value

The return value is the number of scan lines actually copied, if
successful. Otherwise, it is zero if there is an error or no scan lines are
copied.


Comments

The export ordinal for this function is 21.

The function removes the cursor before copying the bitmap bits to the
display device and restores the cursor after copying.


See Also

DeviceBitmapBits, StretchDIBits



SetPalette

    VOID SetPalette(nStartIndex, nNumEntries, lpPalette)
    WORD nStartIndex;
    WORD nNumEntries;
    LPRGBQUAD lpPalette;

The SetPalette function sets one or more entries in the hardware-color
palette to the specified colors.

A graphics driver must export the GetPalette function if the RC_PALETTE
value is set in the dpRaster member of the driver's GDIINFO structure.


Parameters

   nStartIndex
   Specifies a zero-based, color-palette index. The function copies color
   values to the corresponding hardware-palette entry and to subsequent
   entries up to the number specified by the nNumEntries parameter.

   nNumEntries
   Specifies the number of entries to set in the hardware palette.

   lpPalette
   Points to an array of RGBQUAD structures specifying the colors to which
   to set the hardware-palette entries.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 22.


See Also

GetPalette



SetPalTrans

    void SetPalTrans(lpIndexes)
    LPWORD lpIndexes;        /* points to array of indexes */

The SetPalTrans function copies the translation table pointed to by the
lpIndexes parameter and creates a corresponding inverse translation table.
The driver uses the translation tables for logical-to-physical, color-index
mapping.

A graphics driver must export the GetPalette function if the RC_PALETTE
value is set in the dpRaster member of the driver's GDIINFO structure.


Parameters

   lpIndexes
   Points to the array containing color indexes. The number of indexes in
   the array is specified by the dpPalColors member in the device's GDIINFO
   structure.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 24.

If lpIndexes is not NULL, SetPalTrans copies the translation table into its
own translation table and constructs an inverse of the table. The driver
uses the inverse table whenever GDI requests block transfers from the
screen to a memory bitmap. If lpIndexes is NULL, the function constructs
the identity table.


See Also

GetPalTrans



StrBlt

    DWORD StrBlt(lpDestDev, wDestXOrg, wDestYOrg, lpClipRect,
                 lpString, wCount, lpFontInfo, lpDrawMode,
                 lpTextXForm)
    LPPDEVICE lpDestDev;
    WORD wDestXOrg;
    WORD wDestYOrg;
    LPRECT lpClipRect;
    LPSZ lpString;
    int wCount;
    LPFONTINFO lpFontInfo;
    LPDRAWMODE lpDrawMode;
    LPTEXTXFORM lpTextXForm;

The StrBlt function writes text strings by converting characters in a
specified string into raster, vector, or outline glyphs and copying the
glyphs to the specified device or bitmap. Depending on the value of its
parameters, StrBlt also computes the x and y extents of the bounding
rectangle of the displayed string and clips the text to fit a given
clipping rectangle. GDI may call StrBlt if an application calls the TextOut
function (GDI.33), the ExtTextOut function (GDI.351), or the GetTextExtent
function (GDI.91).

The StrBlt function has been superseded by the ExtTextOut function. A
graphics device driver must export the StrBlt function only if the
RC_GDI20_OUTPUT value is not set in the dpRaster member of the driver's
GDIINFO structure or only if the driver is intended to be installed under
Windows version 1.x.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the device or bitmap
   to receive the text output.

   wDestXOrg
   Specifies the x-coordinate (in device units) of the starting point for
   the string.

   wDestYOrg
   Specifies the y-coordinate (in device units) of the starting point for
   the string.

   lpClipRect
   Points to a RECT structure specifying the clipping rectangle.

   lpString
   Points to a null-terminated character string specifying the characters
   to display.

   wCount
   Specifies what action the function is to take as well as the number of
   characters in the string. If the wCount parameter is positive, the
   function draws the characters in the string using the current font, text
   justification, escapement, rotation, applying the clipping rectangle,
   and other factors. If the function modifies the BreakErr member
   specified by the lpDrawMode parameter, it must restore the member to its
   original value.

   If wCount is negative, the function computes the x and y extents of the
   smallest rectangle that completely encloses the displayed string, but
   does not generate output. In this case, the absolute value of wCount
   specifies the number of characters in the string. The function uses the
   current font, text justification, and other factors to compute the
   bounding rectangle, but does not apply the clipping rectangle. The
   function updates the BreakErr member specified by lpDrawMode.

   lpFontInfo
   Points to a FONTINFO structure specifying the physical font to use.

   lpDrawMode
   Points to a DRAWMODE structure specifying the current text color,
   background mode, background color, text justification, and character
   spacing.

   lpTextXForm
   Points to a TEXTXFORM structure specifying additional information about
   the appearance of the characters when drawn.


Return Value

The return values are the x and y extents of the string's bounding
rectangle; the x extent is in the low-order 16 bits and the y extent in the
high-order 16 bits. If the x extent exceeds the maximum value for an extent
(0x7FFF), the function returns 0x7FFF in the low-order 16 bits and the
value of the wDestXorg parameter in the high-order 16 bits. The function
returns 0x80000000 if error occurred or no output was generated.


Comments

The export ordinal for this function is 11.

To ensure backward compatibility, many graphics device drivers provide both
StrBlt and ExtTextOut functions. In such cases, the StrBlt function does
nothing more than call ExtTextOut as in the following example:

    DWORD StrBlt(lpDestDev, wDestXOrg, wDestYOrg, lpClipRect,
                 lpString, wCount, lpFontInfo, lpDrawMode, lpTextXForm)
    LPPDEVICE lpDestDev;
    WORD wDestXOrg;
    WORD wDestYOrg;
    LPRECT lpClipRect;
    LPSZ lpString;
    int wCount;
    LPFONTINFO lpFontInfo;
    LPDRAWMODE lpDrawMode;
    LPTEXTXFORM lpTextXForm;
    {
        return ExtTextOut(lpDestDev, wDestXOrg, wDestYOrg, lpClipRect,
                     lpString, wCount, lpFontInfo, lpDrawMode,
                     lpTextXForm, (LPSHORT)NULL, (LPRECT)NULL, 0);
    }

See Also

ExtTextOut



StretchBlt

    WORD StretchBlt(lpDestDev, wDestX, wDestY, wDestXext, wDestYext,
                    lpSrcDev, wSrcX, wSrcY, wSrcXext, wSrcYext,
                    Rop3, lpPBrush, lpDrawMode, lpClip)
    LPPDEVICE lpDestDev;
    WORD wDestX;
    WORD wDestY;
    WORD wDestXext;
    WORD wDestYext;
    LPPDEVICE lpSrcDev;
    WORD wSrcX;
    WORD wSrcY;
    WORD wSrcXext;
    WORD wSrcYext;
    DWORD Rop3;
    LPBRUSH lpPBrush;
    LPDRAWMODE lpDrawMode;
    LPRECT lpClip;

The StretchBlt function transfers bits from a source-device rectangle to a
destination-device rectangle. The function stretches or compresses the
source bits to fit the destination rectangle. The transfer is controlled by
a ternary raster operation value that specifies how corresponding bits from
the source, destination, and pattern in a brush are combined to form the
final bits in the destination.

A graphics device driver must export the StretchBlt function if the
RC_STRETCHBLT value is set in the dpRaster member of the GDIINFO structure.


Parameters

   lpDestDev
   Points to a PDEVICE or PBITMAP structure specifying the destination
   device or bitmap.

   wDestX
   Specifies the x-coordinate of the upper-left corner of the destination
   rectangle.

   wDestY
   Specifies the y-coordinate of the upper-left corner of the destination
   rectangle.

   wDestXext
   Specifies the width (in device units) of the destination rectangle.

   wDestYext
   Specifies the height (in device units) of the destination rectangle.

   lpSrcDev
   Points to a PDEVICE or PBITMAP structure specifying the source device or
   bitmap.

   wSrcX
   Specifies the x-coordinate of the upper-left corner of the source
   rectangle.

   wSrcY
   Specifies the y-coordinate of the upper-left corner of the source
   rectangle.

   wSrcXext
   Specifies the width (in device units) of the source rectangle.

   wSrcYext
   Specifies the width (in device units) of the source rectangle.

   Rop3
   Specifies a ternary raster operation value. This value determines how
   StretchBlt combines corresponding pixels from the source, destination,
   and brush to produce the final pixels in the destination rectangle. The
   Rop3 parameter can be any one of 256 ternary raster-operation values;
   the following lists the most common values.

    Value                      Meaning
    -----------------------------------------------------------------------

    SRCCOPY (0x00CC0020)       Copies source bits to the destination
                               rectangle: Destination = Source.

    SRCPAINT (0x00EE0086)      Combines the source and destination bits
                               using the bitwise OR operator: Destination =
                               Source | Destination.

    SRCAND (0x008800C6)        Combines the source and destination bits
                               using the bitwise AND operator: Destination
                               = Source & Destination.

    SRCINVERT (0x00660046)     Combines the source and destination bits
                               using the bitwise exclusive OR operator:
                               Destination = Source ^ Destination.

    SRCERASE (0x00440328)      Combines the source and inverse of
                               destination bits using the bitwise AND
                               operator: Destination = Source & (~
                               Destination).

    NOTSRCCOPY (0x00330008)    Copies the inverse of the destination bits
                               to the destination rectangle: Destination =
                               ~ Destination.

    NOTSRCERASE (0x001100A6)   Combines the inverse of the source and
                               destination bits using the bitwise AND
                               operator: Destination = (~ Source) & (~
                               Destination).

    MERGECOPY (0x00C000CA)     Combines the source and brush bits using the
                               bitwise AND operator: Destination = Source &
                               Pattern.

    MERGEPAINT (0x00BB0226)    Combines the destination and inverse of the
                               source bits using the bitwise OR operator:
                               Destination = (~ Source) | Destination.

    PATCOPY (0x00F00021)       Copies the brush bits to the destination
                               rectangle: Destination = Pattern.

    PATPAINT (0x00FB0A09)      Combines the destination, pattern, and the
                               inverse of source bits using the bitwise OR
                               operator: Destination = (~ Source) | Pattern
                               | Destination.

    PATINVERT (0x005A0049)     Combines the pattern and destination bits
                               using using the bitwise exclusive OR
                               operator: Destination = Pattern ^
                               Destination.

    DSTINVERT (0x00550009)     Copies the inverse of the destination bits:
                               Destination = ~ Destination.

    BLACKNESS (0x00000042)     Set all destination bits to black.

    WHITENESS (0x00FF0062)     Set all bits to white.

   For more information about ternary raster operations and a complete list
   of values, see Appendix A, Binary and Ternary Raster-Operation Codes.

   lpPBrush
   Points to a PBRUSH structure specifying a physical brush. StretchBlt
   uses this brush only if Rop3 specifies a ternary-raster operation that
   requires the brush to be combined with source or destination or both.

   lpDrawMode
   Points to a DRAWMODE structure specifying the color information
   StretchBlt needs to determine patterned brush colors and to carry color
   conversions and transparent copy operations. The structure has the
   following form:

        typedef struct tagDRAWMODE {
          short    Rop2;       /*binary-raster operations*/
          short    bkMode;     /*background mode*/
          PCOLOR   bkColor;    /*physical background color*/
          PCOLOR   TextColor;  /*physical text (foreground) color*/
          short    TBreakExtra;/*number of extra pixels to add to line*/
          short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
          short    BreakErr;   /*running error term*/
          short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
          short    BreakCount; /*number of breaks in the line*/
          short    CharExtra;  /*extra pixels for each character*/
          COLORREF LbkColor;   /*logical background color*/
          COLORREF LTextColor; /*logical text (foreground) color*/
        } DRAWMODE;
   lpClip
   Points to a RECT structure specifying the clipping rectangle (in
   destination-device units).


Return Value

The return value is 1 if successful. Otherwise, it is zero if an error was
encountered or -1 if GDI should carry out the requested operation.


Comments

The export ordinal for this function is 27.

Graphics device drivers that support some StretchBlt operations, but not
others, can return -1 to direct GDI to carry out the unsupported
operations. This also applies to operations in which the StretchBlt mode
can affect the final output, such as when StretchBlt compresses a bitmap to
fit a rectangle in a monochrome bitmap. Although the StretchBlt function
must use the current bitmap-stretching mode when compressing or stretching
bitmaps, GDI does not make the current mode available to drivers. In such
cases, the function should assume that the current mode is COLORONCOLOR or
it should return -1 to direct GDI use the proper mode when compressing
bitmaps.

The lpDestDev and lpSrcDev parameters can specify the same device that is
transferring bits from one part of a device to another is a valid
operation. If the source and destination rectangle overlap, StretchBlt
transfers bits carefully so that the transfer does not inadvertently
overwrite source bits before they have been transferred to the destination.

The Rop3 parameter specifies whether bits from the source, destination, and
brush are used in the transfer. If the ternary raster operation specified
by Rop3 does not include the source, StretchBlt ignores the source bits. If
it does not include the destination, StretchBlt replaces the destination
bits without using them to form the final bits.

If Rop3 does not include the brush, StretchBlt ignores the brush. If Rop3
includes the brush, StretchBlt must determine whether the brush is solid or
patterned (that is, has an associated bitmap). If the brush has a bitmap,
StretchBlt must combine the corresponding bits of the bitmap with the
source and destination bits (as specified by the raster operation) to form
the final destination bits.

If the source and bitmap associated with the brush do not have the same
color format as the destination, StretchBlt must convert the source and
brush bitmap to the destination's color format before transferring bits.
StretchBlt uses the text (foreground) and background colors specified by
the lpDrawMode parameter to convert colors.

To convert a monochrome bitmap to a color bitmap, StretchBlt converts white
bits (1) to the background color and converts black bits (0) to the text
(foreground) color.

To convert a color bitmap to a monochrome bitmap, StretchBlt converts all
pixels that match the background color to white (1), and converts all other
pixels to black (0).

In some device drivers, StretchBlt must check the bkMode member of the
lpDrawMode parameter as well as the Rop3 parameter to determine how to
carry out the transfer. If the bkMode member specifies the background mode
TRANSPARENT1, StretchBlt must not transfer source and brush bits that have
the same color as the destination's background color (as specified by the
bkColor member of lpDrawMode). In other words, the corresponding
destination bits must be left unchanged. Other background modes do not
affect the transfer. Only device drivers that have set the C1_TRANSPARENT
value in the dpCaps1 member of the GDIINFO structure are required to check
the background mode.


See Also

BitBlt



StretchDIBits

    WORD StretchDIBits(lpPDevice, fGet, DestX, DestY, DestXE,
                      DestYE, SrcX, SrcY, SrcXE, SrcYE, lpBits,
                      lpBitmapInfo, lpTranslate, dwROP, lpPBrush,
                      lpDrawMode, lpClipRect)
    LPPDEVICE lpPDevice;                    /* specifies device or bitmap   */
    WORD fGet;                              /* 0 to set bits, 1 to get bits */
    WORD DestX;                   /* x-coord of upper-left corner of dest */
    WORD DestY;                   /* y-coord of upper-left corner of dest */
    WORD DestXE;                  /* width of destination bitmap            */
    WORD DestYE;                  /* height of destination bitmap           */
    WORD SrcX;                  /* x-coord of upper-left corner of source */
    WORD SrcY;                  /* y-coord of upper-left corner of source */
    WORD SrcXE;                 /* width of source bitmap                   */
    WORD SrcYE;                 /* height of source bitmap                  */
    LPSTR lpBits;               /* points to buffer with bitmap data        */
    LPBITMAPINFO lpBitmapInfo;  /* points to bitmap information             */
    LPINT lpTranslate;          /* points to color-palette map              */
    DWORD dwROP;                /* raster operation                         */
    LPBRUSH lpPBrush;           /* current brush                            */
    LPDRAWMODE lpDrawMode;      /* points to drawing mode                   */
    LPRECT lpClipRect;          /* points to clipping rectangle             */

The StretchDIBits function moves a source bitmap into a destination bitmap,
stretching or compressing the source bitmap as necessary to fit the
dimensions of the destination bitmap. The function either converts and
copies a device-independent bitmap to a given device or converts and copies
a device-specific bitmap to a device-independent bitmap. The fGet parameter
specifies whether the source bitmap is a device-independent bitmap or
device-specific bitmap. GDI calls this function whenever an application
calls the StretchDIBits function (GDI.439).

A graphics device driver must export the StretchDIBits function if the
RC_STRETCHDIB value is set in the dpRaster member of the driver's GDIINFO
structure.


Parameters

   lpPDevice
   Points to a PDEVICE or PBITMAP structure specifying a device or a
   device-specific bitmap.

   fGet
   Specifies whether to set or retrieve bitmap bits. If this parameter is
   zero, the function stretches or compresses the bitmap bits in the buffer
   pointed to by the lpBits parameter and copies them to the given device
   or bitmap. If this parameter is 1, the function retrieves bits from the
   device or bitmap.

   DestX
   Specifies the x-coordinate of the upper-left corner of destination
   bitmap.

   DestY
   Specifies the y-coordinate of the upper-left corner of destination
   bitmap.

   DestXE
   Specifies the width of the destination bitmap in pixels.

   DestYE
   Specifies the height of the destination bitmap in pixels. If this
   parameter is negative, the function must flip the bitmap, effectively
   displaying or printing it upside down. In this case, the height of the
   destination bitmap is the absolute value of the parameter.

   SrcX
   Specifies the x-coordinate of the upper-left corner of source bitmap.

   SrcY
   Specifies the y-coordinate of the upper-left corner of source bitmap.

   SrcXE
   Specifies the width of the source bitmap in pixels.

   SrcYE
   Specifies the height of the source bitmap in pixels.

   lpBits
   Points to the buffer that contains or receives the device-independent
   bitmap bits. If the fGet parameter is zero, the buffer must contains the
   bitmap bits to be copied to the device or device-specific bitmap. If
   fGet is 1, the buffer receives bitmap bits copied from the device or
   bitmap.

   lpBitmapInfo
   Points to a BITMAPINFO structure specifying the dimensions and format of
   the device-independent bitmap. The structure has the following form:

        typedef struct tagBITMAPINFO {
            BITMAPINFOHEADER    bmiHeader;
            RGBQUAD             bmiColors[1];
        } BITMAPINFO;
   lpTranslate
   Points to an array of color translation values for converting palette
   colors to actual device colors. This parameter is ignored by devices
   that do not use color palettes.

   dwRop
   Specifies the raster operation to use during stretching and compressing.
   The dwRop parameter can be any one of 256 ternary raster-operation
   values; the following lists the most common values.

    Value                      Meaning
    -----------------------------------------------------------------------

    SRCCOPY (0x00CC0020)       Copies source bits to the destination
                               rectangle: Destination = Source.

    SRCPAINT (0x00EE0086)      Combines the source and destination bits
                               using the bitwise OR operator: Destination =
                               Source | Destination.

    SRCAND (0x008800C6)        Combines the source and destination bits
                               using the bitwise AND operator: Destination
                               = Source & Destination.

    SRCINVERT (0x00660046)     Combines the source and destination bits
                               using the bitwise exclusive OR operator:
                               Destination = Source ^ Destination.

    SRCERASE (0x00440328)      Combines the source and inverse of
                               destination bits using the bitwise AND
                               operator: Destination = Source & (~
                               Destination).

    NOTSRCCOPY (0x00330008)    Copies the inverse of the destination bits
                               to the destination rectangle: Destination =
                               ~ Destination.

    NOTSRCERASE (0x001100A6)   Combines the inverse of the source and
                               destination bits using the bitwise AND
                               operator: Destination = (~ Source) & (~
                               Destination).

    MERGECOPY (0x00C000CA)     Combines the source and brush bits using the
                               bitwise AND operator: Destination = Source &
                               Pattern.

    MERGEPAINT (0x00BB0226)    Combines the destination and inverse of the
                               source bits using the bitwise OR operator:
                               Destination = (~ Source) | Destination.

    PATCOPY (0x00F00021)       Copies the brush bits to the destination
                               rectangle: Destination = Pattern.

    PATPAINT (0x00FB0A09)      Combines the destination, pattern, and the
                               inverse of source bits using the bitwise OR
                               operator: Destination = (~ Source) | Pattern
                               | Destination.

    PATINVERT (0x005A0049)     Combines the pattern and destination bits
                               using using the bitwise exclusive OR
                               operator: Destination = Pattern ^
                               Destination.

    DSTINVERT (0x00550009)     Copies the inverse of the destination bits:
                               Destination = ~ Destination.

    BLACKNESS (0x00000042)     Set all destination bits to black.

    WHITENESS (0x00FF0062)     Set all bits to white.

   For more information about ternary raster operations and a complete list
   of values, see Appendix A, Binary and Ternary Raster-Operation Codes.

   lpPBrush
   Points to a PBRUSH structure specifying the current brush. Depending on
   the specified raster operation, the brush may be used during the
   stretching or compressing of the bitmap.

   lpDrawMode
   Points to a DRAWMODE structure specifying the color information the
   function needs to determine patterned brush colors and to carry color
   conversions and transparent copy operations. The structure has the
   following form:

        typedef struct tagDRAWMODE {
          short    Rop2;       /*binary-raster operations*/
          short    bkMode;     /*background mode*/
          PCOLOR   bkColor;    /*physical background color*/
          PCOLOR   TextColor;  /*physical text (foreground) color*/
          short    TBreakExtra;/*number of extra pixels to add to line*/
          short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
          short    BreakErr;   /*running error term*/
          short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
          short    BreakCount; /*number of breaks in the line*/
          short    CharExtra;  /*extra pixels for each character*/
          COLORREF LbkColor;   /*logical background color*/
          COLORREF LTextColor; /*logical text (foreground) color*/
        } DRAWMODE;
   lpClipRect
   Points to a RECT structure specifying the clipping rectangle. The
   structure has the following form:

        typedef struct tagRECT {
            short left;
            short top;
            short right;
            short bottom;
        } RECT;

Return Value

The return value is the number of scan lines copied. Otherwise, it is zero
if the function encounters an error or no scan lines copied. The return
value is -1 if GDI needs to simulate the operation.


Comments

The export ordinal for this function is 28.

For Windows 3.x, the source bitmap will always be a DIB (with the fGet
parameter set to zero). The destination bitmap can be either a memory
bitmap or the actual device surface.


See Also

DeviceBitmapBits, SetDIBitsToDevice, StretchBlt



UpdateColors

    VOID UpdateColors(wStartX, wStartY, wExtX, wExtY, lpTranslate)
    WORD wStartX;           /* x-coordinate of upper-left corner */
    WORD wStartY;           /* y-coordinate of upper-left corner */
    WORD wExtX;             /* width in screen pixels */
    WORD wExtY;             /* height in screen pixels */
    LPWORD lpTranslate;     /* points to translation table */

The UpdateColors function redraws all pixels in a region on the display
surface using the colors specified in the given translation table. For each
pixel in the region, the function reads the pixel's color index, translates
the index, and writes the translated index back to the original position.

A graphics driver must export the GetPalette function if the RC_PALETTE bit
is set in the dpRaster member of the driver's GDIINFO structure.


Parameters

   wStartX
   Specifies the y-coordinate of the upper-left corner of the region to
   update.

   wStartY
   Specifies the y-coordinate of the upper-left corner of the region to
   update.

   wExtX
   Specifies the width of the rectangular region to update in pixels.

   wExtY
   Specifies the height of the rectangular region to update in pixels.

   lpTranslate
   Points to an array of color indexes.


Return Value

This function has no return value.


Comments

The export ordinal for this function is 26.

GDI assumes that the display origin is in the upper-left corner of the
screen.



WEP

    WORD WEP(bSystemExit)
    BOOL bSystemExit;

The WEP function carries out any termination actions the driver requires.
Windows calls the function to indicate that all parts of Windows is
shutting down or that the graphics driver is being unloaded from the
system.


Parameters

   bSystemExit
   Specifies whether the system is shutting down. If this parameter is
   TRUE, Windows is shutting down. Otherwise, Windows is unloading the
   drivers only.


Return Value

The return value is always 1.


Comments

This function must be exported by name.

Chapter 11  Graphics-Driver Escapes

The Microsoft Windows graphics escapes provide graphics support that is
otherwise not available through graphics-device interface (GDI).
Applications use graphics escapes to perform device-dependent operations
that are not supported by GDI. Applications call the Escape function
(GDI.38) to initiate an escape and GDI calls the device driver's Control
function to complete the escape.


11.1 About the Graphics-Driver Escapes

Graphics drivers should support all escapes that are reasonable for a given
device. In particular, printer drivers should be prepared applications that
assume that the printer-setting escapes, such as STARTDOC and ENDDOC, are
always available on high-end devices. All drivers should support the
QUERYESCSUPPORT escape which identifies which graphics escapes the driver
supports.

Display drivers should support the following escapes:

o   QUERYESCSUPPORT

o   GETCOLORTABLE

o   SETCOLORTABLE

Printer drivers should support at least the following escapes:

o   QUERYESCSUPPORT

o   SETABORTPROC

o   STARTDOC

o   NEWFRAME

o   ENDDOC

o   ABORTDOC

o   NEXTBAND


11.2 Obsolete Escapes

The EXTTEXTOUT and SELECTPAPERSOURCE escapes are now obsolete. EXTTEXTOUT
has been replaced by the ExtTextOut function, and SELECTPAPERSOURCE has
been superseded by the GETSETPAPERBINS escape.


11.3 Escape Reference

The following is an alphabetical listing of the graphics-driver escapes.

ABORTDOC

    #define ABORTDOC 2

    short Control(lpDevice, ABORTDOC, NULL, NULL)
    LPPDEVICE lpDevice;

The ABORTDOC escape cancels and deletes the job using the DeleteJob
function.

The ABORTDOC escape should be used for printing operations that do not
specify a stopping function with the SETABORTPROC escape, and to stop
printing operations that have not yet reached their first NEWFRAME or
NEXTBAND call.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

GDI calls this escape when a banding error occurs. It is also called by an
application when an error occurs or when the application wants to cancel
the print job.


See Also

DeleteJob, ENDDOC, NEWFRAME, NEXTBAND, SETABORTPROC



BANDINFO

    #define BANDINFO 24

    short Control(lpDevice, BANDINFO, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPBANDINFOSTRUCT lpInData;
    LPBANDINFOSTRUCT lpOutData;

The BANDINFO escape copies information about a device with banding
capabilities to a structure pointed at by the lpInData parameter.

Banding is a property of an output device that allows a page of output to
be stored in a metafile and divided into bands, each of which is sent to
the device to create a complete page. Use banding with devices that cannot
scroll backwards.

The information copied to the structure pointed at by lpInData includes a
flag indicating whether or not there are graphics in the next band, a flag
indicating whether or not there is text on the page, and a rectangle
structure that contains a bounding rectangle for all graphics on the page.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a BANDINFOSTRUCT structure containing information about the
   graphics band. The BANDINFOSTRUCT structure has the following form:

        typedef struct _BANDINFOSTRUCT {
            BOOL fGraphics;
            BOOL fText;
            RECT rcGraphics;
        } BANDINFOSTRUCT;
   lpOutData
   Points to a BANDINFOSTRUCT structure containing information about the
   graphics band.


Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0.


Comments

This escape should only be implemented for devices that use banding. It
should be called immediately after each call to the NEXTBAND escape. If the
lpOutData parameter is not NULL and graphics will be printed in the current
band, the driver will set the fGraphics member in the output structure. If
text will be printed, the fText member will be nonzero. The rcGraphics
member is not used for output.

Therefore, on the first band, the driver would set the rectangle returned
by NEXTBAND to the whole page. If it receives a BANDINFO escape, it will
set the fText member and clear fGraphics.

On subsequent bands, it will band the page in small rectangles and handle
only graphics calls. Additionally, if the application calls BANDINFO,
clears the fText member and sets fGraphics.

The application can also optimize the banding process somewhat by
describing the page with the structure passed by lpInData. The application
sets the fGraphics member, if there are any graphics on the page, and the
fText member if there is any text. If there are no graphics, the driver may
be able to skip the graphics bands. The application should also set
rcGraphics to the rectangle bounding all nontext graphics on the page. The
driver has the option of banding only the specified graphics rectangle
rather than the whole page.

Vector fonts complicate the process somewhat. Since vector devices using
banding generally cannot print vector fonts, these fonts are simulated
using polylines or scan lines. Therefore, they appear to the driver to be
graphics in the text band. Since vector fonts can appear anywhere on the
page and require graphics banding support, the driver must band graphics on
the whole page even if the BANDINFOSTRUCT passed by the application
specifies otherwise.

If the application never calls BANDINFO, the driver can decide whether or
not to band graphics by maintaining a flag that is set if any graphics
calls are seen during the text band.


See Also

NEXTBAND



BEGIN_PATH

    #define BEGIN_PATH 4096

    short Control(lpDevice, BEGIN_PATH, NULL, NULL)
    LPPDEVICE lpDevice;

The BEGIN_PATH escape opens a path. A path is a connected sequence of
primitives drawn in succession to form a single polyline or polygon. Paths
enable applications to draw complex borders, filled shapes, and clipping
areas by supplying a collection of other primitives that define the desired
shape.

Printer escapes that support paths enable applications to render images on
sophisticated devices such as PostScript printers without generating huge
polygons to simulate them.

To draw a path, an application first issues the BEGIN_PATH escape. It then
draws the primitives defining the border of the desired shape, and issues
an END_PATH and EXT_DEVICE_CAPS escape. The END_PATH escape includes a
parameter specifying how the path is to be rendered.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is a short integer value specifying the current path
nesting level. If the escape is successful, the number of BEGIN_PATH calls
without a corresponding END_PATH call is the result. Otherwise, the result
is zero.


Comments

You may open a path within another path. A path drawn within another path
is treated exactly like a polygon (if the subpath is closed) or a polyline
(if the subpath is open).

You may use the CLIP_TO_PATH escape to define a clipping area corresponding
to the interior or exterior of the currently open path.

Device drivers that implement this escape must also implement the END_PATH
and EXT_DEVICE_CAPS escapes and should also implement the SET_ARC_DIRECTION
escape.


See Also

CLIP_TO_PATH, END_PATH, EXT_DEVICE_CAPS, SET_ARC_DIRECTION



CLIP_TO_PATH

    #define CLIP_TO_PATH 4097

    short Control(lpDevice, CLIP_TO_PATH, lpClipMode, NULL)
    LPPDEVICE lpDevice;
    LPINT lpClipMode;

The CLIP_TO_PATH escape defines a clipping area bounded by the currently
open path. It enables the application to save and restore the current
clipping area and to set up an inclusive or exclusive clipping area bounded
by the currently open path.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpClipMode
   Points to a 32-bit variable specifying the clipping mode. It may be one
   of the following values.

    Value               Meaning
    -----------------------------------------------------------------------

    CLIP_SAVE(0)        Saves the current clipping area.

    CLIP_RESTORE(1)     Restores the previous clipping area.

    CLIP_INCLUSIVE(2)   Sets a clipping area in such a way that portions of
                        primitives falling outside the interior bounded by
                        the current path are clipped.

    CLIP_EXCLUSIVE(3)   Sets a clipping area in such a way that portions of
                        primitives falling inside the interior bounded by
                        the current path should be clipped.

   The high-order 16 bits specifies the interior mode. It may be either
   ALTERNATIVE or WINDING.


Return Value

The return value is a nonzero value if the escape is successful. Otherwise,
the return value is zero.


Comments

Device drivers implementing the CLIP_TO_PATH escape must also implement the
BEGIN_PATH, END_PATH, and EXT_DEVICE_CAPS escapes. Device drivers should
also implement the SET_ARC_DIRECTION escape if they support elliptical
arcs.


See Also

BEGIN_PATH, END_PATH, EXT_DEVICE_CAPS, SET_ARC_DIRECTION



DRAFTMODE

    #define DRAFTMODE 7

    short Control(lpDevice, DRAFTMODE, lpDraftMode, NULL)
    LPPDEVICE lpDevice;
    LPINT lpDraftMode;

The DRAFTMODE escape turns draft mode off or on. Turning draft mode on
instructs the device driver to print faster and with lower quality (if
necessary). The draft mode can only be changed at page boundaries, for
example, after a NEWFRAME escape.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpDraftMode
   Points to a 16-bit variable containing a value specifying the draft
   mode. If it is 1, the escape turns on draft mode; if 0, the escape turns
   off draft mode.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

The default draft mode is off.


See Also

NEWFRAME



DRAWPATTERNRECT

    #define DRAWPATTERNRECT 25

    short Control(lpDevice, DRAWPATTERNRECT, lpInData, NULL)
    LPPDEVICE lpDevice;
    LPPOINT lpInData;

The DRAWPATTERNRECT escape creates a pattern, gray scale, or solid black
rectangle using the pattern or rule capabilities of PCL printers. With the
Hewlett-Packard LaserJet IIP, this escape can also create a solid white
rectangle. A gray scale is a gray pattern that contains a specific mixture
of black and white pixels. A PCL printer is an HP LaserJet or
LaserJet-compatible printer.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a PATTERNRECT structure containing information about the
   rectangle to create. The structure has the following form:

        typedef struct tagPATTERNRECT {
            POINT prPosition;
            POINT prSize;
            WORD prStyle;
            WORD prPattern;
        } PATTERNRECT;

Return Value

The return value is nonzero if the escape is successful. Otherwise, it is
zero.


Comments

An application should use the QUERYESCSUPPORT escape to determine whether a
device is capable of drawing patterns and rules before implementing this
escape. If a printer is capable of outputting a white rule, the return
value for QUERYESCSUPPORT is 2.

The effect of a white rule is to erase any text or other pattern rules
already written in the specified area.

The driver sends all text and rules in the first band before any GDI bitmap
graphics are sent. Therefore, it is not possible to erase bitmap graphics
with white rules.

If an application uses the BANDINFO escape, the drive should send all
patterns and rectangles specified by the DRAWPATTERNRECT escape in the
first band.

Patterns and rules created with this escape may not be erased by placing
opaque objects over them unless you have white rule capability. An
application should use the function calls provided in GDI to obtain this
effect.


See Also

BANDINFO, QUERYESCSUPPORT



ENABLEDUPLEX

    #define ENABLEDUPLEX 28

    short Control(lpDevice, ENABLEDUPLEX, lpInData, NULL)
    LPPDEVICE lpDevice;
    LPWORD lpInData;

The ENABLEDUPLEX escape enables the duplex printing capability of a
printer. A device that has duplex printing capability is able to print on
both sides of the output medium.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that contains one of the following values.

    Value   Meaning
    -----------------------------------------------------------------------

    0       Simplex

    1       Duplex with vertical binding

    2       Duplex with horizontal binding


Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0.


Comments

An application should use the QUERYESCSUPPORT escape to determine whether
or not an output device is capable of creating duplex output. If
QUERYESCSUPPORT returns a nonzero value, the application should send the
ENABLEDUPLEX escape even if simplex printing is desired. This guarantees
the overriding of any values set in the driver-specific dialog. If duplex
printing is enabled and an uneven number of NEWFRAME escapes is sent to the
driver prior to the ENDDOC escape, the driver will add one page eject
before ending the print job.


See Also

ENDDOC, NEWFRAME, QUERYESCSUPPORT



ENABLEPAIRKERNING

    #define ENABLEPAIRKERNING 769

    short Control(lpDevice, ENABLEPAIRKERNING, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPINT lpOutData;

The ENABLEPAIRKERNING escape enables or disables the driver's ability to
automatically kern character pairs. When it is enabled, the driver
automatically kerns those pairs of characters that are listed in the font's
character-pair kerning table. The driver reflects this kerning both in the
printer and in calls to the GetTextExtent (GDI.91) function.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies whether to enable or disable
   automatic pair kerning. If it is 1, kerning is enabled; if 0, kerning is
   disabled.

   lpOutData
   Points to a 16-bit variable variable that receives the previous
   automatic pair-kerning member.


Return Value

The return value is 1 if the escape is successful. Otherwise, the return
value is 0 if not successful, or if the escape is not implemented.


Comments

The default state of this capability is zero; that is, automatic
character-pair kerning is disabled.

A driver does not have to support this escape just because it supplies the
character-pair kerning table to the application through the
GETPAIRKERNTABLE escape. When the GETPAIRKERNTABLE escape is supported but
the ENABLEPAIRKERNING escape is not, it is the application's responsibility
to properly space the kerned characters on the output device.


See Also

GETPAIRKERNTABLE



ENABLERELATIVEWIDTHS

    #define ENABLERELATIVEWIDTHS 768

    short Control(lpDevice, ENABLERELATIVEWIDTHS, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPINT lpOutData;

The ENABLERELATIVEWIDTHS escape enables or disables relative character
widths. When it is disabled (the default setting), each character's width
can be expressed as an integer number of device units. This expression
guarantees that the extent of a string will equal the sum of the extents of
the characters that make up the string. Such behavior enables applications
to build an extent table manually using one-character calls to the
GetTextExtent (GDI.91) function. When it is enabled, the width of a string
may or may not equal the sum of the widths of the characters in the string.
Applications that enable this feature are expected to retrieve the font's
extent table and compute relatively-scaled string widths themselves.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies whether to enable or disable
   relative widths. If it is 1, relative widths are enabled; if 0, relative
   widths are disabled.

   lpOutData
   Points to a 16-bit variable that receives the previous relative
   character-width member.


Return Value

The return value is 1 if the escape is successful. Otherwise, the return
value is 0 if the escape is not successful, or if the escape is not
implemented.


Comments

The default state of this capability is zero; that is, relative character
widths are disabled.

Enabling this feature creates values that are specified as font units and
accepted and returned by the escapes described in this chapter to be
returned in the relative units of the font.

It is assumed that only linear scaling devices will be dealt with in a
relative mode. Nonlinear scaling devices should not implement this escape.



END_PATH

    #define END_PATH 4098

    short Control(lpDevice, END_PATH, lpInfo, NULL)
    LPPDEVICE lpDevice;
    LPPATH_INFO lpInfo;

The END_PATH escape ends a path. A path is a connected sequence of
primitives drawn in succession to form a single polyline or polygon. Paths
enable applications to draw complex borders, filled shapes, and clipping
areas by supplying a collection of other primitives defining the desired
shape.

Printer escapes that support paths enable applications to render images on
sophisticated devices such as PostScript printers without generating huge
polygons to simulate them.

To draw a path, an application first issues the BEGIN_PATH escape. It then
draws the primitives defining the border of the desired shape, and issues
an END_PATH escape.

The END_PATH escape takes a pointer to a structure as a parameter,
specifying the manner in which the path is to be rendered. The structure
specifies whether or not the path is to be drawn and whether or not it is
open or closed. Open paths define polylines, and closed paths define
polygons that can be filled.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInfo
   Points to a PATH_INFO structure. The PATH_INFO structure has the
   following form:

        typedef struct tagPATH_INFO {
            short     RenderMode;
            BYTE      FillMode;
            BYTE      BkMode;
            LPEN      Pen;
            LBRUSH    Brush;
            DWORD     BkColor;
        } PATH_INFO;

Return Value

This escape returns a short integer value specifying the current path
nesting level. If the escape is successful, the number of BEGIN_PATH calls
without a corresponding END_PATH call is the result. Otherwise, -1 is the
result.


Comments

You may draw a path within another path. A path drawn within another path
is treated exactly like a polygon (if the subpath is closed) or a polyline
(if the subpath is open).

You may use the CLIP_TO_PATH escape to define a clipping area corresponding
to the interior or exterior of the currently open path.

Device drivers that implement this escape must also implement the
BEGIN_PATH and EXT_DEVICE_CAPS escapes and should also implement the
SET_ARC_DIRECTION escape.


See Also

BEGIN_PATH, CLIP_TO_PATH, EXT_DEVICE_CAPS, SET_ARC_DIRECTION



ENDDOC

    #define ENDDOC 11

    short Control(lpDevice, ENDDOC, NULL, NULL)
    LPPDEVICE lpDevice;

The ENDDOC escape ends a print job that is started by a STARTDOC escape and
that is to be ended in a standard way, instead of stopping the job in the
middle of the process.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

When a printing error occurs, the ENDDOC escape should not be used to
terminate the printing operation.


See Also

STARTDOC



ENUMPAPERBINS

    #define ENUMPAPERBINS 31

    short Control(lpDevice, ENUMPAPERBINS, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPINT lpOutData;

The ENUMPAPERBINS escape retrieves attribute information about a specified
number of paper bins. The GETSETPAPERBINS escape retrieves the number of
bins available on a printer.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies the number of bins for which
   information is to be retrieved.

   lpOutData
   Points to a BINNAMES structure to which information about the paper bins
   is copied. The size of the structure depends on the number of bins for
   which information was requested. The BINNAMES structure has the
   following form:

        typedef struct tagBINNAMES {
            short BinList[CBINMAX];
            char PaperNames[CBINMAX][CCHBINNAME]
        } BINNAMES;

Return Value

It is 1 if the escape is successful. Otherwise, it is 0 if the escape is
not successful or not implemented.


See Also

GETSETPAPERBINS



ENUMPAPERMETRICS

    #define ENUMPAPERMETRICS 34

    short Control(lpDevice, ENUMPAPERMETRICS, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPRECT lpOutData;

The ENUMPAPERMETRICS escape either retrieves the number of paper types
supported by the driver, or fills an array of RECT structures with the
dimensions of each paper type.

The ExtDeviceMode function achieves the same results.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to an 16-bit variable that specifies what action to take. If the
   variable is zero, the escape returns the number of paper types. If zero,
   the escape fills an array of RECT structures with paper dimensions.

   lpOutData
   Points to an array of RECT structures that receive the coordinates of
   the imageable area of the page. The top-left corner of the rectangle
   specifies the page margins, and the bottom-right corner specifies the
   sum of the page margins and the width and height of the imageable area.
   The units are device coordinates. The orientation returned is always
   portrait.


Return Value

The return value is positive, if successful. Otherwise, it is zero if the
escape is not implemented, and negative if an error occurs.


Comments

The following example illustrates the required actions:

    #define ENUMPAPERMETRICS    34
    #define INFORM              0
    #define PERFORM             1

    int cPaperTypes = CPAPERTYPES;
    RECT arectPage[CPAPERTYPES] = { ... };

    short Control(lpDevice, wFunction, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    WORD wFunction;
    LPVOID lpInData;
    LPVOID lpOutData;
    {

        LPRECT arect;

        switch (wFunction) {

        case ENUMPAPERMETRICS:
            switch (*((LPINT)lpInData)) {
            case INFORM:
                return cPaperTypes;

            case PERFORM:
                arect = (LPRECT)lpOutData;
                for (i=0; i<cPaperTypes; arect++, i++)
                    CopyRect(arect, arectPage[i]);
                return cPaperTypes;

            default:
                return 0;
            }

            .
            .
            .
        }


See Also

ExtDeviceMode



EPSPRINTING

    #define EPSPRINTING 33

    short Control(lpDevice, EPSPRINTING, lpBool, NULL)
    LPPDEVICE lpDevice;
    LPBOOL lpBool;

The EPSPRINTING escape only controls the downloading of the control
portions of the PostScript prolog. It sets up the portrait versus landscape
orientation and leaves the printer in the default 72 dpi user space.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpBool
   Points to a 16-bit variable specifying whether to enable or disable
   encapsulated PostScript (EPS) printing. If it is TRUE, EPS printing is
   enabled. If FALSE, EPS printing is disabled.


Return Value

The return value is positive, if successful. Otherwise, it is zero if the
escape is not implemented, and negative if an error occurs.


Comments

This escape is used to suppress the output of the Windows PostScript header
control section, which is about 10K. If it is used, no GDI calls are
allowed.



EXT_DEVICE_CAPS

    #define EXT_DEVICE_CAPS 4099

    short Control(lpDevice, EXT_DEVICE_CAPS, lpIndex, lpCaps)
    LPPDEVICE lpDevice;
    LPINT lpIndex;
    LPLONG lpCaps;

The EXT_DEVICE_CAPS escape retrieves information about device-specific
capabilities. It serves as a supplement to the GetDeviceCaps (GDI.80)
function.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpIndex
   Points to a 16-bit variable specifying the index of the capability to be
   retrieved. It can be one of the following values.

    Value                    Meaning
    -----------------------------------------------------------------------

    R2_CAPS (1)              Specifies which of the 16-bit binary-raster
                             operations the device driver supports. A
                             unique bit is set for each supported raster
                             operation. For example, the following code
                             fragment sets the bit for support of the
                             R2_XORPEN raster operation:

                                                  Caps = Caps | (1<<R2_XORPEN);
                             For more information about the binary-raster
                             operations, see the DRAWMODE structure.

    PATTERN_CAPS (2)         Specifies the maximum dimensions of a pattern
                             brush bitmap. The low-order 16 bits of the
                             capability value contains the maximum width of
                             a pattern brush bitmap; the high-order 16 bits
                             contains the maximum height.

    PATH_CAPS (3)            Specifies whether the device is capable of
                             creating paths using alternate and winding
                             interiors, and whether the device can do
                             exclusive or inclusive clipping to path
                             interiors. The path capabilities is a
                             combination of two of the following:

                                                      PATH_ALTERNATE (1)
                                                      PATH_WINDING (2)
                                                      PATH_INCLUSIVE (3)
                                                      PATH_EXCLUSIVE (4)
    POLYGON_CAPS(4)          Specifies the maximum number of polygon points
                             supported by the device. The capability value
                             is an unsigned value specifying the maximum
                             number of points.

    PATTERN_COLOR_CAPS (5)   Specifies whether the device can convert
                             monochrome pattern bitmaps to color. The
                             capability value is one if the device can do
                             pattern bitmap color conversions and zero if
                             it cannot.

    R2_TEXT_CAPS (6)         Specifies whether the device is capable of
                             performing binary raster operations on text.
                             The low-order 16 bits of the capability value
                             specifies which raster operations are
                             supported on text. A bit is set for each
                             supported raster operation, as in the R2_CAPS
                             escape. The high-order 16 bits specifies to
                             which type of text the raster capabilities
                             apply. It can be a combination of the the
                             following values:

                                                      RASTER_TEXT (1)
                                                      DEVICE_TEXT (2)
                                                      VECTOR_TEXT (3)
    POLYMODE_CAPS (7)        Specifies the polygon modes supported by the
                             device driver. The capability value is
                             obtained by setting a bit in the corresponding
                             position for each polygon mode supported. For
                             example, if a device supports the
                             PM_POLYSCANLINE and PM_BEZIER polygon modes,
                             the capability value would be set as follows:

        Caps = Caps | (1<<PM_POLYSCANLINE) | (1<<PM_BEZIER);
   lpCaps
   Points to a 32-bit variable that receives the specified capability.


Return Value

The return value is a nonzero value if the specified extended capability is
supported. Otherwise, it is zero if the capability is not supported.


Comments

A device driver implementing this escape must not modify the value of the
32-bit integer described by the lpCaps parameter unless it returns a valid
value for the capability.


See Also

SET_POLY_MODE



FLUSHOUTPUT

    #define FLUSHOUTPUT 6

    short Control(lpDevice, FLUSHOUTPUT, NULL, NULL)
    LPPDEVICE lpDevice;

The FLUSHOUTPUT escape flushes output in the device's buffer.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

This escape is intended for banding printer drivers. When called, they
should reinitialize the banding bitmap (that is, eliminate anything in the
bitmap that is only partially drawn).



GETCOLORTABLE

    #define GETCOLORTABLE 5

    short Control(lpDevice, GETCOLORTABLE, lpIndex, lpColor)
    LPPDEVICE lpDevice;
    LPINT lpIndex;
    LPLONG lpColor;

The GETCOLORTABLE escape retrieves an RGB color-table entry and copies it
to the location specified by the lpColor parameter.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpIndex
   Points to a 16-bit a variable specifying the index of a color-table
   entry. Color-table indexes start at zero for the first table entry.

   lpColor
   Points to 32-bit variable that receives the RGB color value for the
   given entry.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


See Also

SETCOLORTABLE



GETEXTENDEDTEXTMETRICS

    #define GETEXTENDEDTEXTMETRICS 256

    short Control(lpDevice, GETEXTENDEDTEXTMETRICS, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPEXTTEXTDATA lpInData;
    LPEXTTEXTMETRIC lpOutData;

The GETEXTENDEDTEXTMETRICS escape fills the buffer pointed to by the
lpOutData parameter with the extended text metrics for the currently
selected font.


Parameters

   lpDevice
   A long pointer to a PDEVICE structure, which is the destination device
   bitmap.

   lpInData
   Points to a EXTTEXTDATA structure containing information The EXTTEXTDATA
   structure has the following form:

        typedef struct tagEXTTEXTDATA {
            short             nSize;
            LPAPPEXTTEXTDATA  lpInData;
            LPFONTINFO        lpFont;
            LPTEXTXFORM       lpXForm;
            LPDRAWMODE        lpDrawMode;
        } EXTTEXTDATA;
   lpOutData
   Points to a EXTTEXTMETRIC structure. The EXTTEXTMETRIC structure has the
   following form:

        typedef struct tagEXTTEXTMETRIC {
            short  etmSize;
            short  etmPointSize;
            short  etmOrientation;
            short  etmMasterHeight;
            short  etmMinScale;
            short  etmMaxScale;
            short  etmMasterUnits;
            short  etmCapHeight;
            short  etmXHeight;
            short  etmLowerCaseAscent;
            short  etmUpperCaseDescent;
            short  etmSlant;
            short  etmSuperScript;
            short  etmSubScript;
            short  etmSuperScriptSize;
            short  etmSubScriptSize;
            short  etmUnderlineOffset;
            short  etmUnderlineWidth;
            short  etmDoubleUpperUnderlineOffset;
            short  etmDoubleLowerUnderlineOffset;
            short  etmDoubleUpperUnderlineWidth;
            short  etmDoubleLowerUnderlineWidth;
            short  etmStrikeOutOffset;
            short  etmStrikeOutWidth;
            WORD   etmKernPairs;
            WORD   etmKernTracks;
        } EXTTEXTMETRIC;

Return Value

The return value is the number of bytes copied to the buffer pointed to by
the lpOutData parameter. This value will never exceed the size specified by
the etmSize member in the EXTTEXTMETRIC structure. Otherwise, the return
value is zero if the escape fails or is not implemented.


Comments

The values returned in many of the fields of the EXTTEXTMETRIC structure
are affected by whether relative character widths are enabled or disabled.


See Also

ENABLERELATIVEWIDTHS



GETEXTENTTABLE

    #define GETEXTENTTABLE 257

    short Control(lpDevice, GETEXTENTTABLE, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPBYTE lpInData;
    LPINT lpOutData;

The GETEXTENTTABLE escape returns the width (extent) of individual
characters from a group of consecutive characters in the selected font's
character set. The first and last character (from the group of consecutive
characters) are function arguments.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a CHARRANGE structure containing the character codes for the
   first and last characters in the range. The CHARRANGE structure has the
   following form:

        typedef struct tagCHARRANGE {
            BYTE chFirst;
            BYTE chLast;
        } CHARRANGE;
   lpOutData
   Points to an array of integer values. The size of the array must be at
   least one more than the difference between the chLast and chFirst
   members of the structure pointed to by the lpInData parameter.


Return Value

The return value is 1 if the escape is successful. Otherwise, the return
value is 0 if it is not successful, or if the escape is not implemented.


Comments

The values returned are affected by whether relative character widths are
enabled or disabled.


See Also

ENABLERELATIVEWIDTHS



GETFACENAME

    #define GETFACENAME 513

    short Control(lpDevice, GETFACENAME, NULL, lpFaceName)
    LPPDEVICE lpDevice;
    LPSTR lpFaceName;

The GETFACENAME escape gets the name of the current physical font.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpFaceName
   Points to the buffer that receives the name.


Return Value

The return value is positive if successful. It is zero if the escape is not
implemented, and negative if an error occurs.



GETPAIRKERNTABLE

    #define GETPAIRKERNTABLE 258

    short Control(lpDevice, GETPAIRKERNTABLE, NULL, lpOutData)
    LPPDEVICE lpDevice;
    LPKERNPAIR lpOutData;

The GETPAIRKERNTABLE escape fills the buffer pointed to by the lpOutData
parameter with the character pair-kerning table for the currently selected
font.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpOutData
   Points to an array of KERNPAIR structures. This array must be large
   enough to accommodate the font's entire character pair-kerning table.
   The number of character-kerning pairs in the font can be obtained from
   the EXTTEXTMETRIC structure which is returned by the
   GETEXTENDEDTEXTMETRICS escape. The KERNPAIR structure has the following
   form:

        typedef struct tagKERNPAIR {
            union {
                BYTE each [2];
                WORD both;
            } kpPair;
            short  kpKernAmount;
        } KERNPAIR;

Return Value

The return value is the number of KERNPAIR structures copied to the buffer.
Otherwise, the return value is zero if the font does not have kerning pairs
defined, the escape fails, or the escape is not implemented.


Comments

The values returned in the KERNPAIR structures are affected by whether
relative character widths are enabled or disabled.


See Also

ENABLERELATIVEWIDTHS



GETPHYSPAGESIZE

    #define GETPHYSPAGESIZE 12

    short Control(lpDevice, GETPHYSPAGESIZE, NULL, lpDimensions)
    LPPDEVICE lpDevice;
    LPPOINT lpDimensions;

The GETPHYSPAGESIZE escape retrieves the physical page size in device units
(that is, how many pixels wide by how many scan lines high) and copies it
to the location pointed to by the lpDimensions parameter.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpDimensions
   Points to a POINT structure that receives the physical page dimensions.
   The POINT structure has the following form:

        typedef struct tagPOINT {
            short   x;
            short   y;
        } POINT;

Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.



GETPRINTINGOFFSET

    #define GETPRINTINGOFFSET 13

    short Control(lpDevice, GETPRINTINGOFFSET, NULL, lpOffset)
    LPPDEVICE lpDevice;
    LPPOINT lpOffset;

The GETPRINTINGOFFSET escape retrieves the offset from location 0, 0 (the
upper-left corner of the physical page), which is the point at which the
actual printing or drawing begins.

This escape function is not generally useful for devices that allow the
user to set the origin by hand.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpOffset
   Points to a POINT structure that receives the horizontal and vertical
   coordinates (in device units) of the printing offset. The POINT
   structure has the following form:

        typedef struct tagPOINT {
            short   x;
            short   y;
        } POINT;

Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.



GETSCALINGFACTOR

    #define GETSCALINGFACTOR 14

    short Control(lpDevice, GETSCALINGFACTOR, NULL, lpFactors)
    LPPDEVICE lpDevice;
    LPPOINT lpFactors;

The GETSCALINGFACTOR escape retrieves the scaling factors for the x and y
axes of a printing device. For each scaling factor, the escape copies an
exponent of two to the location pointed to by the lpFactors parameter. For
example, the value three is copied to lpFactors for a scaling factor of
eight.

Scaling factors are used by printing devices that cannot provide the same
resolution as the device resolution. This escape communicates to GDI the
factor by which it needs to stretch bitmaps when sending them to the
printer.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpFactors
   Points to a POINT structure that receives the horizontal and vertical
   scaling factors in the x and y members, respectively. The POINT
   structure has the following form:

        typedef struct tagPOINT {
            short   x;
            short   y;
        } POINT;

Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.



GETSETPAPERBINS

    #define GETSETPAPERBINS 29

    short Control(lpDevice, GETSETPAPERBINS, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPBININFO lpInData;
    LPBININFO lpOutData;

The GETSETPAPERBINS escape retrieves the number of paper bins available on
a printer and sets the current paper bin.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a BININFO structure that specifies the new paper bin. This
   parameter may be set to NULL. The BININFO structure has the following
   form:

        typedef struct tagBININFO {
            short   BinNumber;
            short   NbrofBins;
            short   Reserved[4];
        } BININFO;
   lpOutData
   Points to a BININFO structure that receives information about the
   current or previous paper bin and the number of bins available. This
   parameter may be set to NULL.


Return Value

The return value is TRUE, if successful. Otherwise, it is FALSE.


Comments

If the lpInData parameter is NULL and the lpOutData parameter points to a
BININFO structure, the escape retrieves the number of bins and the number
of the current bin.

If both lpInData and lpOutData point to BININFO structures, the escape sets
the current bin to the number specified in the BinNumber member of the
structure pointed to by lpInData and retrieves the number of the previous
bin.

If lpInData points to a BININFO structure but lpOutData is NULL, the escape
sets the current bin to the number specified in the BinNumber member of the
structure pointed to by lpInData.

When setting the paper bin with GETSETPAPERBINS, the bin selected is set
for the current job by setting the bit 15 of the bin index. If this bit is
not set, the selected paper bin becomes the default for later print jobs,
and the current job's selection is unchanged. Setting bit 15 enables an
application to change bins in the middle of a printing job.



GETSETPAPERMETRICS

    #define GETSETPAPERMETRICS 35

    short Control(lpDevice, GETSETPAPERMETRICS, lpNewPaper, lpOrigPaper)
    LPPDEVICE lpDevice;
    LPRECT lpNewPaper;
    LPRECT lpOrigPaper;

The GETSETPAPERMETRICS escape sets the paper type according to the given
paper-metrics information. It also gets the current printer's paper-metrics
information. However, this escape is needed now only for backward
compatibility with earlier applications. The ExtDeviceMode function
achieves the same results.

This escape expects a RECT structure, representing the imageable area of
the physical page, and assumes the origin is in the upper-left corner.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpNewPaper
   Points to a RECT structure that contains the new imageable area. The
   RECT structure has the following form:

        typedef struct tagRECT {
            short left;
            short top;
            short right;
            short bottom;
        } RECT;
   The coordinates are measured in device units. The orientation is set to
   match this parameter.

   lpOrigPaper
   Points to a RECT structure that receives the original value.

   The coordinates are measured in device units.


Return Value

The return value is positive if successful. Otherwise, the return value is
zero if the escape is not implemented, and negative if an error occurs.


See Also

ExtDeviceMode



GETSETPRINTORIENT

    #define GETSETPRINTORIENT 30

    short Control(lpDevice, GETSETPRINTORIENT, lpInData, NULL)
    LPPDEVICE lpDevice;
    LPORIENT lpInData;

The GETSETPRINTORIENT escape returns or sets the current paper orientation.
However, this escape is needed now only for backward compatibility with
earlier applications. The ExtDeviceMode function achieves the same results.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to an ORIENT structure that specifies the new paper orientation.
   If this parameter is NULL, the GETSETPRINTORIENT escape returns the
   current paper orientation. The ORIENT structure has the following form:

        typedef struct tagORIENT {
            short Orientation;
            short Reserved[4];
        } ORIENT;

Return Value

The return value specifies the current orientation, if the lpInData
parameter is NULL. Otherwise, it is the previous orientation, or -1 if the
escape failed.


Comments

The new orientation will take effect for the next device context created
for the device on this port.


See Also

ExtDeviceMode



GETSETSCREENPARAMS

    short Escape(hdc, GETSETSCREENPARAMS, sizeof(SCREENPARAMS),
        lpInData, lpOutData)

The GETSETSCREENPARAMS printer escape retrieves or sets the current screen
information for rendering halftones.


Parameters

   hdc
   HDC Identifies the device context.

   lpInData
   SCREENPARAMS FAR * Points to a SCREENPARAMS structure that contains the
   new screen information. For more information about this structure, see
   the following Comments section. This parameter may be NULL.

   lpOutData
   SCREENPARAMS FAR * Points to a SCREENPARAMS structure that retrieves the
   previous screen information. For more information about this structure,
   see the following Comments section. This parameter may be NULL.


Return Value

The return value specifies the outcome of the escape. This value is
positive if the escape is successful. Otherwise, it is negative.


Comments

This escape affects how device-independent bitmaps (DIBs) are rendered and
how color objects are filled.

The SCREENPARAMS structure has the following form:

    typedef struct tagSCREENPARAMS {
      int   angle;
      int   frequency;
    } SCREENPARAMS;
Following are the members of the SCREENPARAMS structure:

   angle
   Specifies, in degrees, the angle of the halftone screen.

   frequency
   Specifies, in dots per inch, the screen frequency.



GETTECHNOLOGY

    #define GETTECHNOLOGY 20

    short Control(lpDevice, GETTECHNOLOGY, NULL, lpTechnology)
    LPPDEVICE lpDevice;
    LPSTR lpTechnology;

The GETTECHNOLOGY escape retrieves the general technology type for a
printer. This allows an application to perform technology-specific actions.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpTechnology
   Points to a buffer to which the driver copies a null-terminated string
   containing the printer technology type, such as PostScript.


Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0 if
the escape is not successful or not implemented.



GETTRACKKERNTABLE

    #define GETTRACKKERNTABLE 259

    short Control(lpDevice, GETTRACKKERNTABLE, NULL, lpOutData)
    LPPDEVICE lpDevice;
    LPKERNTRACK lpOutData;

The GETTRACKKERNTABLE escape fills the buffer pointed to by the lpOutData
parameter with the track-kerning table for the currently selected font.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpOutData
   Points to an array of KERNTRACK structures. This array must be large
   enough to accommodate all the font's kerning tracks. The number of
   tracks in the font can be obtained from the EXTTEXTMETRIC structure
   returned by the GETEXTENDEDTEXTMETRICS escape. If lpOutData is NULL,
   GETTRACKKERNTABLE returns the number of table entries. The KERNTRACK
   structure has the following form:

        typedef struct tagKERNTRACK {
            short ktDegree;
            short ktMinSize;
            short ktMinAmount;
            short ktMaxSize;
            short ktMaxAmount;
        } KERNTRACK;

Return Value

The return value is the number of KERNTRACK structures copied to the
buffer. The return value is zero if the font does not have kerning tracks
defined, if the function fails, or if the escape is not implemented.


Comments

The values returned in the KERNTRACK structures are affected by whether
relative character widths are enabled or disabled.


See Also

ENABLERELATIVEWIDTHS, GETEXTENDEDTEXTMETRICS



GETVECTORBRUSHSIZE

    #define GETVECTORBRUSHSIZE 27

    short Control(lpDevice, GETVECTORBRUSHSIZE, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPLBRUSH lpInData;
    LPPOINT lpOutData;

The GETVECTORBRUSHSIZE escape retrieves the size in device units of a
plotter pen used to fill closed figures. GDI uses this information to
prevent the filling of closed figures (for example, rectangles and
ellipses) from overwriting the borders of the figure.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a LBRUSH structure that specifies the brush for which data is
   to be returned. The LBRUSH structure has the following form:

        typedef struct tagLBRUSH {
            short  lbStyle;
            long   lbColor;
            short  lbHatch;
            long   lbBkColor;
        } LBRUSH;
   lpOutData
   Points to a POINT structure that receives the width of the pen in device
   units. The escape copies the width to the y member. The POINT structure
   has the following form:

        typedef struct tagPOINT {
            short   x;
            short   y;
        } POINT;

Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0 if
the escape is not successful or not implemented.



GETVECTORPENSIZE

    #define GETVECTORPENSIZE 26

    short Control(lpDevice, GETVECTORPENSIZE, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPPEN lpInData;
    LPPOINT lpOutData;

The GETVECTORPENSIZE escape retrieves the size in device units of a plotter
pen. GDI uses this information to prevent hatched brush patterns from
overwriting the border of a closed figure.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a LPEN structure that specifies the pen for which the width is
   to be retrieved. The LPEN structure has the following form:

        typedef struct tagLPEN {
            long  lopnStyle;
            POINT lopnWidth;
            long  lopnColor;
        } LPEN;
   lpOutData
   Points to a POINT structure that receives the pen width in device units.
   The escape copies the pen width to the y member. The POINT structure has
   the following form:

        typedef struct tagPOINT {
            short   x;
            short   y;
        } POINT;

Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0 if
the escape is not successful or not implemented.



NEWFRAME

    #define NEWFRAME 1

    short Control(lpDevice, NEWFRAME, NULL, NULL)
    LPPDEVICE lpDevice;

The NEWFRAME escape informs the device that the application has finished
writing to a page. This escape is used typically with a printer to direct
the device driver to advance to a new page by performing a page-break
algorithm or form feed.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
one of the following values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.



NEXTBAND

    #define NEXTBAND 3

    short Control(lpDevice, NEXTBAND, lpInData, lpBandRect)
    LPPDEVICE lpDevice;
    LPPOINT lpInData;
    LPRECT lpBandRect;

The NEXTBAND escape informs the device driver that the application has
finished writing to a band. The device driver then sends the band to the
printer and returns the coordinates of the next band.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a POINT structure that receives the horizontal and vertical
   scaling factors in the x and y members respectively. The POINT structure
   has the following form:

                       typedef struct tagPOINT {
                           short   x;
                           short   y;
                       } POINT;
   The shift count in the POINT structure pointed to by the lpInData
   parameter is used for devices such as laser printers that support
   graphics at a lower resolution than text.

   lpBandRect
   Points to a RECT structure that receives the next band coordinates. The
   device driver copies the device coordinates of the next band into this
   structure.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
one of the following values.

Value                 Meaning
---------------------------------------------------------------------------

SP_ERROR (-1)         A general error condition or general error in banding
                      occurred.

SP_APPABORT (-2)      The job was stopped because the application's
                      callback function returned FALSE (0).

SP_USERABORT (-3)     The user stopped the print job by choosing the Delete
                      button from Print Manager.

SP_OUTOFDISK (-4)     A lack of disk space caused the job to stop. There is
                      not enough disk space to create or extend the Print
                      Manager temporary file.

SP_OUTOFMEMORY (-5)   A lack of memory caused the job to stop.



PASSTHROUGH

    #define PASSTHROUGH 19

    short Control(lpDevice,  PASSTHROUGH,  lpInData,  NULL)
    LPPDEVICE lpDevice;
    LPWORD lpInData;

The PASSTHROUGH escape enables the application to send data directly to the
printer, bypassing the standard printer-driver code.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a buffer in which the first 16 bits specifies the number of
   remaining bytes in the buffer. The escape sends the remaining bytes in
   the buffer to the printer.


Return Value

The return value is the number of bytes transferred to the printer if the
escape is successful. Otherwise, the return value is zero if the escape is
not successful, or if the escape is not implemented. If the return value is
nonzero but less than the size of the data, an error prohibited
transmission of the entire data block.


Comments

There may be restrictions on the kinds of device data an application may
send to the device without interfering with the operation of the driver
should not send commands that reset the printer or print the current page.
Additionally, applications are strongly discouraged from performing
functions that consume printer memory, such as downloading a font or a
macro.

The driver should invalidate its internal state variables such as current
position and current line style when carrying out this escape. The
application must be able to issue multiple, sequential PASSTHROUGH escapes
without intervening saves and restores being inserted by the driver.

This escape is also known as DEVICEDATA.



QUERYESCSUPPORT

    #define QUERYESCSUPPORT 8

    short Control(lpDevice, QUERYESCSUPPORT, lpEscNum, NULL)
    LPPDEVICE lpDevice;
    LPINT lpEscNum;

The QUERYESCSUPPORT escape determines if a particular escape is implemented
by the device driver.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpEscNum
   Points to a 16-bit variable specifying the escape function to be
   checked.


Return Value

The return value is nonzero for implemented escapes. Otherwise, it is zero
for unimplemented escapes. All device drivers must return success if
queried about whether they support the QUERYESCSUPPORT escape.



RESETDEVICE

    #define RESETDEVICE 128

    short Control(lpDevice, RESETDEVICE, lpDeviceOld, NULL)
    LPPDEVICE lpDevice;
    LPPDEVICE lpDeviceOld;

The RESETDEVICE escape resets the device context by copying information
that is specific to the current print job from the original physical device
structure to the new one. GDI calls this escape whenever an application
calls the ResetDC function (GDI.376).

Printer drivers that can reset print-job options (such as orientation and
paper source) during a single print job must support the RESETDEVICE
escape.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the new physical device.

   lpDeviceOld
   Points to a PDEVICE structure containing the device-specific settings to
   be copied to the new physical device structure.


Return Value

The return value is TRUE if the function is successful. Otherwise, it is
FALSE.


Comments

The RESETDEVICE escape must copy all information required to continue the
current print job to the new physical device structure. This includes
information such as the print-job number and record of downloaded
resources, but does not include information about the environment (such as
orientation and paper source). GDI calls the Enable function to set the
environment for the new physical device structure before calling this
escape.

After the RESETDEVICE escape returns, GDI immediately calls the Disable
function with the old physical device structure. RESETDEVICE must ensure
that resources copied to the new physical device structure are not deleted
on the subsequent call to Disable. For example, if the Disable function
frees any working buffers allocated by the driver at the start of a print
job, RESETDEVICE must either allocate new buffers for the new physical
device structure or remove all pointers to these buffers from the old
physical device structure.


See Also

Disable, Enable



RESTORE_CTM

    #define RESTORE_CTM 4100

    short Control(lpDevice, RESTORE_CTM, NULL, NULL)
    LPPDEVICE lpDevice;

The RESTORE_CTM escape restores the current, previously saved
transformation matrix (CTM). The CTM controls the manner in which
coordinates are translated, rotated, and scaled by the device. By using
matrixes, you can combine these operations in any order to produce the
desired mapping for a particular picture.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is the number of SAVE_CTM escapes without a corresponding
RESTORE_CTM escape. The return value is -1 if the escape is unsuccessful.


Comments

Applications should not make any assumptions about the initial contents of
the CTM.

When a driver transforms a primitive using a transformation matrix modified
by the application, it should ignore the clipping rectangle specified by
GDI. Applications should specify the desired clipping rectangle using the
SET_CLIP_BOX escape.

Drivers supporting this escape must also implement the SET_CLIP_BOX,
SAVE_CTM, and TRANSFORM_CTM escapes.


See Also

SAVE_CTM, SET_CLIP_BOX, TRANSFORM_CTM



SAVE_CTM

    #define SAVE_CTM 4101

    short Control(lpDevice, SAVE_CTM, NULL, NULL)
    LPPDEVICE lpDevice;

The SAVE_CTM escape saves the current transformation matrix (CTM). The CTM
controls the manner in which coordinates are translated, rotated, and
scaled by the device. By using matrixes, you can combine these operations
in any order to produce the desired mapping for a particular image.

You can restore the matrix by using the RESTORE_CTM escape.

An application typically saves the CTM before changing it. This enables the
application to restore the previous state upon completion of a particular
operation.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.


Return Value

The return value is the number of SAVE_CTM escapes without a corresponding
RESTORE_CTM escape. The return value is zero if the escape is unsuccessful.


Comments

Applications should not make any assumptions about the initial contents of
the CTM and are expected to restore the contents of the CTM.

When a driver transforms a primitive using a transformation matrix modified
by the application, it should ignore the clipping rectangle specified by
GDI. Applications should specify the desired clipping rectangle using the
SET_CLIP_BOX escape.

Drivers supporting this escape must also implement the SET_CLIP_BOX,
RESTORE_CTM, and TRANSFORM_CTM escapes.


See Also

RESTORE_CTM, SET_CLIP_BOX, TRANSFORM_CTM



SET_ARC_DIRECTION

    #define SET_ARC_DIRECTION 4102

    short Control(lpDevice, SET_ARC_DIRECTION, lpDirection, NULL)
    LPPDEVICE lpDevice;
    LPINT lpDirection;

The SET_ARC_DIRECTION escape specifies the direction in which elliptical
arcs are drawn using the Arc (GDI.23) function.

By convention, elliptical arcs are drawn counterclockwise by GDI. This
escape enables an application to draw paths containing arcs drawn
clockwise.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpDirection
   Points to a 16-bit variable specifying the arc direction. It may be
   either COUNTERCLOCKWISE(0) or CLOCKWISE(1).


Return Value

The return value is the previous arc direction.


Comments

The default arc direction is COUNTERCLOCKWISE.

Device drivers that implement the BEGIN_PATH and END_PATH escapes should
also implement this escape.

This escape maps to the PostScript page-description language elements and
is intended for PostScript line devices.


See Also

BEGIN_PATH, END_PATH



SET_BACKGROUND_COLOR

    #define SET_BACKGROUND_COLOR 4103

    short Control(lpDevice, SET_BACKGROUND_COLOR, lpNewColor, lpOldColor)
    LPPDEVICE lpDevice;
    LPLONG lpNewColor;
    LPLONG lpOldColor;

The SET_BACKGROUND_COLOR escape enables an application to set and retrieve
the current background color for the device. The background color is the
color of the display surface before an application draws anything on the
device. This escape is particularly useful for color printers and film
recorders.

This escape should be sent before the application draws anything on the
current page.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpNewColor
   Points to a 32-bit variable specifying the desired background color.
   This parameter can be NULL if the application merely wants to retrieve
   the current background color.

   lpOldColor
   Points to a 32-bit variable that receives the previous background color.
   This parameter can be NULL if the application wants to ignore the
   previous background color.


Return Value

The return value is TRUE if the escape is successful. Otherwise, it is
FALSE.


Comments

The default background color is white.

The background color is reset to the default color when the device driver
receives an ENDDOC or ABORTDOC escape.


See Also

ABORTDOC, ENDDOC



SET_BOUNDS

    #define SET_BOUNDS 4109

    short Control(lpDevice, SET_BOUNDS, lpBounds, NULL)
    LPPDEVICE lpDevice;
    LPRECT lpBounds;

The SET_BOUNDS escape sets the bounding rectangle for the image being
output by the device driver when creating images in a file format such as
Encapsulated PostScript (EPS) and Hewlett-Packard Graphics Language (HPGL).


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpBounds
   Points to a RECT structure that specifies the bounds, in device
   coordinates, of the image to output.


Return Value

The return value is TRUE if successful. Otherwise, it is FALSE.


Comments

The application should issue this escape before each page. For single-page
jobs, this escape should be issued immediately after the STARTDOC escape.

When using coordinate transformation escapes, device drivers may not
perform bounding-box calculations correctly. Using this escape saves the
driver from the task of calculating the bounding box.


See Also

STARTDOC



SET_CLIP_BOX

    #define SET_CLIP_BOX 4108

    short Control(lpDevice, SET_CLIP_BOX, lpClipBox, NULL)
    LPPDEVICE lpDevice;
    LPRECT lpClipBox;

The SET_CLIP_BOX escape sets the clipping rectangle or restores the
previous clipping rectangle. The SET_CLIP_BOX escape is required of any
device driver that implements the coordinate transformation escapes.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpClipBox
   Points to a RECT structure that contains the bounding rectangle of the
   desired clipping area. If the lpClipBox parameter is not NULL, the
   previous clipping rectangle is saved, and the current clipping rectangle
   is set to the specified bounds. If lpClipBox is NULL, the previous
   clipping rectangle is restored.


Return Value

The return value is a Boolean value specifying whether or not the clipping
rectangle was properly set.


Comments

Drivers that implement the TRANSFORM_CTM, SAVE_CTM, and RESTORE_CTM escapes
must also implement this escape.

When an applications calls a GDI output function, GDI calculates a clipping
rectangle that bounds the primitive, and then passes both the primitive and
the clipping rectangle to the driver. The driver is expected to clip the
primitive to the specified bounding rectangle. However, when an application
uses the coordinate transformation escapes, the clipping rectangle that was
calculated by GDI is generally invalid.

The application can use the SET_CLIP_BOX escape to specify the correct
clipping rectangle when coordinate transformations are used.


See Also

RESTORE_CTM, SAVE_CTM, TRANSFORM_CTM



SET_POLY_MODE

    #define SET_POLY_MODE 4104

    short Control(lpDevice, SET_POLY_MODE, lpMode, NULL)
    LPPDEVICE lpDevice;
    LPINT lpMode;

The SET_POLY_MODE escape enables a device driver to draw shapes (such as
Bezier curves) that are not supported directly by GDI. This permits
applications that draw complex curves to send the curve description
directly to a device without having to simulate the curve as a polygon with
a large number of points.

The SET_POLY_MODE escape sets the poly mode for the device driver. The poly
mode is a state variable indicating how to interpret calls to the Polygon
(GDI.63) and Polyline (GDI.37) functions.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpMode
   Points to a 16-bit variable that specifies the desired poly mode. The
   parameter can be one of the following values.

                   Value                    Meaning
                   --------------------------------------------------------

                   PM_POLYLINE (1)          The points define a
                                            conventional polygon or
                                            polyline.

                   PM_BEZIER (2)            The points define a sequence of
                                            4-point Bezier spline curves.
                                            The first curve passes through
                                            the first four points, with the
                                            first and fourth points as end
                                            points, and the second and
                                            third points as control points.
                                            Each subsequent curve in the
                                            sequence has the end point of
                                            the previous curve as its start
                                            point, the next two points as
                                            control points, and the third
                                            as its end point.

                                            The last curve in the sequence
                                            is permitted to have fewer than
                                            four points. If the curve has
                                            only one point, it is
                                            considered a point. If it has
                                            two points, it is a line
                                            segment. If it has three
                                            points, it is a parabola
                                            defined by drawing a Bezier
                                            curve with the end points equal
                                            to the first and third points
                                            and the two control points
                                            equal to the second point.

                   PM_POLYLINESEGMENT (3)   The points specify a list of
                                            coordinate pairs. Line segments
                                            are drawn connecting each
                                            successive pair of points.

   The device driver need not support all the possible modes. It is
   expected to return zero if it does not support the specified mode.


Return Value

The return value is the previous poly mode if the escape is successful.
Otherwise, the return value is zero.


Comments

An application should issue the SET_POLY_MODE escape before it draws a
complex curve. It should then call Polyline or Polygon with the desired
control points defining the curve. After drawing the curve, the application
should reset the driver to its previous state by reissuing the
SET_POLY_MODE escape.

Calls to the Polyline function are drawn using the currently selected pen.

Calls to the Polygon function are drawn using the currently selected pen
and brush. If the start and end points are not equal, a line is drawn from
the start point to the end point before filling the polygon (or curve).

Calls to the Polygon function using PM_POLYLINESEGMENT mode are treated
exactly the same as calls to Polyline.

A Bezier curve is defined by four points. The curve is generated by
connecting the first and second, second and third, and third and fourth
points. The midpoints of these consecutive line segments are then
connected. Then the midpoints of the lines connecting the midpoints are
connected.

The line segments drawn in this way converge to a curve defined by the
following parametric equations, expressed as a function of an independent
variable t.

    X(t) = (1-t)**3x1 + 3(1-t)**2tx2 + 3(1-t)t**2x3 + t**3x4

    Y(t) = (1-t)**3y1 + 3(1-t)**2ty2 + 3(1-t)t**2y3 + t**3y4
The points (x1,y1), (x2,y2), (x3,y3), and (x4,y4) are the control points
defining the curve. The independent variable t varies from 0 to 1.

A second-degree Bezier curve may be expressed as a third-degree Bezier
using the following parameterization:

    Cx1 = 1/3X1 + 2/3X2    Cy1 = 1/3Y1 + 2/3Y2
    Cx2 = 2/3X2 + 1/3X3    Cy2 = 2/3Y2 + 1/3Y3
(Cx1, Cy1) and (Cx2, Cy2) are third-degree control points of the
second-degree Bezier specified by the points (x1, y1), (x2, y2), and (x3,
y3).

Applications are expected to check the return value from this escape to
determine whether or not the driver supports the specified poly mode.


See Also

Polygon, Polyline



SET_SCREEN_ANGLE

    #define SET_SCREEN_ANGLE 4105

    short Control(lpDevice, SET_SCREEN_ANGLE, lpAngle, NULL)
    LPPDEVICE lpDevice;
    LPINT lpAngle;

The SET_SCREEN_ANGLE escape sets the current screen angle to the desired
angle and enables an application to simulate the tilting of a photographic
mask in producing a separation for a particular primary color.

Four-color process separation is the process of separating the colors
comprising an image into four component primaries: cyan, magenta, yellow,
and black. The image is then reproduced by overprinting each primary. In
traditional four-color process printing, half-tone images for each of the
four primaries are photographed against a mask tilted to a particular
angle. Tilting the mask in this manner minimizes unwanted moire patterns
caused by overprinting two or more colors.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpAngle
   Points to a 16-bit variable specifying the desired screen angle in
   tenths of a degree. The angle is measured counterclockwise.


Return Value

This escape returns the previous screen angle.


Comments

The default screen angle is defined by the device driver.



SET_SPREAD

    #define SET_SPREAD 4106

    short Control(lpDevice, SET_SPREAD, lpSpread, NULL)
    LPPDEVICE lpDevice;
    LPINT lpSpread;

The SET_SPREAD escape sets the spread for spot-color separation. The spread
is the amount by which all the nonwhite primitives are expanded to provide
a slight overlap between primitives to compensate for imperfections in the
reproduction process.

Spot-color separation is the process of separating an image into each
distinct color used in the image. You then reproduce the image by
overprinting each successive color in the image. When reproducing a
spot-separated image, the printing equipment must be calibrated to align
each page exactly on each pass. However, differences between passes in such
factors as temperature and humidity often cause images to align imperfectly
on subsequent passes. For this reason, lines in spot separations are often
widened (spread) slightly to make up for problems in registering subsequent
passes through the printer. This process is called trapping.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpSpread
   Points to a 16-bit variable specifying the amount, in device units, by
   which all the nonwhite primitives are to be expanded.


Return Value

The return value is the previous spread.


Comments

The default spread is zero.

The current spread applies to all the bordered primitives (whether or not
the border is visible) and text.



SETABORTPROC

    #define SETABORTPROC 9

    short Control(lpDevice, SETABORTPROC, lphDC, NULL)
    LPPDEVICE lpDevice;
    LPHANDLE lphDC;

The SETABORTPROC escape sets the cancel function for the print job.

If an application wants to allow the print job to be cancelled during
spooling, it must set the cancel function before the print job is started
with the STARTDOC escape. Print Manager calls the cancel function during
spooling to allow the application to cancel the print job or to handle
out-of-disk-space conditions. If no cancel function is set, the print job
will fail if there is not enough disk space for spooling.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lphDC
   Points to a handle to the application's device context for the print
   job.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

The driver should pass the application's device context handle to the
OpenJob (GDI.240) function to allow GDI to call the application's callback
function.


See Also

STARTDOC



SETALLJUSTVALUES

    #define SETALLJUSTVALUES 771

    short Control(lpDevice, SETALLJUSTVALUES, lpInData, NULL)
    LPPDEVICE lpDevice;
    LPINT lpInData;

The SETALLJUSTVALUES escape sets all the text justification values that are
used for text output. Text justification is the process of inserting extra
pixels among break characters in a line of text. The space character is
normally used as a break character.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a JUST_VALUE_STRUCT structure that contains the justification
   values. The JUST_VALUE_STRUCT structure has the following form:

                       typedef struct tagJUST_VALUE_STRUCT {
                           short nCharExtra;
                           WORD  nCharCount;
                           short nBreakExtra;
                           WORD  nBreakCount;
                       } JUST_VALUE_STRUCT;

Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0.


Comments

The units used for the nCharExtra and nBreakExtra members in the
JUST_VALUE_STRUCT structure specify font units, and are dependent on
whether or not relative character widths were enabled with the
ENABLERELATIVEWIDTHS escape.

The values set with this escape will apply to subsequent calls to the
ExtTextOut function. The driver will stop distributing the nCharExtra
amount when it has output of nCharCount characters. It will also stop
distributing the space specified by nBreakExtra when it has output of
nBreakCount characters. A call on the same string to the GetTextExtent
(GDI.91) function, made immediately after the ExtTextOut function, is
processed in the same manner.

To reenable justification with the SetTextJustification (GDI.10) and
SetTextCharacterExtra (GDI.8) functions, an application should call
SETALLJUSTVALUES and set the members nCharExtra and nBreakExtra to zero.


See Also

ENABLERELATIVEWIDTHS, EXTTEXTMETRIC



SETCOLORTABLE

    #define SETCOLORTABLE 4

    short Control(lpDevice, SETCOLORTABLE, lpColorEntry, lpColor)
    LPPDEVICE lpDevice;
    LPWORD lpColorEntry;
    LPLONG lpColor;

The SETCOLORTABLE escape sets an RGB color-table entry. If the device
cannot supply the exact color, the function sets the entry to the closest
possible approximation of the color.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpColorEntry
   Points to a COLORTABLE_STRUCT structure. The COLORTABLE_STRUCT structure
   has the following form:

                       typedef struct tagCOLORTABLE_STRUCT {
                           WORD Index;
                           LONG rgb;
                       } COLORTABLE_STRUCT;
   lpColor
   Points to a 32-bit variable that receives the RGB color value selected
   by the device driver to represent the requested color value.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

A device's color table is a shared resource; changing the system display
color for one window changes it for all the windows.

The SETCOLORTABLE escape has no effect on devices with fixed-color tables.

This escape is intended for use by both printer and display drivers.
However, the EGA and VGA color drivers do not support it. It should not be
used with palette-capable display devices.

It is used by applications that want to change the palette used by the
display driver. However, since the driver's color-mapping algorithms will
probably no longer work with a different palette, an extension has been
added to this escape.

If the color index pointed to by the lpColorEntry parameter is 0xFFFFH, the
driver is to leave all color-mapping functionality to the calling
application. The application will necessarily know the proper color-mapping
algorithm and take responsibility for passing the correctly mapped physical
color to the driver (instead of the logical RGB color) in functions such as
RealizeObject and ColorInfo.

For example, if the device supports 256 colors with palette indexes of 0
through 255, the application would determine which index contains the color
that it wants to use in a certain brush. It would then pass this index in
the low byte of the logical color passed to RealizeObject. The driver would
then use this color exactly as passed instead of performing its usual
color-mapping algorithm. If the application wants to reactivate the
driver's color-mapping algorithm (that is, if it restores the original
palette when switching from its window context), then the color index
pointed to by lpColorEntry should be 0xFFFEH.


See Also

ColorInfo, GETCOLORTABLE, RealizeObject



SETCOPYCOUNT

    #define SETCOPYCOUNT 17

    short Control(lpDevice, SETCOPYCOUNT, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPINT lpOutData;

The SETCOPYCOUNT escape specifies the number of uncollated copies of each
page that the printer is to print.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable containing the number of uncollated copies
   to print.

   lpOutData
   Points to a 16-bit variable that receives the number of copies to print.
   This may be less than the number requested if the requested number is
   greater than the device's maximum copy count.


Return Value

The return value is 1 if the escape is successful. Otherwise it is 0 if it
is not, or if the escape is not implemented.



SETKERNTRACK

    #define SETKERNTRACK 770

    short Control(lpDevice, SETKERNTRACK, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPINT lpOutData;

The SETKERNTRACK escape specifies which kerning track a driver that
supports automatic-track kerning should use. A kerning track of zero
disables automatic-track kerning. When this escape is enabled, the driver
automatically kerns all characters according to the specified track. The
driver reflects this kerning both on the printer and in calls to the
GetTextExtent (GDI.91) function.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies the kerning track to use. A
   value of zero disables this feature. The etmKernTracks member in the
   EXTTEXTMETRIC structure for the driver specifies the maximum permitted
   value. Each permitted value corresponds to a position in the
   track-kerning table (using one as the first item in the table).

   lpOutData
   Points to a 16-bit variable that receives the previous kerning track.


Return Value

The return value is 1 if the escape is successful. Otherwise, it is 0 if it
is not, or if the escape is not implemented.


Comments

The default state is zero, which means that automatic-track kerning is
disabled.

A driver does not have to support this escape just because it supplies the
track-kerning table to the application using the GETTRACKKERNTABLE escape.
In the case where GETTRACKKERNTABLE is supported but SETKERNTRACK is not,
it is the application's responsibility to properly space the characters on
the output device.


See Also

GETEXTENDEDTEXTMETRICS, GETTRACKKERNTABLE



SETLINECAP

    #define SETLINECAP 21

    short Control(lpDevice, SETLINECAP, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPINT lpInData;
    LPINT lpOutData;

The SETLINECAP escape sets the line end cap. An end cap is that portion of
a line segment that appears on either end of the segment. The cap may be
square or circular; it can extend past, or remain flush with, the specified
end points.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies the end-cap type. The
   variable can contain one of the following values.

                   Value   Meaning
                   --------------------------------------------------------

                   -1      Line segments are drawn by using the default GDI
                           end cap.

                   0       Line segments are drawn with a squared end point
                           that does not project past the specified segment
                           length.

                   1       Line segments are drawn with a rounded end
                           point; the diameter of this semicircular arc is
                           equal to the line width.

                   2       Line segments are drawn with a squared end point
                           that projects past the specified segment length.
                           The projection is equal to half the line width.

   lpOutData
   Points to a 16-bit variable that receives the previous end-cap setting.


Return Value

The return value is positive if the escape is successful. Otherwise, it is
negative.


Comments

The interpretation of this escape varies with page-description languages
(PDLs). Consult your PDL documentation for its exact meaning.

This escape is also known as SETENDCAP.


See Also

SETLINEJOIN



SETLINEJOIN

    #define SETLINEJOIN 22

    short Control(lpDevice, SETLINEJOIN, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPWORD lpInData;
    LPWORD lpOutData;

The SETLINEJOIN escape specifies how to join two lines that meet at an
angle.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies the newline join type. If
   this parameter is NULL, the escape does not change the line join. The
   variable can contain one of the following values.

                   Value   Meaning
                   --------------------------------------------------------

                   0       Miter join. The outer edges of the strokes for
                           the two segments are extended until they meet at
                           an angle, as in a picture frame. If the segments
                           meet at too sharp of an angle, a bevel join is
                           used instead; this is controlled by the miter
                           limit established by the SETMITERLIMIT escape.

                   1       Round join. A circular arc with a diameter equal
                           to the line width is drawn around the point
                           where the segments meet, and is filled in,
                           producing a rounded corner. The stroke actually
                           draws a full circle at this point. If path
                           segments shorter than one-half the line width
                           meet at sharp angles, an unintentional wrong
                           side of this circle may appear.

                   2       Bevel join. The meeting path segments are
                           finished with butt-end caps (same as set by the
                           SETLINECAP escape); then, the resulting notch
                           beyond the ends of the segments is filled with a
                           triangle.

   lpOutData
   Points to a 16-bit variable that receives the previous line-join type.
   If this parameter is NULL, the escape does not return the previous
   line-join type.


Return Value

The return value is TRUE if the escape is successful. Otherwise, it is
FALSE.


Comments

Join styles are significant only at points at which consecutive segments of
a path connect at an angle. Curved lines are actually rendered as sequences
of straight line segments, and the current line join is applied to the
corners between those segments. However, for typical values of the flatness
parameter, the corners are so shallow that the difference between join
styles is not visible.


See Also

SETLINECAP, SETMITERLIMIT



SETMITERLIMIT

    #define SETMITERLIMIT 23

    short Control(lpDevice, SETMITERLIMIT, lpInData, lpOutData)
    LPPDEVICE lpDevice;
    LPWORD lpInData;
    LPWORD lpOutData;

The SETMITERLIMIT escape tells the driver how an application wants to clip
off miter-type line joins when they become too long. It sets the current
miter-limit parameter in the graphics state to a number greater than or
equal to one.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpInData
   Points to a 16-bit variable that specifies the miter-limit value. If
   this parameter is NULL, the escape does not change the miter-limit
   value.

   lpOutData
   Points to a 16-bit variable that receives the previous or current
   miter-limit value (if the lpInData parameter is NULL). If this parameter
   is NULL, the escape does not return to the previous limit.


Return Value

The return value is TRUE if the escape is successful. Otherwise, it is
FALSE.


Comments

The miter limit controls the stroke operator's treatment of corners when
miter joins have been specified. For more information about miter joins,
see the SETLINEJOIN escape.

When path segments connect at a sharp angle, a miter join results in a
spike that extends well beyond the connection point. The purpose of the
miter limit is to cut off such spikes when they become too long.

At any given corner, the miter length is the distance from the point at
which the inner edges of the strokes intersect to the point at which the
outside edges of the strokes intersect (that is, the diagonal length of the
miter). This distance increases as the angle between the segments
decreases. If the ratio of the miter length to the line width exceeds the
miter-limit parameter, the corner is treated with a bevel join instead of a
miter join.

The ratio of miter length to line width is directly related to the angle
alpha between the segments by the formula:

    miter-length / line-width = 1 / sin(alpha/2)
The following are examples of miter-limit values:

o   1.415 cuts off miters at angles less than 90 degrees, and converts them
    to bevels.

o   2.0 cuts off miters at angles less than 60 degrees.

o   10.0 cuts off miters at angles less than 11 degrees.

The default value of the miter limit is 10. Setting the miter limit to 1
cuts off miters at all angles so that bevels are always produced even when
miters are specified.


See Also

SETLINEJOIN



SETPRINTERDC

    #define SETPRINTERDC 9

    short Control(lpDevice, SETPRINTERDC, lphdc, NULL)
    LPPDEVICE lpDevice;
    LPHANDLE lphdc;

The SETPRINTERDC escape saves the given device context for use in a
subsequent call to the OpenJob function (GDI.240). GDI calls this escape
whenever an application calls the StartDoc function (GDI.377) or the
STARTDOC escape using the Escape function (GDI.38).

Printer drivers that call the OpenJob function to start a print job must
support the SETPRINTERDC escape.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the device.

   lphdc
   Points to a device context handle for the application starting the print
   job.


Return Value

The return value is TRUE if the escape is successful. Otherwise, it is
FALSE.


Comments

The SETPRINTERDC escape should save the device context handle in the
PDEVICE structure and use it when calling the OpenJob function as part of
processing the STARTDOC escape.


See Also

STARTDOC



STARTDOC

    #define STARTDOC 10

    short Control(lpDevice, STARTDOC, lpDocName, NULL)
    LPPDEVICE lpDevice;
    LPSTR lpDocName;

The STARTDOC escape informs the device driver that a new print job is
starting and that all subsequent NEWFRAME escapes should be spooled under
the same job, until an ENDDOC escape occurs.

This ensures that documents longer than one page will not be interspersed
with other jobs.


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpDocName
   Points to a null-terminated string specifying the name of the document.
   The document name is displayed in Print Manager.


Return Value

The return value is positive if successful. Otherwise, it is -1 if an error
occurs, such as insufficient memory or an invalid port specification.


See Also

ABORTDOC, ENDDOC, NEWFRAME



TRANSFORM_CTM

    #define TRANSFORM_CTM 4107

    short Control(lpDevice, TRANSFORM_CTM, lpMatrix, NULL)
    LPPDEVICE lpDevice;
    LPLONG lpMatrix;

The TRANSFORM_CTM escape modifies the current transformation matrix (CTM).
The CTM controls the manner in which coordinates are translated, rotated,
and scaled by the device. By using matrixes, you can combine these
operations in any order to produce the desired mapping for a particular
image.

The new current transformation matrix will contain the product of the
matrix referenced by the lpMatrix parameter and the previous CTM (CTM = M *
CTM).


Parameters

   lpDevice
   Points to a PDEVICE structure specifying the destination device.

   lpMatrix
   Points to a three-by-three array of 32-bit fixed values specifying the
   new transformation matrix.


Return Value

The return value is TRUE if the escape is successful. Otherwise, it is
FALSE.


Comments

Applications should not make any assumptions about the initial value of the
CTM.

When a driver transforms a primitive using a transformation matrix modified
by the application, it should ignore the clipping rectangle specified by
GDI. Applications should specify the desired clipping rectangle using the
SET_CLIP_BOX escape.

Drivers supporting this escape must also implement the SET_CLIP_BOX,
SAVE_CTM, and RESTORE_CTM escapes.


See Also

RESTORE_CTM, SET_CLIP_BOX, SAVE_CTM

Chapter 12  Graphics-Driver Types and Structures

This chapter describes the types and structures used by Microsoft Windows
graphics-driver functions and escapes.


12.1 Types

In addition to the standard C-language data types (such as char, int, long,
and void), the graphics functions and escapes use the following data types.

Type        Description
---------------------------------------------------------------------------

BOOL        Specifies a 16-bit Boolean value. Its value can be either TRUE
            or FALSE.

BYTE        Specifies an unsigned, 8-bit integer.

CHAR        Specifies an signed, 8-bit integer.

COLORREF    Specifies a 32-bit RGB color value or a logical color index.
            For RGB color values, the high-order byte is zero, and bytes 0,
            1, and 2 represent the intensity levels of blue, green, and
            red, respectively. For logical color indexes, the high-order
            byte is 0xFF, and the low-order, 16 bits represents the index.

DWORD       Specifies a unsigned, 32-bit integer.

FARPROC     Specifies a far pointer to a function that uses the Pascal
            calling convention.

FIXED       Specifies a fixed, real number in 32 bits. The high-order 16
            bits specifies the integer portion, and the low-order 16 bits
            specifies the fraction expressed as an integer value. To
            calculate the actual fraction value, divide the low-order 16
            bits by 65536.

HANDLE      Specifies a 16-bit handle representing objects such as pens,
            brushes, bitmaps, and global memory.

HWND        Specifies a 16-bit window handle.

INT         Specifies a signed, 16-bit integer.

LONG        Specifies a signed, 32-bit integer.

LPPDEVICE   Specifies a far pointer to a PDEVICE structure.

LPSTR       Specifies a far pointer to an array of bytes.

LPVOID      Specifies a far pointer to an undetermined type. Function
            parameters having this type must be cast to a specific far
            pointer type before being used.

PBRUSH      Specifies a integer, an array, or a structure containing
            device-specific information about a physical brush that a
            driver can use to fill figures and draw scan lines. The exact
            size and content of a PBRUSH type depends entirely on the
            driver.

PCOLOR      Specifies a 32-bit integer representing physical-color values.
            A physical color specifies a given color on the device. The
            range and meaning of physical color values depends entirely on
            the driver.

PPEN        Specifies an integer, array, or structure containing
            device-specific information that a driver can use to draw lines
            and borders. The exact size and content of a physical pen
            depend entirely on the driver.

SHORT       Specifies a signed, 16-bit integer.

VOID        Specifies an empty type. This type is typically used with
            functions that return no value.

WORD        Specifies an unsigned, 16-bit integer.

When LP prefix is applied to a data type, the resulting type specifies a
far pointer to a variable having the specified data type.


12.2 Structures

The following is an alphabetical listing of the structures used by the
graphics drivers and functions. All structures must be packed. This means
that you cannot align structure members on 16-bit boundaries by default.

BANDINFOSTRUCT

    typedef struct _BANDINFOSTRUCT {
        BOOL fGraphics;
        BOOL fText;
        RECT rcGraphics;
    } BANDINFOSTRUCT;
The BANDINFOSTRUCT structure, used by banding drivers, specifies whether
graphics and text are on the page.


Members

   fGraphics
   Specifies whether graphics are on the page. It is nonzero if graphics
   are on the page; zero if not.

   fText
   Specifies whether text is on the page. It is nonzero if text is on the
   page; zero if not.

   rcGraphics
   Specifies a RECT structure that contains the coordinates for the
   rectangle bounding all nontext graphics on the page.


Comments

A driver receives BANDINFOSTRUCT structures from applications that call the
BANDINFO escape. Information in the structure helps the driver optimize the
banding process. For example, if there are no graphics, the driver may be
able to skip the graphics bands. If the bounding rectangle for graphics is
smaller than the page, the driver has the option of banding only the
specified graphics rectangle rather than the whole page.


See Also

BANDINFO, NEXTBAND



BININFO

    typedef struct tagBININFO {
        short   BinNumber;
        short   NbrofBins;
        short   Reserved[4];
    } BININFO;
The BININFO structure contains information about a printer's paper bins.


Members

   BinNumber
   Identifies the current or previous paper bin.

   NbrofBins
   Specifies the number of paper bins available.

   Reserved
   Reserved; do not use.


See Also

GETSETPAPERBINS



BINNAMES

    typedef struct tagBINNAMES {
        short BinList[CBINMAX];
        char PaperNames[CBINMAX][CCHBINNAME]
    } BINNAMES;
The BINNAMES structure contains paper-bin identifiers and names. The
structure consists of two arrays: an array of 16-bit values specifying the
paper-bin identifiers, and an array of paper-bin names.


Members

   BinList
   Specifies an array of 16-bit values specifying the paper-bin
   identifiers. The number of elements in the array (CBINMAX) must be
   specified by the lpInData parameter of the ENUMPAPERBINS escape.

   PaperNames
   Specifies an array of null-terminated paper-bin names. The number of
   elements in the array (CBINMAX) must be specified by the lpInData
   parameter of the ENUMPAPERBINS escape. The maximum number of characters
   in each name (CCHBINNAME) is 24.


See Also

ENUMPAPERBINS



BITMAPINFO

    typedef struct tagBITMAPINFO {
        BITMAPINFOHEADER    bmiHeader;
        RGBQUAD             bmiColors[1];
    } BITMAPINFO;
The BITMAPINFO structure fully defines the dimensions and color information
for a Windows 3.x device-independent bitmap.


Members

   bmiHeader
   Specifies a BITMAPINFOHEADER structure that contains information about
   the dimensions and color format of a device-independent bitmap.

   bmiColors
   Specifies an array of RGBQUAD structures that define the colors in the
   bitmap.


Comments

A Windows 3.x device-independent bitmap consists of two distinct parts: a
BITMAPINFO data structure that describes the dimensions and colors of the
bitmap, and an array of bytes that define the pixels of the bitmap. The
bits in the array are packed together, but each scan line must be padded
with zeros to end on a 32-bit boundary. Segment boundaries can appear
anywhere in the bitmap, however. The origin of the bitmap is the lower-left
corner.

The biBitCount member of the BITMAPINFOHEADER structure determines the
number of bits which define each pixel and the maximum number of colors in
the bitmap. This member may be set to any of the following values.

Value   Meaning
---------------------------------------------------------------------------

1       The bitmap is monochrome, and the bmiColors member must contain two
        entries. Each bit in the bitmap array represents a pixel. If the
        bit is clear, the pixel is displayed with the color of the first
        entry in the bmiColors member; if the bit is set, the pixel has the
        color of the second entry in the table.

4       The bitmap has a maximum of 16 colors, and the bmiColors member
        contains up to 16 entries. Each pixel in the bitmap is represented
        by a 4-bit index into the color table.

        For example, if the first byte in the bitmap is 0x1F, then the byte
        represents two pixels. The first pixel contains the color in the
        second table entry, and the second pixel contains the color in the
        sixteenth table entry.

8       The bitmap has a maximum of 256 colors, and the bmiColors member
        contains up to 256 entries. In this case, each byte in the array
        represents a single pixel.

24      The bitmap has a maximum of 2**24 colors. The bmiColors member is
        NULL, and each three bytes in the bitmap array represents the
        relative intensities of blue, green, and red, respectively, of a
        pixel.

Alternatively, for functions that use device-independent bitmaps, the
bmiColors member can be an array of 16-bit unsigned integers that specify
an index into the currently realized, logical palette instead of explicit
RGB values. In this case, an application using the bitmap must call
device-independent bitmap functions with the wColorUse parameter set to
DIB_PAL_COLORS.


See Also

DeviceBitmapBits, SetDIBitsToDevice, StretchDIBits



BITMAPINFOHEADER

    typedef struct tagBITMAPINFOHEADER {    /* bmih */
        DWORD  biSize;
        DWORD  biWidth;
        DWORD  biHeight;
        WORD   biPlanes;
        WORD   biBitCount;
        DWORD  biCompression;
        DWORD  biSizeImage;
        DWORD  biXPelsPerMeter;
        DWORD  biYPelsPerMeter;
        DWORD  biClrUsed;
        DWORD  biClrImportant;
    } BITMAPINFOHEADER;
The BITMAPINFOHEADER structure contains information about the dimensions
and color format of a Windows 3.x device-independent bitmap.


Members

   biSize
   Specifies the number of bytes required by the BITMAPINFOHEADER
   structure.

   biWidth
   Specifies the width of the bitmap in pixels.

   biHeight
   Specifies the height of the bitmap in pixels.

   biPlanes
   Specifies the number of planes for the target device and must be set to
   1.

   biBitCount
   Specifies the number of bits per pixel. This value must be 1, 4, 8, or
   24.

   biCompression
   Specifies the type of compression for a compressed bitmap. It can be one
   of the following values.

     Value     Meaning
     ----------------------------------------------------------------------

     BI_RGB    Specifies that the bitmap is not compressed.

     BI_RLE8   Specifies a run-length encoded (RLE) format for bitmaps with
               8 bits per pixel. The compression format is a 2-byte format
               consisting of a count byte followed by a byte containing a
               color index.

     BI_RLE4   Specifies a run-length encoded format for bitmaps with 4
               bits per pixel. The compression format is a two-byte format
               consisting of a count byte followed by two word-length color
               indexes.

   biSizeImage
   Specifies the size in bytes of the image. It is valid to set this member
   to zero if the bitmap is in the BI_RGB format. The size must then be
   calculated explicitly.

   biXPelsPerMeter
   Specifies the horizontal resolution in pixels-per-meter of the target
   device for the bitmap. An application can use this value to select a
   bitmap from a resource group that best matches the characteristics of
   the current device.

   biYPelsPerMeter
   Specifies the vertical resolution in pixels-per-meter of the target
   device for the bitmap.

   biClrUsed
   Specifies the number of color indexes in the color table actually used
   by the bitmap. If this value is zero, the bitmap uses the maximum number
   of colors corresponding to the value of the biBitCount member.

   biClrImportant
   Specifies the number of color indexes that are considered important for
   displaying the bitmap. If this value is zero, then all colors are
   important.


Comments

The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a
color table to provide a complete definition of the dimensions and colors
of a Windows 3.x device-independent bitmap.


Bitmap-Compression Formats

Windows supports formats for compressing bitmaps that define their colors
with 8 bits per pixel and with 4 bits per pixel. Compression reduces the
disk and memory storage required for the bitmap.

When the biCompression member is set to BI_RLE8, the bitmap is compressed
using a run-length encoding format for an 8-bit bitmap. This format may be
compressed in either of two modes:

o   Encoded

o   Absolute

Both modes can occur anywhere throughout a single bitmap.

Encoded mode consists of two bytes: the first byte specifies the number of
consecutive pixels to be drawn using the color index contained in the
second byte. In addition, the first byte of the pair can be set to zero to
indicate an escape that denotes an end of line, end of bitmap, or a delta.
The interpretation of the escape depends on the value of the second byte of
the pair. The following list shows the meaning of the second byte.

Value   Meaning
---------------------------------------------------------------------------

0       End of line.

1       End of bitmap.

2       Delta. The two bytes following the escape contain unsigned values
        indicating the horizontal and vertical offset of the next pixel
        from the current position.

Absolute mode is signaled by the first byte set to zero and the second byte
set to a value between 03H and 0FFH. In absolute mode, the second byte
represents the number of bytes which follow, each of which contains the
color index of a single pixel. When the second byte is set to 2 or less,
the escape has the same meaning as in encoded mode. In absolute mode, each
run must be aligned on a 16-bit boundary.

The following example shows the hexadecimal values of an 8-bit compressed
bitmap:

    03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01
    02 78 00 00 09 1E 00 01
This bitmap would expand as follows (two-digit values represent a color
index for a single pixel):

    04 04 04
    06 06 06 06 06
    45 56 67
    78 78
    move current position 5 right and 1 down
    78 78
    end of line
    1E 1E 1E 1E 1E 1E 1E 1E 1E
    end of RLE bitmap
When the biCompression member is set to BI_RLE4, the bitmap is compressed
using a run-length encoding format for a 4-bit bitmap, which also uses
encoded and absolute modes. In encoded mode, the first byte of the pair
contains the number of pixels to be drawn using the color indexes in the
second byte. The second byte contains two color indexes, one in its
high-order nibble (that is, its low-order four bits) and one in its
low-order nibble. The first of the pixels is drawn using the color
specified by the high-order nibble, the second is drawn using the color in
the low-order nibble, the third is drawn with the color in the high-order
nibble, and so on, until all the pixels specified by the first byte have
been drawn.

In absolute mode, the first byte contains zero, the second byte contains
the number of color indexes that follow, and subsequent bytes contain color
indexes in their high- and low-order nibbles, one color index for each
pixel. In absolute mode, each run must be aligned on a word boundary. The
end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4.

The following example shows the hexadecimal values of a 4-bit compressed
bitmap:

    03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01
    04 78 00 00 09 1E 00 01
This bitmap would expand as follows (single-digit values represent a color
index for a single pixel):

    0 4 0
    0 6 0 6 0
    4 5 5 6 6 7
    7 8 7 8
    move current position 5 right and 1 down
    7 8 7 8
    end of line
    1 E 1 E 1 E 1 E 1
    end of RLE bitmap


CHARRANGE

    typedef struct tagCHARRANGE {
        BYTE chFirst;
        BYTE chLast;
    } CHARRANGE;
The CHARRANGE structure contains character codes for the first and last
characters in a range of characters.


Members

   chFirst
   Specifies the character code of the first character.

   chLast
   Specifies the character code of the last character.


See Also

GETEXTENTTABLE



COLORTABLE_STRUCT

    typedef struct tagCOLORTABLE_STRUCT {
        WORD Index;
        LONG rgb;
    } COLORTABLE_STRUCT;
The COLORTABLE_STRUCT structure contains color information for an entry in
the color table.


Members

   Index
   Specifies the color-table index. Color table entries start at zero for
   the first entry.

   rgb
   Specifies an RGB color value.


See Also

SETCOLORTABLE, GETCOLORTABLE



DEVMODE

    typedef struct _devicemode {    /* dm */
        char  dmDeviceName[CCHDEVICENAME];
        WORD  dmSpecVersion;
        WORD  dmDriverVersion;
        WORD  dmSize;
        WORD  dmDriverExtra;
        DWORD dmFields;
        short dmOrientation;
        short dmPaperSize;
        short dmPaperLength;
        short dmPaperWidth;
        short dmScale;
        short dmCopies;
        short dmDefaultSource;
        short dmPrintQuality;
        short dmColor;
        short dmDuplex;
        short dmYResolution;
        short dmTTOption;
    } DEVMODE;
The DEVMODE structure contains information about a printer driver's
initialization and environment. An application passes this structure to the
DeviceCapabilities and ExtDeviceMode functions.


Members

   dmDeviceName
   Specifies the name of the device the driver supports--for example, HP
   LaserJet III in the case of the Hewlett-Packard LaserJet III.

   dmSpecVersion
   Specifies the version number of the DEVMODE structure. For Windows
   version 3.1, this value should be 0x30A.

   dmDriverVersion
   Specifies the assigned printer driver version number.

   dmSize
   Specifies the size, in bytes, of the DEVMODE structure. (This value does
   not include the optional dmDriverData member for device-specific data,
   which can follow the structure.) If an application manipulates only the
   driver-independent portion of the data, it can use this member to find
   out the length of the structure without having to account for different
   versions.

   dmDriverExtra
   Specifies the size, in bytes, of the optional dmDriverData member for
   device-specific data, which can follow the structure. If an application
   does not use device-specific information, it should set this member to
   zero.

   dmFields
   Specifies a value that indicates which of the remaining members in the
   DEVMODE structure have been initialized. It can be any combination (or
   it can be none) of the following values.

     Constant           Value
     ----------------------------------------------------------------------

     DM_ORIENTATION     0x0000001L

     DM_PAPERSIZE       0x0000002L

     DM_PAPERLENGTH     0x0000004L

     DM_PAPERWIDTH      0x0000008L

     DM_SCALE           0x0000010L

     DM_COPIES          0x0000100L

     DM_DEFAULTSOURCE   0x0000200L

     DM_PRINTQUALITY    0x0000400L

     DM_COLOR           0x0000800L

     DM_DUPLEX          0x0001000L

     DM_YRESOLUTION     0x0002000L

     DM_TTOPTION        0x0004000L

   A printer driver supports only those members that are appropriate for
   the printer technology.

   dmOrientation
   Specifies the orientation of the paper. It can be either
   DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE.

   dmPaperSize
   Specifies the size of the paper to print on. This member may be set to
   zero if the length and width of the paper are specified by the
   dmPaperLength and dmPaperWidth members, respectively. Otherwise, the
   dmPaperSize member can be set to one of the following predefined values.

     Value                             Meaning
     ----------------------------------------------------------------------

     DMPAPER_10x14                     10 x 14 inches

     DMPAPER_11x17                     11 x 17 inches

     DMPAPER_A3                        A3 297 x 420 millimeters

     DMPAPER_A4                        A4 210 x 297 millimeters

     DMPAPER_A4_EXTRA                  A4 Extra 9.27 x 12.69 inches

     DMPAPER_A4_TRANSVERSE             Transverse 297 x 210 millimeters

     DMPAPER_A4SMALL                   A4 Small 210 x 297 millimeters

     DMPAPER_A5                        A5 148 x 210 millimeters

     DMPAPER_B4                        B4 250 x 354 millimeters

     DMPAPER_B5                        B5 182 x 257 millimeters

     DMPAPER_CSHEET                    C size sheet

     DMPAPER_DSHEET                    D size sheet

     DMPAPER_ENV_10                    Envelope #10 4.125 x 9.5 inches

     DMPAPER_ENV_11                    Envelope #11 4.5 x 10.375 inches

     DMPAPER_ENV_12                    Envelope #12 4.75 x 11 inches

     DMPAPER_ENV_14                    Envelope #14 5 x 11.5 inches

     DMPAPER_ENV_9                     Envelope #9 3.875 x 8.875 inches

     DMPAPER_ENV_C5                    Envelope C5 162 x 229 millimeters

     DMPAPER_ENV_DL                    Envelope DL 110 x 220 millimeters

     DMPAPER_ENV_MONARCH               Envelope Monarch 3.875 x 7.5 inches

     DMPAPER_ESHEET                    E size sheet

     DMPAPER_EXECUTIVE                 Executive 7.25 x 10.5 inches

     DMPAPER_FIRST                     Letter 8.5 x 11 inches

     DMPAPER_FOLIO                     Folio 8.5 x 13 inches

     DMPAPER_LAST                      Letter Extra Transverse 12 x 9.5
                                       inches

     DMPAPER_LEDGER                    Ledger 11 x 17 inches

     DMPAPER_LEGAL                     Legal 8.5 x 14 inches

     DMPAPER_LEGAL_EXTRA               Legal Extra 9.5 x 15 inches

     DMPAPER_LETTER                    Letter 8.5 x 11 inches

     DMPAPER_LETTER_EXTRA              Letter Extra 9.5 x 12 inches

     DMPAPER_LETTER_EXTRA_TRANSVERSE   Letter Extra Transverse 12 x 9.5
                                       inches

     DMPAPER_LETTER_TRANSVERSE         Letter Transverse 11 x 8.5 inches

     DMPAPER_LETTERSMALL               Letter Small 8.5 x 11 inches

     DMPAPER_NOTE                      Note 8.5 x 11 inches

     DMPAPER_QUARTO                    Quarto 215 x 275 millimeters

     DMPAPER_STATEMENT                 Statement 5.5 x 8.5 inches

     DMPAPER_TABLOID                   Tabloid 11 x 17 inches

     DMPAPER_TABLOID_EXTRA             Tabloid Extra 11.69 x 18 inches

     DMPAPER_USER                      User defined

   dmPaperLength
   Specifies a paper length, in tenths of a millimeter. This member
   overrides the paper length specified by the dmPaperSize member, either
   for custom paper sizes or for such devices as dot-matrix printers that
   can print on a variety of page sizes.

   dmPaperWidth
   Specifies a paper width, in tenths of a millimeter. This member
   overrides the paper width specified by the dmPaperSize member.

   dmScale
   Specifies the factor by which the printed output is to be scaled. The
   apparent page size is scaled from the physical page size by a factor of
   dmScale/100. For example, a letter-size paper with a dmScale value of 50
   would contain as much data as a page of size 17x22 inches because the
   output text and graphics would be half their original height and width.

   dmCopies
   Specifies the number of copies printed if the device supports
   multiple-page copies.

   dmDefaultSource
   Specifies the default bin from which the paper is fed. The application
   can override this value by using the GETSETPAPERBINS escape. This member
   can be one of the following values.

         DMBIN_AUTO
         DMBIN_CASSETTE
         DMBIN_ENVELOPE
         DMBIN_ENVMANUAL
         DMBIN_FIRST
         DMBIN_LARGECAPACITY
         DMBIN_LARGEFMT
         DMBIN_LAST
         DMBIN_LOWER
         DMBIN_MANUAL
         DMBIN_MIDDLE
         DMBIN_ONLYONE
         DMBIN_SMALLFMT
         DMBIN_TRACTOR
         DMBIN_UPPER
   A range of values is reserved for device-specific bins. To be consistent
   with initialization information, the GETSETPAPERBINS and ENUMPAPERBINS
   escapes use these values.

   dmPrintQuality
   Specifies the printer resolution. Following are the four predefined
   device-independent values:

             DMRES_HIGH (-4)
             DMRES_MEDIUM (-3)
             DMRES_LOW (-2)
             DMRES_DRAFT (-1)
   If a positive value is given, it specifies the number of dots per inch
   (DPI) and is therefore device dependent.

   If the printer initializes the dmYResolution member, the dmPrintQuality
   member specifies the x-resolution of the printer, in dots per inch.

   dmColor
   Specifies whether a color printer is to render color or monochrome
   output. Possible values are:

             DMCOLOR_COLOR (1)
             DMCOLOR_MONOCHROME (2)
   dmDuplex
   Specifies duplex (double-sided) printing for printers capable of duplex
   printing. This member can be one of the following values:

             DMDUP_SIMPLEX (1)
             DMDUP_HORIZONTAL (2)
             DMDUP_VERTICAL (3)
   dmYResolution
   Specifies the y-resolution of the printer, in dots per inch. If the
   printer initializes this member, the dmPrintQuality member specifies the
   x-resolution of the printer, in dots per inch.

   dmTTOption
   Specifies how TrueType fonts should be printed. It can be one of the
   following values.

     Value           Meaning
     ----------------------------------------------------------------------

     DMTT_BITMAP     Prints TrueType fonts as graphics. This is the default
                     action for dot-matrix printers.

     DMTT_DOWNLOAD   Downloads TrueType fonts as soft fonts. This is the
                     default action for Hewlett-Packard printers that use
                     Printer Control Language (PCL).

     DMTT_SUBDEV     Substitutes device fonts for TrueType fonts. This is
                     the default action for PostScript printers.


Comments

An application can retrieve the paper sizes and names supported by a
printer by calling the DeviceCapabilities function with the DC_PAPERS,
DC_PAPERSIZE, and DC_PAPERNAMES values.

Before setting the value of the dmTTOption member, applications should find
out how a printer driver can use TrueType fonts by calling the
DeviceCapabilities function with the DC_TRUETYPE value.

Drivers can add device-specific data immediately following the DEVMODE
structure.


See Also

DeviceCapabilities, ExtDeviceMode



DRAWMODE

    typedef struct tagDRAWMODE {
      short    Rop2;       /*binary-raster operations*/
      short    bkMode;     /*background mode*/
      PCOLOR   bkColor;    /*physical background color*/
      PCOLOR   TextColor;  /*physical text (foreground) color*/
      short    TBreakExtra;/*number of extra pixels to add to line*/
      short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
      short    BreakErr;   /*running error term*/
      short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
      short    BreakCount; /*number of breaks in the line*/
      short    CharExtra;  /*extra pixels for each character*/
      COLORREF LbkColor;   /*logical background color*/
      COLORREF LTextColor; /*logical text (foreground) color*/
    } DRAWMODE;
The DRAWMODE structure contains information used during output, such as
drawing lines, filling interiors, and writing text.


Members

   Rop2
   Specifies a binary-raster operation value. The value, in the range 1 to
   16, determines how to combine source and destination colors. This member
   can be one of the following values.

     Value                 Meaning
     ----------------------------------------------------------------------

     R2_BLACK (1)          Black: 0.

     R2_NOTMERGEPEN (2)    Inverse of the bitwise OR of the source and
                           destination colors: NOT (Source OR Dest).

     R2_MASKNOTPEN (3)     Bitwise AND of the destination and the inverse
                           of the source: Dest AND (NOT Source).

     R2_NOTCOPYPEN (4)     Inverse of the source color: NOT Source.

     R2_MASKPENNOT (5)     Bitwise AND of the source and the inverse of the
                           destination: Source AND (NOT Dest).

     R2_NOT (6)            Inverse of the destination color: NOT Dest.

     R2_XORPEN (7)         Bitwise exclusive OR of the destination and
                           source: Dest XOR Source.

     R2_NOTMASKPEN (8)     Inverse of the bitwise AND of the destination
                           and source colors: NOT (Dest AND Source).

     R2_MASKPEN 9          Bitwise AND of the destination and source
                           colors: Dest AND Source.

     R2_NOTXORPEN (10)     Inverse of the bitwise exclusive OR of the
                           destination and source colors: NOT (Dest XOR
                           Source).

     R2_NOP 11             Destination color: Dest.

     R2_MERGENOTPEN (12)   Bitwise OR of the destination and the inverse of
                           the source: Dest AND (NOT Source).

     R2_COPYPEN (13)       Source color: Source.

     R2_MERGEPENNOT (14)   Bitwise OR of the source and the inverse of the
                           destination: Source OR (NOT Dest).

     R2_MERGEPEN (15)      Bitwise OR of the source and the destination:
                           Source OR Dest.

     R2_WHITE (16)         White: 1.

   bkMode
   Specifies whether the background for styled lines, hatched brushes,
   brushes used for interiors and scan lines, bitmaps, and text is given
   the current background color or left unchanged. This member can be one
   of the following values.

     Value              Meaning
     ----------------------------------------------------------------------

     TRANSPARENT (1)    Leaves destination background unchanged.

     OPAQUE (2)         Replaces destination background with the color
                        specified by the BackgroundColor member.

     TRANSPARENT1 (4)   Leaves destination background unchanged, but before
                        copying the source to destination, removes pixels
                        from the source that have the current background
                        color.

   bkColor
   Contains a physical color value specifying the background color.

   TextColor
   Contains a physical color value specifying the text (foreground) color.

   TBreakExtra
   Specifies the total amount of space (in pixels) to add to the break
   characters in a line of text. TBreakExtra is set to zero if no
   justification is required.

   BreakExtra
   Specifies the amount of space (in pixels) to add to each break character
   in a line of text. This value is equal to TBreakExtra divided by
   BreakCount.

   BreakErr
   Specifies the running error term: the amount of space (in pixels) not
   yet added to break characters in a line of text. This member is used in
   conjunction with the BreakRem member to determine which break characters
   receive the additional pixels specified by BreakRem. Initially, BreakErr
   is set to (BreakCount)/2+1.

   BreakRem
   Specifies the amount of space (in pixels) to add to one or more break
   characters in a line of text. This space is in addition to any extra
   space specified by the BreakExtra member and is intended to be
   distributed evenly across the line. The BreakRem value is equal to the
   remainder after dividing TBreakExtra by BreakCount.

   BreakCount
   Specifies the number of break characters in a line of text. If the
   TBreakExtra member is not zero, each break character must be drawn wider
   than its normal width. The BreakExtra member specifies the extra width
   (in pixels). The BreakRem member may also specify additional pixels for
   one or more break characters.

   CharExtra
   Specifies amount of space (in pixels) to add between characters in a
   line of text.

   LbkColor
   Contains an COLORREF value specifying the logical background color.

   LTextColor
   Contains an COLORREF value specifying the logical text (foreground)
   color.


See Also

BitBlt, DeviceBitmapBits, ExtTextOut, Output, Pixel, SetDIBitsToDevice,
StrBlt, StretchBlt, StretchDIBits



EXTTEXTDATA

    typedef struct tagEXTTEXTDATA {
        short             nSize;
        LPAPPEXTTEXTDATA  lpInData;
        LPFONTINFO        lpFont;
        LPTEXTXFORM       lpXForm;
        LPDRAWMODE        lpDrawMode;
    } EXTTEXTDATA;
The EXTTEXTDATA structure contains a complete set of information describing
the text to be drawn.


Members

   nSize
   Specifies the size in bytes of the structure.

   lpInData
   Points to a 16-bit variable that contains the number of bytes pointed to
   by the lpOutData parameter in an GETEXTENDEDTEXTMETRICS escape.

   lpFont
   Points to a FONTINFO structure specifying a physical font. The FONTINFO
   structure has the following form:

         typedef struct tagFONTINFO {
             short dfType;
             short dfPoints;
             short dfVertRes;
             short dfHorizRes;
             short dfAscent;
             short dfInternalLeading;
             short dfExternalLeading;
             char  dfItalic;
             char  dfUnderline;
             char  dfStrikeOut;
             short dfWeight;
             char  dfCharSet;
             short dfPixWidth;
             short dfPixHeight;
             char  dfPitchAndFamily;
             short dfAvgWidth;
             short dfMaxWidth;
             char  dfFirstChar;
             char  dfLastChar;
             char  dfDefaultChar;
             char  dfBreakChar;
             short dfWidthBytes;
             long  dfDevice;
             long  dfFace;
             long  dfBitsPointer;
             long  dfBitsOffset;
             char  dfReserved;
             /* The following fields present only for Windows 3.x fonts */
             long  dfFlags;
             short dfAspace;
             short dfBspace;
             short dfCspace;
             long  dfColorPointer;
             long  dfReserved1[4];
         } FONTINFO;
   lpXForm
   Points to a TEXTXFORM structure specifying additional attributes of the
   text. The TEXTXFORM structure has the following form:

         typedef struct tagTEXTXFORM {
             short  txfHeight;
             short  txfWidth;
             short  txfEscapement;
             short  txfOrientation;
             short  txfWeight;
             char   txfItalic;
             char   txfUnderline;
             char   txfStrikeOut;
             char   txfOutPrecision;
             char   txfClipPrecision;
             short  txfAccelerator;
             short  txfOverhang;
         } TEXTXFORM;
   lpDrawMode
   Points to a DRAWMODE structure specifying information used to draw the
   text. The DRAWMODE structure has the following form:

         typedef struct tagDRAWMODE {
           short    Rop2;       /*binary-raster operations*/
           short    bkMode;     /*background mode*/
           PCOLOR   bkColor;    /*physical background color*/
           PCOLOR   TextColor;  /*physical text (foreground) color*/
           short    TBreakExtra;/*number of extra pixels to add to line*/
           short    BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/
           short    BreakErr;   /*running error term*/
           short    BreakRem;   /*remaining pixels: TBreakExtra%BreakCount*/
           short    BreakCount; /*number of breaks in the line*/
           short    CharExtra;  /*extra pixels for each character*/
           COLORREF LbkColor;   /*logical background color*/
           COLORREF LTextColor; /*logical text (foreground) color*/
         } DRAWMODE;

See Also

DRAWMODE, FONTINFO, GETEXTENDEDTEXTMETRICS, TEXTXFORM



EXTTEXTMETRIC

    typedef struct tagEXTTEXTMETRIC {
        short  etmSize;
        short  etmPointSize;
        short  etmOrientation;
        short  etmMasterHeight;
        short  etmMinScale;
        short  etmMaxScale;
        short  etmMasterUnits;
        short  etmCapHeight;
        short  etmXHeight;
        short  etmLowerCaseAscent;
        short  etmUpperCaseDescent;
        short  etmSlant;
        short  etmSuperScript;
        short  etmSubScript;
        short  etmSuperScriptSize;
        short  etmSubScriptSize;
        short  etmUnderlineOffset;
        short  etmUnderlineWidth;
        short  etmDoubleUpperUnderlineOffset;
        short  etmDoubleLowerUnderlineOffset;
        short  etmDoubleUpperUnderlineWidth;
        short  etmDoubleLowerUnderlineWidth;
        short  etmStrikeOutOffset;
        short  etmStrikeOutWidth;
        WORD   etmKernPairs;
        WORD   etmKernTracks;
    } EXTTEXTMETRIC;
The EXTTEXTMETRIC contains extended information about a font.


Members

   etmSize
   Specifies the size (in bytes) of the structure.

   etmPointSize
   Specifies the point size of the font.

   etmOrientation
   Specifies the orientation.

   etmMasterHeight
   Specifies the master height.

   etmMinScale
   Specifies the smallest reasonable scaling factor for the font.

   etmMaxScale
   Specifies the largest reasonable scaling factor for the font.

   etmMasterUnits
   Specifies the master units.

   etmCapHeight
   Specifies the height of capital letters.

   etmXHeight
   Specifies a representative height for the font.

   etmLowerCaseAscent
   Specifies the ascent height for lowercase letters.

   etmUpperCaseDescent
   Specifies the ascent height for uppercase letters.

   etmSlant
   Specifies the slant of characters in the font.

   etmSuperScript
   Specifies whether the font supports superscripts.

   etmSubScript
   Specifies whether the font supports subscripts.

   etmSuperScriptSize
   Specifies the size of the superscript characters.

   etmSubScriptSize
   Specifies the size of the subscript characters.

   etmUnderlineOffset
   Specifies the offset from the baseline to the underline.

   etmUnderlineWidth
   Specifies the width of an underline.

   etmDoubleUpperUnderlineOffset
   Specifies the offset from the baseline to the upper portion of a double
   underline.

   etmDoubleLowerUnderlineOffset
   Specifies the offset from the baseline to the lower portion of a double
   underline.

   etmDoubleUpperUnderlineWidth
   Specifies the width of the upper portion of a double underline.

   etmDoubleLowerUnderlineWidth
   Specifies the width of the lower portion of a double underline.

   etmStrikeOutOffset
   Specifies the offset from the baseline of the strikeout line.

   etmStrikeOutWidth
   Specifies the width of the strikeout line.

   etmKernPairs
   Specifies the number of kerning pairs.

   etmKernTracks
   Specifies the number of kerning tracks.


See Also

GETEXTENDEDTEXTMETRICS



FONTINFO

    typedef struct tagFONTINFO {
        short dfType;
        short dfPoints;
        short dfVertRes;
        short dfHorizRes;
        short dfAscent;
        short dfInternalLeading;
        short dfExternalLeading;
        char  dfItalic;
        char  dfUnderline;
        char  dfStrikeOut;
        short dfWeight;
        char  dfCharSet;
        short dfPixWidth;
        short dfPixHeight;
        char  dfPitchAndFamily;
        short dfAvgWidth;
        short dfMaxWidth;
        char  dfFirstChar;
        char  dfLastChar;
        char  dfDefaultChar;
        char  dfBreakChar;
        short dfWidthBytes;
        long  dfDevice;
        long  dfFace;
        long  dfBitsPointer;
        long  dfBitsOffset;
        char  dfReserved;
        /* The following fields present only for Windows 3.x fonts */
        long  dfFlags;
        short dfAspace;
        short dfBspace;
        short dfCspace;
        long  dfColorPointer;
        long  dfReserved1[4];
    } FONTINFO;
The FONTINFO structure contains information about a physical font.
Depending on whether the font is realized by GDI or by a device driver, the
FONTINFO structure may be immediately followed by a character width table
and by font bitmap or vector information.

The FONTINFO structure contains optional members (dfFlags through
dfReserved1) that are present only if the font has been designed for
Windows 3.x. If GDI realizes a font for a driver, the font's corresponding
FONTINFO structure will not include these optional members unless the
RC_BIGFONT bit is set in the dpRaster member of the driver's GDIINFO
structure.


Members

   dfType
   Specifies font type. The low-order byte, reserved for exclusive GDI use,
   is a combination of the following values.

     Value                         Meaning
     ----------------------------------------------------------------------

     PF_RASTER_TYPE (0x0000)       Font is a raster font.

     PF_VECTOR_TYPE (0x0001)       Font is a vector font.

     PF_BITS_IS_ADDRESS (0x0004)   Indicates that the dfBitsOffset member
                                   specifies the absolute memory address of
                                   the font bitmap or vector information.

     PF_DEVICE_REALIZED (0x0080)   Font has been realized by the device
                                   driver.

   All other values in the low-order byte are reserved. In particular, the
   value 0x0008 in the dfType member is reserved for use with Asian fonts.

   The high-order byte is reserved for device use. GDI never inspects the
   high byte. If GDI realizes the font, it sets this byte to zero. If the
   device driver realizes the font, it can set this byte to any value.

   dfPoints
   Specifies the point size at which this character set looks best.

   dfVertRes
   Specifies the vertical resolution (dots-per-inch) at which this
   character set was digitized.

   dfHorizRes
   Specifies the horizontal resolution (dots-per-inch) at which this
   character set was digitized.

   dfAscent
   Specifies the distance from the top of a character definition cell to
   the baseline of the typographical font. It is useful for aligning the
   baseline of fonts of different heights.

   dfInternalLeading
   Specifies the amount of leading inside the bounds set by the dfPixHeight
   member. Accent marks may occur in this area.

   dfExternalLeading
   Specifies the amount of extra leading that the designer requests the
   application add between rows. Since this area is outside of the font
   proper, it contains no marks and will not be altered by text output
   calls in either the OPAQUE or TRANSPARENT mode.

   dfItalic
   Specifies whether the character-definition data represents an italic
   font. The low-order bit is 1 if the flag is set. All other bits are
   zero.

   dfUnderline
   Specifies whether the character-definition data represents an underlined
   font. The low-order bit is 1 if the flag is set. All other bits are
   zero.

   dfStrikeOut
   Specifies whether the character definition data represents a struck-out
   font. The low-order bit is 1 if the flag is set. All other bits are
   zero.

   dfWeight
   Specifies the weight of the characters in the character definition data,
   on a scale from 1-1000. A value of 400 specifies regular weight type;
   700 is bold; and so on.

   dfCharSet
   Specifies the character set defined by this font. It can be one of the
   following values.

     Value   Meaning
     ----------------------------------------------------------------------

     0       ANSI character set

     2       Symbol character set

     255     OEM hardware font

   dfPixWidth
   Specifies the width of all characters in the font.

   For vector fonts, the dfPixWidth member is the width of the grid on
   which the font was digitized.

   For raster fonts, dfPixWidth is the width (in pixels) of each character
   bitmap. If that member is zero, the font has variable-width characters
   and these widths are specified in the character-width table immediately
   following this structure.

   dfPixHeight
   Specifies the height of all characters in the font.

   For vector fonts, the dfPixHeight member is the height of the grid on
   which the font was digitized.

   For raster fonts, dfPixHeight is the height (in scan lines) of each
   character bitmap.

   dfPitchAndFamily
   Specifies the pitch and font family. The pitch specifies whether the
   characters in the font have the same width or variable widths. The font
   family indicates, in a general way, the look of a font.

   The dfPitchAndFamily member can be a combination of the following
   values.

     Value                  Meaning
     ----------------------------------------------------------------------

     0x01                   Variable-pitch font. If this value is not
                            given, the font is fixed pitch.

     FF_ROMAN (0x10)        Proportionally spaced fonts with serifs.

     FF_SWISS (0x20)        Proportionally spaced fonts without serifs.

     FF_MODERN (0x30)       Fixed-pitch fonts.

     FF_SCRIPT (0x40)       Cursive or script fonts.

     FF_DECORATIVE (0x50)   Novelty fonts.

   If the high-order 4 bits is set to FF_DONTCARE (0x00), the font belongs
   to no specific family.

   dfAvgWidth
   Specifies the width of characters in the font. For fixed-pitch fonts,
   this is the same as dfPixWidth. For variable-pitched fonts, this is the
   width of the character X.

   dfMaxWidth
   Specifies the maximum pixel width of any character in the font. For
   fixed-pitch fonts, this is simply dfPixWidth.

   dfFirstChar
   Specifies the first character code defined by this font. Character
   definitions are stored only for the characters actually present in a
   font, so this field should be used when calculating indexes into the
   character-width table following this structure.

   dfLastChar
   Specifies the last character code defined by this font. Notice that all
   the characters with codes between the dfFirstChar and dfLastChar member
   must be present in the character-width table.

   dfDefaultChar
   Specifies the default character. A device driver uses this character as
   a substitute for any character in a string that is out of the range of
   the dfFirstChar through dfLastChar members. The character is given
   relative to dfFirstChar so that the actual value of the default
   character is the sum of dfDefaultChar and dfFirstChar. Ideally, the
   dfDefaultChar member should be a visible character in the current font,
   for example, a period (.).

   dfBreakChar
   Specifies the word-break character. Applications use this character the
   separate words when wrapping or justifying lines of text. The character
   is given relative to dfFirstChar so that the actual value of the
   word-break character is the sum of the dfBreakChar and dfFirstChar
   members. In many fonts, dfBreakChar is zero and dfFirstChar is 32. This
   means that the word-break character value is 32, an ASCII space.

   dfWidthBytes
   Specifies the number of bytes in each row of the font bitmap (raster
   fonts). This field is not used for vector fonts. The dfWidthBytes member
   is always an even quantity so that rows of the bitmap start on 16-bit
   boundaries.

   dfDevice
   Specifies the offset from the beginning of the segment containing the
   FONTINFO structure to the null-terminated ASCII string specifying the
   device name. For a generic font, this value will be NULL.

   dfFace
   Specifies the offset from the beginning of the segment containing the
   FONTINFO structure to the null-terminated ASCII string specifying the
   name of the font face.

   dfBitsPointer
   Specifies the absolute machine address of the bitmap. This is set by
   GDI. The dfBitsPointer member is guaranteed to be even.

   dfBitsOffset
   Specifies the offset from the beginning of the segment containing the
   FONTINFO structure to the beginning of the bitmap information.

   If the PF_BITS_IS_ADDRESS bit is set in dfType, dfBitsOffset is an
   absolute address of the bitmap or vector information. For example, this
   bit is set if the font bitmap or vector information is in ROM.

   For raster fonts, dfBitsOffset points to a sequence of bytes that make
   up the bitmaps for each character in the font.

   For vector fonts, dfBitsOffset points to a string of bytes or words
   (depending on the size of the grid on which the font was digitized) that
   specifies the strokes for each character of the font. The dfBitsOffset
   member must be even.

   dfReserved
   Reserved; do not use. This member is present only for raster fonts. In
   Windows 2.x fonts, this member ensures that the character-width table
   (which immediately follows this member) starts on a 16-bit boundary.

   dfFlags
   Specifies the format of the font bitmap information. It can be one of
   the following values.

     Value                          Meaning
     ----------------------------------------------------------------------

     FSF_FIXED (0x0001)             Font is fixed pitch.

     FSF_PROPORTIONAL (0x0002)      Font is proportional pitch

     FSF_ABCFIXED (0x0004)          Font is an ABC fixed font. The advance
                                    width for each character in the font is
                                    the sum of the dfAspace, dfBspace, and
                                    dfCspace members.

     FSF_ABCPROPORTIONAL (0x0008)   Font is an ABC proportional font.

     FSF_1COLOR (0x0010)            Font is one color.

     FSF_16COLOR (0x0020)           Font is 16 color.

     FSF_256COLOR (0x0040)          Font is 256 color.

     FSF_RGBCOLOR (0x0080)          Font is RGB color.

   This member is present only for Windows 3.x fonts.

   dfAspace
   Specifies the global A space, if any. The dfAspace member is the
   distance from the current position to the left edge of the bitmap. This
   member is present only for Windows 3.x fonts.

   dfBspace
   Specifies the global B space, if any. The dfBspace member is the width
   of the character. This member is present only for Windows 3.x fonts.

   dfCspace
   Specifies the global C space, if any. The dfCspace member is the
   distance from the right edge of the bitmap to the new current position.
   This member is present only for Windows 3.x fonts.

   dfColorPointer
   Specifies the offset to the color table (if any) for color fonts. This
   member is present only for Windows 3.x fonts, however, it is not
   presently used and should always be set to NULL.

   dfReserved1
   This member is not used. This member is present only for Windows 3.x
   fonts.


Comments

The FONTINFO structure may be immediately followed by one or more of the
following items.

Item                    Description
---------------------------------------------------------------------------

Character-width table   Specifies the widths of each character as well as
                        specifies the offset to the corresponding bitmap or
                        vector information.

Bitmaps                 Specifies the bits defining the shape of the
                        characters in a raster font. The size of this item
                        is whatever length the total bitmaps occupy. Each
                        row of a raster bitmap must start on a 16-bit
                        boundary. This implies that the end of each row
                        must be padded to an even length.

Vectors                 Specifies the set of coordinates that define the
                        shape of the characters in a vector font.

Font name               Specifies a null-terminated ASCII character string
                        specifying the name of the font. The size of this
                        field is the length of the string plus a null
                        character.

Device name             Specifies a null-terminated ASCII character string
                        specifying the name of the device if this font file
                        is for a specific device. The size of this field is
                        the length of the string plus a null character.

All device drivers must support Windows 2.x fonts. If a device driver
supports Windows 3.x fonts, it must set the RC_BIGFONT bit in the dpRaster
member of its GDIINFO structure. Printer drivers can call the GetDeviceCaps
function (GDI.80), and check for the RC_BIGFONT bit in the raster
capabilities to determine whether the display driver uses Windows 3.x
fonts.

When a device driver realizes a font using the RealizeObject function, the
dfFace and dfDevice members must point to valid character strings
containing the font and device names.


Windows 2.x Fonts

For Windows 2.x fonts the character-width table is either an array of
integer values or an array of glyph-entry structures. The number of
elements in the array is equal to:

    dfLastChar - dfFirstChar + 2
That is, there is always one more element than the number of characters in
the font. The extra entry is available for storing the size in bytes of the
last character in a vector font. Although this extra entry applies only to
vector fonts, it is present for all fonts.

For fixed-pitch vector fonts, the character-width table is an array of
integer values. In this case, each element of the array is an offset
(relative to the start of the segment containing the FONTINFO structure) to
the first byte or 16 bits of vector information for the given character.
The number of bytes or words for a particular character is calculated by
subtracting its character-width table entry from the entry for the next
character.

For variable-pitch vector fonts, the character width table is an array of
VECTORGLYPHENTRY structures. The VECTORGLYPHENTRY structure has the
following form:

    typedef struct tagVECTORGLYPHENTRY {
        short vgeOffset;    /* offset to vectors relative to segment start */
        short vgeWidth;     /* width of character in pixels */
    } VECTORGLYPHENTRY;
The vgeOffset member specifies the offset (relative to the start of the
segment containing the FONTINFO structure) to the first byte or 16 bits of
vector information for the given character. The vgeWidth member specifies
the width for the character.

For raster fonts, the character-width table is an array of RASTERGLYPHENTRY
structures.

The rgeWidth member specifies the width (in pixels) of the bitmap for the
given character. The member also specifies the advance width for the given
character. The rgeOffset member specifies the offset (relative to the start
of the segment containing the FONTINFO structure) to the first byte of
bitmap information for the character.

Windows 2.x fonts cannot exceed 64K bytes.


Windows 3.x Fonts

Windows 3.x fonts are primarily designed for use on systems with more than
average memory and a microprocessor (such as an 80386) that has
instructions that use 32-bit address offsets.

For Windows 3.x fonts, the format of the character-width table is dependent
on the value of the dfFlags member.

Value                 Meaning
---------------------------------------------------------------------------

DFF_FIXED             Specifies an array of RASTERGLYPHENTRY structures.

DFF_PROPORTIONAL      Specifies an array of RASTERGLYPHENTRY structures.

DFF_ABCFIXED          Specifies an array of ABCGLYPHENTRY structures.

DFF_ABCPROPORTIONAL   Specifies an array of ABCGLYPHENTRY structures.

DFF_1COLOR            Specifies an array of COLORGLYPHENTRY structures.

DFF_16COLOR           Specifies an array of COLORGLYPHENTRY structures.

DFF_256COLOR          Specifies an array of COLORGLYPHENTRY structures.

DFF_RGBCOLOR          Specifies an array of COLORGLYPHENTRY structures.

Windows presently supports only the DFF_FIXED and DFF_PROPORTIONAL values.

The rgeWidth member specifies the width (in pixels) of the bitmap for the
given character. The member also specifies the width for the character. The
rgeOffset member specifies the offset (relative to the start of the segment
containing the FONTINFO structure) to the first byte of bitmap information
for the character.

The ABCGLYPHENTRY structure has the following form:

    typedef struct tagABCGLYPHENTRY {
        short ageWidth;     /* width of character bitmap in pixels */
        long  ageOffset;    /* pointer to the bits */
        FIXED ageAspace;    /* A space in fractional pixels (16.16) */
        FIXED ageBspace;    /* B space in fractional pixels (16.16) */
        FIXED ageCspace;    /* C space in fractional pixels (16.16) */
    } ABCGLYPHENTRY;
The ageWidth member specifies the width (in pixels) of the bitmap for the
given character. The ageOffset member specifies the offset (relative to the
start of the segment containing the FONTINFO structure) to the first byte
of bitmap information for the character. The sum of the ageAspace,
ageBspace, and ageCspace members specify the width of the character.

The COLORGLYPHENTRY structure has the following form:

    typedef struct tagCOLORGLYPHENTRY {
        short cgeWidth;     /* width of character bitmap in pixels */
        long  cgeOffset;    /* pointer to the bits */
        short cgeHeight;    /* height of character bitmap in pixels */
        FIXED cgeAspace;    /* A space in fractional pixels (16.16) */
        FIXED cgeBspace;    /* B space in fractional pixels (16.16) */
        FIXED cgeCspace;    /* C space in fractional pixels (16.16) */
    } COLORGLYPHENTRY;
The cgeWidth member specifies the width (in pixels) of the bitmap for the
given character. The cgeOffset member specifies the offset (relative to the
start of the segment containing the FONTINFO structure) to the first byte
of bitmap information for the character. The cgeHeight member specifies the
height (in scan lines) of the bitmap. The sum of the cgeAspace, cgeBspace,
and cgeCspace members specify the width of the character.

The number of bits for each pixel in a character bitmap depends on the
value of the dfFlags member.

Value          Bits per pixel
---------------------------------------------------------------------------

DFF_1COLOR     Bitmap has 1 bit per pixel.

DFF_16COLOR    Bitmap has 4 bits per pixel.

DFF_256COLOR   Bitmap has 8 bits per pixel.

DFF_RGBCOLOR   Bitmap has 32 bits per pixel (an RGBQUAD structure for each
               pixel).

All other font formats use 1 bit per pixel.

Windows 3.x fonts can exceed 64K bytes.


See Also

ExtTextOut, RealizeObject, StrBlt



GDIINFO

    typedef struct tagGDIINFO {
        short  int                dpVersion;
        short  int                dpTechnology;
        short  int                dpHorzSize;
        short  int                dpVertSize;
        short  int                dpHorzRes;
        short  int                dpVertRes;
        short  int                dpBitsPixel;
        short  int                dpPlanes;
        short  int                dpNumBrushes;
        short  int                dpNumPens;
        short  int                futureuse;
        short  int                dpNumFonts;
        short  int                dpNumColors;
        unsigned  short  int      dpDEVICEsize;
        unsigned  short  int      dpCurves;
        unsigned  short  int      dpLines;
        unsigned  short  int      dpPolygonals
        unsigned  short  int      dpText;
        unsigned  short  int      dpClip;
        unsigned  short  int      dpRaster;
        short  int                dpAspectX;
        short  int                dpAspectY;
        short  int                dpAspectXY;
        short  int                dpStyleLen;
        POINT                     dpMLoWin;
        POINT                     dpMLoVpt;
        POINT                     dpMHiWin;
        POINT                     dpMHiVpt;
        POINT                     dpELoWin;
        POINT                     dpELoVpt;
        POINT                     dpEHiWin;
        POINT                     dpEHiVpt;
        POINT                     dpTwpWin;
        POINT                     dpTwpVpt;
        short  int                dpLogPixelsX;
        short  int                dpLogPixelsY;
        short  int                dpDCManage;
        short  int                dpCaps1;
        long   int                dpSpotSizeX;
        long   int                dpSpotSizeY;
        short  int                dpPalColors;
        short  int                dpPalReserved;
        short  int                dpPalResolution;
    } GDIINFO;
The GDIINFO structure contains information about graphics devices supported
by the device driver. GDI retrieves this structure when it loads the driver
and uses the information in the structure to initialize the driver.


Members

   dpVersion
   Specifies the version number. The high-order byte specifies the major
   version, the low-order byte the minor version. For example, in a device
   driver developed for Windows 3.1, this member should contain 0x030A.

   dpTechnology
   Specifies the device technology. It can be one of the following values.

            Value               Meaning
            ---------------------------------------------------------------

            DT_PLOTTER (0)      Vector plotter

            DT_RASDISPLAY (1)   Raster display

            DT_RASPRINTER (2)   Raster printer

            DT_RASCAMERA (3)    Raster camera

            DT_CHARSTREAM (4)   Character stream, PLP

            DT_METAFILE (5)     Metafile, VDM

            DT_DISPFILE (6)     Display file

   dpHorzSize
   Specifies the width of the physical display surface in millimeters.

   dpVertSize
   Specifies the height of the physical display surface in millimeters.

   dpHorzRes
   Specifies the width of the display surface in pixels. For nonraster
   devices, this width is equivalent to the number of vertical grid lines
   used by the device to plot points on the display surface. In such cases,
   a pixel is defined to be the smallest mark the device can draw.

   dpVertRes
   Specifies the height of the display in raster lines. For nonraster
   devices, this height is equivalent to the number of horizontal grid
   lines used by the device to plot points on the display surface. In such
   cases, a raster line is equivalent to a gridline.

   dpBitsPixel
   Specifies the number of adjacent bits on each plane required to define a
   single pixel.

   dpPlanes
   Specifies the number of planes required to define the pixels. For a
   typical raster device with red, green, and blue bit planes (such as a
   3-plane EGA), this member is 3.

   dpNumBrushes
   Specifies the number of device-specific brushes supported by this
   device.

   dpNumPens
   Specifies the number of device-specific pens supported by this device.

   futureuse
   Reserved; do not use.

   dpNumFonts
   Specifies the number of device-specific fonts supported by this device.

   dpNumColors
   Specifies the number of entries in the color table for this device or
   the number of reserved colors for palette-capable devices.

   dpDEVICEsize
   Specifies the size (in bytes) of the PDEVICE structure for this device.
   It must be at least two bytes.

   dpCurves
   Specifies whether the device driver can perform circles, pie wedges,
   chord arcs, and ellipses. The dpCurves member also specifies whether the
   interior of those figures that can be handled can be brushed in, and
   whether the borders of those figures that can be handled can be drawn
   with wide lines, styled lines, or lines that are both wide and styled.
   The dpCurves member can be a combination of the following values.

            Value                    Meaning
            ---------------------------------------------------------------

            CC_NONE (0x0000)         Curves not supported.

            CC_CIRCLES (0x0001)      Can perform circles.

            CC_PIE (0x0002)          Can perform pie wedges.

            CC_CHORD (0x0004)        Can perform chord arcs.

            CC_ELLIPSES (0x0008)     Can perform ellipses.

            CC_WIDE (0x0010)         Can perform wide lines.

            CC_STYLED (0x0020)       Can perform styled lines.

            CC_WIDESTYLED (0x0040)   Can perform lines that are wide and
                                     styled.

            CC_INTERIORS (0x0080)    Can perform interiors.

            CC_ROUNDRECT (0x0100)    Can perform round rectangles.

   All other values are reserved.

   dpLines
   Specifies whether the device driver can perform polylines and lines. The
   dpLines member also specifies whether the interior of those figures that
   can be handled can be brushed in, and whether the borders of those
   figures that can be handled can be drawn with wide lines, styled lines,
   or lines that are both wide and styled. The dpLines member can be a
   combination of the following values.

            Value                    Meaning
            ---------------------------------------------------------------

            LC_NONE (0x0000)         Lines not supported.

            LC_POLYLINE (0x0002)     Can perform polylines.

            LC_WIDE (0x0010)         Can perform wide lines.

            LC_STYLED (0x0020)       Can perform styled lines.

            LC_WIDESTYLED (0x0040)   Can perform wide styled lines.

            LC_INTERIORS (0x0080)    Can perform interiors.

   All other values are reserved. The high byte must be zero.

   dpPolygonals
   Specifies whether the device driver can perform polygons, rectangles,
   and scan lines. The dpPolygonals member also specifies whether the
   interior of those figures that can be handled can be brushed in, and
   whether the borders of those figures that can be handled can be drawn
   with wide lines, styled lines, or lines that are both wide and styled.
   The dpPolygonals member can be a combination of the following values.

            Value                     Meaning
            ---------------------------------------------------------------

            PC_NONE (0x0000)          Polygons not supported.

            PC_ALTPOLYGON (0x0001)    Can perform alternate-fill polygons.

            PC_RECTANGLE (0x0002)     Can perform rectangles.

            PC_WINDPOLYGON (0x0004)   Can perform winding-number-fill
                                      polygons.

            PC_SCANLINE (0x0008)      Can perform scan lines.

            PC_WIDE (0x0010)          Can perform wide borders.

            PC_STYLED (0x0020)        Can perform styled borders.

            PC_WIDESTYLED (0x0040)    Can perform borders that are wide and
                                      styled.

            PC_INTERIORS (0x0080)     Can perform interiors.

   All other values are reserved. The high byte must be zero.

   dpText
   Specifies the level of text support the device driver provides. The
   dpText member can be a combination of the following values.

            Value                      Meaning
            ---------------------------------------------------------------

            TC_OP_CHARACTER (0x0001)   Can generate character-precision
                                       text. If this value is not given (or
                                       implied by the TC_OP_STROKE value),
                                       the driver can generate
                                       string-precision text only.

            TC_OP_STROKE (0x0002)      Can generate stroke-precision text.
                                       The value implies the
                                       TC_OP_CHARACTER value.

            TC_CP_STROKE (0x0004)      Can draw partially clipped
                                       characters. If this value is not
                                       given, the character must be
                                       entirely within the clipping region
                                       to be drawn.

            TC_CR_90 (0x0008)          Can rotate characters in 90-degree
                                       increments. If this value is not
                                       given (or implied by the TC_CR_ANY
                                       value), the driver can not rotate
                                       text.

            TC_CR_ANY (0x0010)         Can rotate characters to any angle.
                                       This value implies the TC_CR_90
                                       value.

            TC_SF_X_YINDEP (0x0020)    Can scale characters independently
                                       along the x- and y-axes. If this
                                       value is not given, the driver may
                                       be able to scale characters but not
                                       independently along the axes.

            TC_SA_DOUBLE (0x0040)      Can scale characters by doubling. If
                                       this value is not given (or implied
                                       by the TC_SA_INTEGER or TC_SA_CONTIN
                                       values), the driver cannot scale
                                       text.

            TC_SA_INTEGER (0x0080)     Can scale characters by integral
                                       multiples. This value implies the
                                       TC_SA_DOUBLE value.

            TC_SA_CONTIN (0x0100)      Can scale characters by any
                                       multiple. This value implies the
                                       TC_SA_DOUBLE and TC_SA_INTEGER
                                       values.

            TC_EA_DOUBLE (0x0200)      Can generate bold characters by
                                       doubling the weight. If this value
                                       is not given, the driver cannot
                                       modify character weights.

            TC_IA_ABLE (0x0400)        Can generate italic characters by
                                       skewing.

            TC_UA_ABLE (0x0800)        Can generate underlined characters.

            TC_SO_ABLE (0x1000)        Can generate struck-out characters.

            TC_RA_ABLE (0x2000)        Can use raster fonts to generate
                                       text.

            TC_VA_ABLE (0x4000)        Can use vector fonts to generate
                                       text.

            TC_RESERVED (0x8000)       Reserved; must be zero.

   If a device claims to have an ability, it must have it for all fonts,
   whether realized by the device or provided by GDI.

   dpClip
   Specifies whether the device can clip output. This member can be one of
   the following values.

            Value              Meaning
            ---------------------------------------------------------------

            CP_NONE (0)        Device cannot clip.

            CP_RECTANGLE (1)   Device can output using a single rectangle.

            CP_REGION (2)      Device can output using a region (which may
                               be several rectangles).

   dpRaster
   Specifies raster abilities. This member can be a combination of the
   following values.

            Value                      Meaning
            ---------------------------------------------------------------

            RC_NONE (0x0000)           Device has no raster capabilities.

            RC_BITBLT (0x0001)         Can transfer bitmaps. The driver
                                       exports the BitBlt function.

            RC_BANDING (0x0002)        Requires banding support.

            RC_SCALING (0x0004)        Requires scaling support.

            RC_BITMAP64 (0x0008)       Supports bitmaps that are larger
                                       than 64K bytes.

            RC_GDI20_OUTPUT (0x0010)   Supports the Windows 2.x functions.
                                       The driver exports the ExtTextOut,
                                       GetCharWidth, and FastBorder
                                       functions.

            RC_GDI20_STATE (0x0020)    Supports state blocks in device
                                       contexts.

            RC_SAVEBITMAP (0x0040)     Saves bitmaps locally in shadow
                                       memory. Driver exports the
                                       SaveScreenBitmap function.

            RC_DI_BITMAP (0x0080)      Can get and set device-independent
                                       bitmaps (DIBs). The Driver exports
                                       the DeviceBitmapBits function.

            RC_PALETTE (0x0100)        Can do color-palette management.

            RC_DIBTODEV (0x0200)       Can transfer device-independent
                                       bitmaps directly to device. The
                                       driver exports the SetDIBitsToDevice
                                       function.

            RC_BIGFONT (0x0400)        Supports Windows 3.x fonts. If this
                                       value is not given, GDI ensures that
                                       the driver receives Windows 2.x
                                       fonts only.

            RC_STRETCHBLT (0x0800)     Can stretch and compress bitmaps
                                       while transferring the bitmap. The
                                       driver exports the StretchBlt
                                       function.

            RC_FLOODFILL (0x1000)      Can perform flood filling. The
                                       driver exports the FloodFill
                                       function.

            RC_STRETCHDIB (0x2000)     Can stretch and compress
                                       device-independent bitmaps while
                                       transferring the bitmap. The driver
                                       exports the StretchDIBits function.

            RC_OP_DX_OUTPUT (0x4000)   Can fill opaque rectangle and set
                                       character widths on calls to the
                                       ExtTextOut function.

            RC_DEVBITS (0x8000)        Supports device bitmaps. Driver
                                       exports the BitmapBits and
                                       SelectBitmap function.

   dpAspectX
   Specifies the relative width of a device pixel. This value, in the range
   1 to 1000, helps specify the device's aspect ratio.

   dpAspectY
   Specifies the relative height of a device pixel. This value, in the
   range 1 to 1000, helps specify the device's aspect ratio.

   dpAspectXY
   Specifies the relative diagonal width of a device pixel. This value, in
   the range 1 to 1000, helps specify the device's aspect ratio. It must be
   equal to the square root of the sum of the squares of the dpAspectX and
   dpAspectY members.

   dpStyleLen
   Specifies the minimum length of a dot generated by a styled pen. The
   length is relative to the width of a device pixel and should be given in
   the same units as the dpAspectX member. For example, if dpAspectX is 5
   and the minimum length required is 3 pixels, the dpStyleLen member
   should be 15.

   dpMLoWin
   Specifies the width and height of the metric (low resolution) window.
   Width is dpHorzSize*10; height is dpVertSize*10.

   dpMLoVpt
   Specifies the horizontal and vertical resolutions of the metric (low
   resolution) viewport. Horizontal is dpHorzRes; vertical is -dpVertRes.

   dpMHiWin
   Specifies the width and height of the metric (high resolution) window.
   Width is dpHorzSize*100; height is dpVertSize*100.

   dpMHiVpt
   Specifies the horizontal and vertical resolutions of the metric (high
   resolution) viewport. Horizontal is dpHorzRes; vertical is -dpVertRes.

   dpELoWin
   Specifies the width and height of the English (low resolution) window.
   Width is dpHorzSize*1000; height is dpVertSize*1000.

   dpELoVpt
   Specifies the horizontal and vertical resolutions of the English (low
   resolution) viewport. Horizontal is dpHorzRes*254; vertical is
   -dpVertRes*254.

   dpEHiWin
   Specifies the width and height of the English (high resolution) window.
   Width is dpHorzSize*10,000; height is dpVertSize*10,000.

   dpEHiVpt
   Specifies the horizontal and vertical resolutions of the English (high
   resolution) viewport. Horizontal is dpHorzRes*254; vertical is
   -dpVertRes*254.

   dpTwpWin
   Specifies the width and height of the twip window. There are 20 twips
   per 1 printer's point and 72 printer's points per inch. Width is
   dpHorzSize*14400; height is dpVertSize*14400.

   dpTwpVpt
   Specifies the horizontal and vertical resolutions of the twip viewport.
   Horizontal is dpHorzRes*254; vertical is -dpVertRes*254.

   dpLogPixelsX
   Specifies the number of pixels per logical inch along a horizontal line
   on the display surface. This is used to match fonts.

   dpLogPixelsY
   Specifies the number of pixels per logical inch along a vertical line on
   the display surface. This is used to match fonts.

   dpDCManage
   Specifies whether the device driver can manage multiple device contexts
   (DC). This member can be one of the following values.

            Value                    Meaning
            ---------------------------------------------------------------

            0x0000                   Driver allows multiple DCs. It creates
                                     a new PDEVICE for each DC that
                                     specifies a new device and filename
                                     pair, but uses the same PDEVICE for
                                     any subsequent DCs that specify the
                                     same device and filename pair.

            DC_SPDEVICE (0x0001)     Driver allows multiple DCs but it
                                     creates a new PDEVICE for each DC
                                     regardless of whether the device and
                                     filename pairs are the same.

            DC_1PDEVICE (0x0002)     Driver allows multiple DCs but only if
                                     all DCs have unique device and
                                     filename pairs. The driver creates a
                                     PDEVICE for each DC. The driver
                                     returns an error on any attempt to
                                     create a second DC with an existing
                                     device and filename pair.

            DC_IGNOREDFNP (0x0004)   Driver allows multiple DCs but only
                                     creates one PDEVICE. All DCs share the
                                     same PDEVICE regardless of the device
                                     and filename pairs.

            0x0006                   Driver allows only one DC. The driver
                                     returns an error on any attempt to
                                     create a second DC.

   The values 0x0003, 0x0005, and 0x0007 are not valid and must not be
   used.

   dpCaps1
   Specifies additional raster abilities. The member can be one of the
   following values.

            Value                     Meaning
            ---------------------------------------------------------------

            C1_TRANSPARENT (0x0001)   Performs BitBlt and StretchBlt
                                      functions with a transparent
                                      background.

            TC_TT_ABLE (0x0002)       Informs GDI that the driver is
                                      capable of producing TrueType as
                                      raster fonts. The driver must call
                                      the dmExtTextOut function to draw the
                                      raster font into the bitmap. The
                                      value is similar to TC_RA_ABLE.

   All other values are reserved.

   dpSpotSizeX
   Specifies the horizontal spot size for TrueType fonts on this device.

   dpSpotSizeY
   Specifies the vertical spot size for TrueType fonts on this device.

   dpPalColors
   Specifies the total number of simultaneous colors available in Windows
   3.x for palette-capable devices. Nonpalette-capable devices ignore this
   value.

   dpPalReserved
   Specifies the even number of reserved system colors available in Windows
   3.x for palette-capable devices. Nonpalette-capable devices ignore this
   value.

   dpPalResolution
   Specifies the palette resolution, which equals the number of bits going
   into video DACS. Nonpalette-capable devices ignore this value.


Comments

The dpText member requires that for each precision level that the precision
levels below it are also set. For example, the TC_SA_INTEGER value requires
that the the TC_SA_DOUBLE value be set, and the TC_SA_CONTIN value requires
that all three be set. Since it is required that the lowest precision level
of each ability be supported, no value is provided in dpText for the lowest
level of each ability.

The dpAspectX, dpAspectY, and dpAspectXY members specify the relative
width, height, and diagonal width of a device pixel and correspond directly
to the device's aspect ratio. For devices whose pixels do not have integral
diagonal widths, the member values can be multiplied by a convenient factor
to preserve information. For example, pixels on a device with a 1 to 1
aspect ratio have a diagonal width of 1.414. For good results, the aspect
members should be set to 100, 100, and 141, respectively. For numerical
stability, the member values should be kept under 1000.

The window/viewport pair members are the numerator and denominator of the
scale fraction used to correct for the device aspect ratio, and to set to a
fixed unit of measurement, either metric or English. These numbers should
be integers in the range of -32768 to 32767. When calculating these
constants, out-of-range values can be divided by some number to bring them
back into range as long as the corresponding window or viewport constant is
divided by the same number.

The dpRaster member is also used to indicate a scaling device. If the
RC_SCALING value is set, the device does graphics scaling. Certain devices
perform graphics at one resolution and text at another. Some applications
require that character cells be an integral number of pixels. If a device
reported that its graphics resolution was 75 dpi but its text resolution
was 300 dpi, then its character cells would not be an integral number of
pixels (since they were digitized at 300 dpi). To get around this problem,
GDI uses scaling devices. The device driver registers itself as a 300 dpi
device and all the graphics at 300 dpi are scaled to 75 dpi. Any device
that scales must have the RC_SCALING value set. Scaling always reduces the
resolution; it never increases it. GDI calls the Control function with
GETSCALINGFACTOR escape before output to a device. The scaling factor is a
shift count that is a power of two. Therefore, a scaling factor of 2 means
reduce by 4, and a scaling factor of 1 means reduce by 2.

The number of reserved colors on the palette is always 20, with 16
corresponding to the VGA colors and 4 special colors. Half of the reserved
palette colors are placed at the beginning and half at the end of the
palette.


See Also

Enable, Control, GETSCALINGFACTOR, PDEVICE



JUST_VALUE_STRUCT

    typedef struct tagJUST_VALUE_STRUCT {
        short nCharExtra;
        WORD  nCharCount;
        short nBreakExtra;
        WORD  nBreakCount;
    } JUST_VALUE_STRUCT;
The JUST_VALUE_STRUCT structures contains the values to use when justifying
text.


Members

   nCharExtra
   Specifies in font units the total extra space that must be distributed
   over nCharCount characters.

   nCharCount
   Specifies the number of characters over which the nCharExtra member is
   distributed.

   nBreakExtra
   Specifies in font units the total extra space that is distributed over
   nBreakCount break characters.

   nBreakCount
   Specifies the number of break characters over which nBreakExtra units
   are distributed.


See Also

SETALLJUSTVALUES



KERNPAIR

    typedef struct tagKERNPAIR {
        union {
            BYTE each [2];
            WORD both;
        } kpPair;
        short  kpKernAmount;
    } KERNPAIR;
The KERNPAIR structure contains the amount of kerning to apply to a given
pair of characters.


Members

   kpPair
   Specifies the character pair. This 2-byte member contains the character
   codes in the order in which the pair is to be printed.

   kpKernAmount
   Specifies the amount of kerning to apply to the character pair.


See Also

GETPAIRKERNTABLE



KERNTRACK

    typedef struct tagKERNTRACK {
        short ktDegree;
        short ktMinSize;
        short ktMinAmount;
        short ktMaxSize;
        short ktMaxAmount;
    } KERNTRACK;
The KERNTRACK structure contains information used to adapt kerning values
for scaled fonts.


Members

   ktDegree
   Specifies the degree.

   ktMinSize
   Specifies the minimum size.

   ktMinAmount
   Specifies the minimum amount.

   ktMaxSize
   Specifies the maximum size.

   ktMaxAmount
   Specifies the maximum amount.


See Also

GETTRACKKERNTABLE



LBRUSH

    typedef struct tagLBRUSH {
        short  lbStyle;
        long   lbColor;
        short  lbHatch;
        long   lbBkColor;
    } LBRUSH;
The LBRUSH structure contains style and color information for a brush.


Members

   lbStyle
   Specifies brush style. GDI requires that drivers support at least the
   following brush styles.

            Value            Meaning
            ---------------------------------------------------------------

            BS_SOLID (0)     Brush is a single solid or dithered color.

            BS_HOLLOW (1)    Brush has no color or pattern.

            BS_HATCHED (2)   Brush has a predefined pattern.

            BS_PATTERN (3)   Brush has the pattern as specified by a given
                             bitmap.

   lbColor
   Specifies a foreground color for brushes having BS_SOLID and BS_HATCHED
   values. For BS_HOLLOW and BS_PATTERN values, this member is zero. Brush
   colors are specified as physical colors. For palette-capable devices,
   this member specifies a physical-color index if the high-order byte is
   0xFF.

   lbHatch
   Specifies a brush pattern for brushes having BS_HATCHED style or a
   global memory handle for a bitmap for brushes having BS_PATTERN style.
   For BS_SOLID and BS_HOLLOW values, this member is zero.

   For BS_HATCHED brushes, this member specifies a brush pattern and can be
   one of the following values.

            Value           Description
            ---------------------------------------------------------------

            HS_HORIZONTAL   Horizontal hatch

            HS_VERTICAL     Vertical hatch

            HS_FDIAGONAL    45-degree upward hatch (left to right)

            HS_BDIAGONAL    45-degree downward hatch (left to right)

            HS_CROSS        Horizontal and vertical cross hatch

            HS_DIAGCROSS    45-degree cross hatch

   For BS_PATTERN style, this member is the global memory handle to a
   PBITMAP structure specifying the pattern.

   lbBkColor
   Specifies the background color for brushes having BS_HATCHED style.
   Brush colors are specified as physical colors. For palette-capable
   devices, this member specifies a physical color index if the high-order
   byte is 0xFF.


See Also

RealizeObject



LFONT

    typedef struct {
        short lfHeight;
        short lfWidth;
        short lfEscapement;
        short lfOrientation;
        short lfWeight;
        BYTE  lfItalic;
        BYTE  lfUnderline;
        BYTE  lfStrikeOut;
        BYTE  lfCharSet;
        BYTE  lfOutPrecision;
        BYTE  lfClipPrecision;
        BYTE  lfQuality;
        BYTE  lfPitchAndFamily;
        BYTE  lfFaceName [32];
    } LFONT;
The LFONT structure contains the logical attributes for a font.


Members

   lfHeight
   Specifies the height of the font in device units. If this member is
   greater than zero, the driver should choose a font whose cell height
   matches the given height. If this member is zero, the driver should
   choose a font having a reasonable default size. If this member is less
   than zero, the driver should choose a font whose character height (that
   is, cell height less internal leading) matches the absolute value of
   this member. In all cases, the driver should choose the largest font
   that does not exceed the requested height and, if there is no such font,
   choose the next smallest font available.

   lfWidth
   Specifies the average width of characters in the font in device units.
   If this member is zero, the driver should choose an available font whose
   digitization aspect ratio (the dfVertRes member of the FONTINFO
   structure) most closely matches the aspect ratio of the device (the
   dpAspectY member in the GDIINFO structure). When comparing fonts, the
   driver should compare the absolute values of the differences between the
   digitization aspect ratio and the device aspect ratio.

   lfEscapement
   Specifies the angle, counterclockwise from the x-axis in tenths of a
   degree, of the vector passing through the origin of all the characters
   in the string.

   lfOrientation
   Specifies the angle, counterclockwise from the x-axis in tenths of a
   degree, of the baseline of the character.

   lfWeight
   Specifies the weight of the font ranging from 1 to 1000, with 400 being
   the value for the standard font. If this member is zero, the driver
   should choose a reasonable weight.

   lfItalic
   Specifies whether the font is to be italic. If the low bit is set, the
   font is to be italic. All other bits must be zero.

   lfUnderline
   Specifies whether the font is to be underlined. If the low bit is set,
   the font is to be underlined. All other bits must be zero.

   lfStrikeOut
   Specifies whether the font is to be struck out. If the low bit is set,
   the font is to be struck out. All other bits must be zero.

   lfCharSet
   Specifies the character set to be used. It can be one of the following
   values.

            Value                   Meaning
            ---------------------------------------------------------------

            ANSI_CHARSET (0x00)     Indicates the ANSI character set.

            SYMBOL_CHARSET (0x02)   Indicates the Symbol character set.

            OEM_CHARSET (0xFF)      Indicates an OEM-specific character
                                    set. The characters and corresponding
                                    character codes depend on the computer.

   lfOutPrecision
   Specifies the required output precision for text. This member can have
   one of the following values.

            Value                         Meaning
            ---------------------------------------------------------------

            OUT_DEFAULT_PRECIS (0x00)     Chooses a reasonable font.

            OUT_STRING_PRECIS (0x01)      Chooses the font whose size
                                          (height and width) most closely
                                          matches the requested size. The
                                          driver may disregard the
                                          requested orientation and
                                          escapement, but other attributes
                                          must match.

            OUT_CHARACTER_PRECIS (0x02)   Chooses the font whose size
                                          (height and width) most closely
                                          matches the requested size. The
                                          driver may disregard the
                                          requested orientation, but other
                                          attributes must match.

            OUT_STROKE_PRECIS (0x03)      Chooses a font whose attributes
                                          exactly match the requested
                                          attributes.

   lfClipPrecision
   Specifies the required clipping precision for text. This member can be
   one of the following values.

            Value                          Meaning
            ---------------------------------------------------------------

            CLIP_DEFAULT_PRECIS (0x00)     Chooses a reasonable font.

            CLIP_CHARACTER_PRECIS (0x01)   Chooses a font that allows
                                           clipping of individual
                                           characters. The driver must be
                                           able to clip a character if any
                                           portion of it lies outside the
                                           clipping rectangle.

            CLIP_STROKE_PRECIS (0x02)      Chooses a font that allows
                                           clipping of portions of a
                                           character. The driver must be
                                           able to clip any portion of a
                                           character that lies outside the
                                           clipping rectangle.

   lfQuality
   Specifies the required quality for text. This member can have one of the
   following values.

            Value                    Meaning
            ---------------------------------------------------------------

            DEFAULT_QUALITY (0x00)   Chooses a reasonable font.

            DRAFT_QUALITY (0x01)     Chooses a font that generates the most
                                     efficient, speediest output. The
                                     driver can sacrifice appearance if a
                                     speedier font has lower quality. GDI
                                     synthesizes bold, italic, underline,
                                     and strikethrough characters if needed.

            PROOF_QUALITY (0x02)     Chooses a font that generates the
                                     highest-quality output. The driver
                                     should sacrifice speedy output if a
                                     slower font has higher quality. The
                                     driver should sacrifice output
                                     precision if a font that does not
                                     exactly match the requested attributes
                                     (such as size) is a higher quality.
                                     GDI synthesizes bold, italic,
                                     underline, and strikethrough
                                     characters if needed.

   lfPitchAndFamily
   Specifies the font pitch and font family. This member is a combination
   of one pitch and one family value. The pitch value can be any one of the
   following values.

            Value                   Meaning
            ---------------------------------------------------------------

            DEFAULT_PITCH (0x00)    Chooses a reasonable font.

            FIXED_PITCH (0x01)      Chooses a fixed-pitch font.

            VARIABLE_PITCH (0x02)   Chooses a variable-pitch font.

   The font family, which describes in a general way the look of a font,
   can be any one of the following values.

            Value                  Meaning
            ---------------------------------------------------------------

            FF_DONTCARE (0x00)     Chooses a reasonable font.

            FF_ROMAN (0x10)        Chooses a variable-pitch font with
                                   serifs.

            FF_SWISS (0x20)        Chooses a variable-pitch fonts without
                                   serifs.

            FF_MODERN (0x30)       Chooses a fixed-pitch font.

            FF_SCRIPT (0x40)       Chooses a cursive or script font.

            FF_DECORATIVE (0x50)   Chooses a novelty font.

   lfFaceName
   Specifies a null-terminated string specifying the name of the font. The
   driver should choose a font having the given name. If the string is
   empty (the first byte is zero), the driver should choose a reasonable
   font. The string, including the null terminator, does not exceed 32
   bytes.


See Also

EngineRealizeFont, RealizeObject



LPEN

    typedef struct tagLPEN {
        long  lopnStyle;
        POINT lopnWidth;
        long  lopnColor;
    } LPEN;
The LPEN structure specifies a logical pen. Pens are used to draw lines and
borders.


Members

   lopnStyle
   Specifies the pen style. GDI requires that drivers support at least the
   following pen styles.

            Value                Meaning
            ---------------------------------------------------------------

            LS_SOLID (0)         Draws solid lines.

            LS_DASHED (1)        Draws dashed lines.

            LS_DOTTED (2)        Draws dotted lines.

            LS_DOTDASHED (3)     Draws lines with alternating dots and
                                 dashes.

            LS_DASHDOTDOT (4)    Draws lines with a repeating pattern of a
                                 dash followed by two dots.

            LS_NOLINE (5)        Nothing is drawn.

            LS_INSIDEFRAME (6)   Creates a pen in which a line is drawn
                                 inside the frame of ellipses and
                                 rectangles. If the width of the pen is
                                 greater than 1 and the pen style is
                                 PS_INSIDEFRAME, the line is drawn inside
                                 the frame of all primitives except
                                 polygons and polylines; the pen is drawn
                                 with a logical (dithered) color if the pen
                                 color does not match an available RGB
                                 value. The PS_INSIDEFRAME style is
                                 identical to PS_SOLID if the pen width is
                                 less than or equal to 1.

   lopnWidth
   Specifies a POINT structure whose x member contains the pen width in
   device units. A zero-width pen is drawn with the system's smallest
   width. Negative-width pens have no width and are NULL pens. The y member
   is ignored.

   lopnColor
   Specifies the color for the pen. Pen colors are specified as physical
   colors. For palette-capable devices, the value is a color index if the
   high byte is 0x0FFH.


See Also

RealizeObject



ORIENT

    typedef struct tagORIENT {
        short Orientation;
        short Reserved[4];
    } ORIENT;
The ORIENT structure contains information about the paper orientation, such
as whether it is portrait or landscape.


Members

   Orientation
   Specifies the paper orientation. If it is 1, the orientation is
   portrait. If it is 2, the orientation is landscape.

   Reserved
   Not used; must be zero.


See Also

GETSETPRINTORIENT



PATH_INFO

    typedef struct tagPATH_INFO {
        short     RenderMode;
        BYTE      FillMode;
        BYTE      BkMode;
        LPEN      Pen;
        LBRUSH    Brush;
        DWORD     BkColor;
    } PATH_INFO;
The PATH_INFO structure contains information about a path.


Members

   RenderMode
   Specifies how to draw the path. This member can have one of the
   following values.

            Value            Meaning
            ---------------------------------------------------------------

            NO_DISPLAY (0)   Path not drawn.

            OPEN (1)         Drawn as an open polygon.

            CLOSED (2)       Drawn as a closed polygon.

   FillMode
   Specifies how to fill the path. This member can have one of the
   following values.

            Value           Meaning
            ---------------------------------------------------------------

            ALTERNATE (1)   Filled using the alternate-fill method.

            WINDING (2)     Filled using the winding-fill method.

   BkMode
   Specifies how to use existing colors when filling the path. This member
   is equivalent to the BkMode member of the DRAWMODE structure. Drivers
   that encounter a BkMode of zero should assume TRANSPARENT value and
   ignore BkColor.

   Pen
   Specifies which pen to use to draw the path. If RenderMode is set to the
   NO_DISPLAY value, the pen is ignored.

   Brush
   Specifies which brush to use to draw the path. If RenderMode is set to
   the NO_DISPLAY or OPEN values, the pen is ignored.

   BkColor
   Specifies which background color to use when filling the path. This
   member is equivalent to the BkColor member of the DRAWMODE structure.


See Also

END_PATH



PATTERNRECT

    typedef struct tagPATTERNRECT {
        POINT prPosition;
        POINT prSize;
        WORD prStyle;
        WORD prPattern;
    } PATTERNRECT;
The PATTERNRECT structure contains information about a pattern, gray scale,
or black rectangle to be created by a Hewlett-Packard PCL driver.


Members

   prPosition
   Specifies a POINT structure identifying the upper-left corner of the
   rectangle.

   prSize
   Specifies a POINT structure identifying the lower-right corner of the
   rectangle.

   prStyle
   Specifies the type of pattern. It can be one of the following values.

            Value   Meaning
            ---------------------------------------------------------------

            0       Black rule

            1       White rule

            2       Gray scale

            3       Device defined

   prPattern
   Specifies the percent of gray for a gray scale pattern or specifies one
   of six patterns for device-defined patterns. This member is ignored if
   the value is zero (black rule).


See Also

DRAWPATTERNRECT



PBITMAP

    typedef struct tagPBITMAP {
        short bmType;
        short bmWidth;
        short bmHeight;
        short bmWidthBytes;
        BYTE  bmPlanes;
        BYTE  bmBitsPixel;
        long  bmBits;
        long  bmWidthPlanes;
        long  bmlpPDevice;
        short bmSegmentIndex;
        short bmScanSegment;
        short bmFillBytes;
        short reserved1;
        short reserved2;
    } PBITMAP;
A PBITMAP structure specifies the dimensions, attributes, and bits of a
physical bitmap.


Members

   bmType
   Specifies a physical bitmap. The member must be set to zero.

   bmWidth
   Specifies the width of the bitmap in pixels.

   bmHeight
   Specifies the height of the bitmap in raster lines.

   bmWidthBytes
   Specifies the number of bytes in each raster line of this bitmap. The
   number of bytes must be even; all raster lines must be aligned on 16-bit
   boundaries.

   bmPlanes
   Specifies the number of color planes.

   bmBitsPixel
   Specifies the number of color bits for each pixel.

   bmBits
   Points to an array of bits specifying the pixels of the bitmap. The
   array must be aligned on a 16-bit boundary.

   bmWidthPlanes
   Specifies the size in bytes of each color plane. It is equal to the
   product of bmWidthBytes*bmHeight.

   bmlpPDevice
   Points to the PDEVICE structure specifying the device for which this
   bitmap is compatible.

   bmSegmentIndex
   Specifies the segment or selector offset for segments in the bitmap
   array. If the bitmap is less than 64K bytes, this member is zero.

   bmScanSegment
   Specifies the number of raster lines contained in each segment of the
   bitmap array. If the bitmap is less than 64K bytes, this member is zero.

   bmFillBytes
   Specifies the number of extra bytes in each segment. Graphics-device
   interface (GDI) allocates storage for the bitmap array in 16-byte
   multiples.

   reserved1
   Reserved; do not use.

   reserved2
   Reserved; do not use.


Comments

If the bitmap bits exceed 64K bytes, GDI allocates a two or more segments
to store the bitmap. In such cases, the bmScanSegment member specifies the
number of raster lines stored in each segment, with bmFillBytes specifying
any additional bytes needed to round the segment size out to a multiple of
16; no segment contains more than 64K bytes. The total number of segments
is equal to the quotient of bmHeight divided by bmScanSegment rounded up by
one if the remainder is not zero. The selector (or segment address) for
each segment is a multiple of bmSegmentIndex.

GDI stores the bits in the bitmap array as raster lines, with the raster
line representing the top of the bitmap stored first. If the bitmap has
more than one plane, GDI stores the first raster lines for all planes at
the beginning of the array, stores the second raster lines next, and so on.
The following shows the layout for a 4-plane bitmap:

    Plane 0, first raster line
    Plane 1, first raster line
    Plane 2, first raster line
    Plane 3, first raster line
    Plane 0, second raster line
            .
            .
            .
    Plane 0, last raster line
    Plane 1, last raster line
    Plane 2, last raster line
    Plane 3, last raster line
If the bitmap array exceeds 64K bytes, GDI splits the raster lines across
several segments but retains the storage order, giving the first raster
lines in the first segment and the last raster lines in the last segment.
When GDI splits the raster lines, it ensures that matching raster lines
from the various planes are always in the same segment. If necessary, GDI
leaves a number of empty bytes (as specified by bmFillBytes) at the end of
the segment to round out the segment size to a multiple of 16.



PDEVICE

    typedef struct tagPDEVICE {
        short pdType;
    } PDEVICE;
The PDEVICE structure contains information that a graphics driver uses to
identify a device and the current state of the device. The size and content
of the structure depends entirely on the driver. For example, the structure
may include the current pen, the current position, the communication port
of a particular device, and other state information. However, the first
member in every PDEVICE structure must be pdType.


Members

   pdType
   Specifies the device type. If this member is nonzero, the structure
   identifies a device and all remaining members are driver specific. If
   this member is zero, the structure identifies a memory bitmap and all
   remaining members must be identical to a PBITMAP structure.


Comments

GDI allocates space for the PDEVICE structure when it calls the Enable
function to initialize a device driver. The size of this structure must be
specified in the dpDEVICEsize member of the GDIINFO structure.


See Also

Enable



POINT

    typedef struct tagPOINT {
        short   x;
        short   y;
    } POINT;
The POINT structure contains the x- and y-coordinates of a point.


Members

   x
   Specifies the x-coordinate of a point.

   y
   Specifies the y-coordinate of a point.


See Also

GETPHYSPAGESIZE, GETPRINTINGOFFSET



RECT

    typedef struct tagRECT {
        short left;
        short top;
        short right;
        short bottom;
    } RECT;
The RECT structure contains the coordinates of the top-left and
bottom-right corners of a rectangle.


Members

   left
   Specifies the x-coordinate of the top-left corner of the rectangle.

   top
   Specifies the y-coordinate of the top-left corner of the rectangle.

   right
   Specifies the x-coordinate of the bottom-right corner of the rectangle.

   bottom
   Specifies the y-coordinate of the bottom-right corner of the rectangle.


See Also

Output(OS_RECTANGLE)



RGBQUAD

    typedef struct tagRGBQUAD {
        BYTE rgbBlue;
        BYTE rgbGreen;
        BYTE rgbRed;
        BYTE rgbReserved;
    } RGBQUAD;
The RGBQUAD structure specifies a logical color or a 16-bit color index. A
logical color specifies the color desired by an application. A color index
indirectly specifies a logical color by identifying a color in an array (or
table) of colors.


Members

   rgbBlue
   Specifies the intensity of blue. It must be a value in the range 0 (no
   blue) to 255 (brightest blue).

   rgbGreen
   Specifies the intensity of green. It must be a value in the range 0 (no
   green) to 255 (brightest green).

   rgbRed
   Specifies the intensity of red. It must be a value in the range 0 (no
   red) to 255 (brightest red).

   rgbReserved
   Specifies whether the RGBQUAD structure specifies an RGB color or a
   16-bit color index. If this member is zero, this is an RGB color. If
   this member is 0xFF, then the low 16 bits (rgbBlue and rgbGreen members)
   is a color index, not an RGB color.


Comments

When the colors are at minimum intensity (0,0,0), the result is black; when
at maximum intensity (255,255,255), the result is white; and when at half
intensity (127,127,127), the result is gray.

Primary colors can be combined to form new colors. For example, solid red
(0,0,255) and blue (255,0,0) can form purple (255,0,255). If a device
cannot display all the possible RGB color combinations, the device driver
must map given RGB color values to colors the device can display. For
example, in a black-and-white display with only one bit per pixel, the
driver uses a cutoff intensity at which all the RGB values above the
intensity are white and all below are black. One method used to compute the
cutoff intensity is to add the individual color intensities according to
the following formula:

    ((5*rgbGreen+3*rgbRed+rgbBlue)+4)>>3
If the result is greater than 128, then all the RGB values above that
intensity will be white, and those below it will be black.



TEXTMETRIC

    typedef struct tagTEXTMETRIC {
        short  tmHeight;
        short  tmAscent;
        short  tmDescent;
        short  tmInternalLeading;
        short  tmExternalLeading;
        short  tmAveCharWidth;
        short  tmMaxCharWidth;
        short  tmWeight;
        BYTE   tmItalic;
        BYTE   tmUnderlined;
        BYTE   tmStruckOut;
        BYTE   tmFirstChar;
        BYTE   tmLastChar;
        BYTE   tmDefaultChar;
        BYTE   tmBreakChar;
        BYTE   tmPitchAndFamily;
        BYTE   tmCharSet;
        short  tmOverhang;
        short  tmDigitizedAspectX;
        short  tmDigitizedAspectY;
    } TEXTMETRIC;
The TEXTMETRIC structure contains a list of the basic metrics of a physical
font.


Members

   tmHeight
   Specifies the height of the character cell. This member is equal to the
   sum of the tmAscent and tmDescent members.

   tmAscent
   Specifies the ascent of the character cell, that is, height of the cell
   measured from the baseline.

   tmDescent
   Specifies the descent of the character cell, that is, the height of the
   cell measured from the baseline to the bottom of the cell.

   tmInternalLeading
   Specifies the amount of internal leading. It is equal to the difference
   between the cell height (as expressed by the tmHeight member) and the
   maximum height of any character in the font (excluding the height of
   accent marks).

   tmExternalLeading
   Specifies the recommended amount of leading for the font.

   tmAveCharWidth
   Specifies the average width of characters in the font (loosely defined
   as the width of the letter X).

   tmMaxCharWidth
   Specifies the maximum width of any character in the font.

   tmWeight
   Specifies the weight of the font.

   tmItalic
   If nonzero, specifies an italic font.

   tmUnderlined
   If nonzero, specifies an underlined font.

   tmStruckOut
   If nonzero, specifies a font that has been struck through.

   tmFirstChar
   Specifies the value of the first character defined in the font.

   tmLastChar
   Specifies the value of the last character defined in the font.

   tmDefaultChar
   Specifies the value of the character that is to be substituted for
   characters that are not in the font.

   tmBreakChar
   Specifies the value of the character that is to be used to define word
   breaks for text justification.

   tmPitchAndFamily
   Specifies the font pitch and font family. This member is a combination
   of one pitch and one family value. The pitch value can be any one of the
   following values.

            Value                   Meaning
            ---------------------------------------------------------------

            DEFAULT_PITCH (0x00)    Chooses a reasonable font.

            FIXED_PITCH (0x01)      Chooses a fixed-pitch font.

            VARIABLE_PITCH (0x02)   Chooses a variable-pitch font.

   The font family, which describes in a general way the look of a font,
   can be any one of the following values.

            Value                  Meaning
            ---------------------------------------------------------------

            FF_DONTCARE (0x00)     Chooses a reasonable font.

            FF_ROMAN (0x10)        Chooses a variable-pitch font with
                                   serifs.

            FF_SWISS (0x20)        Chooses a variable-pitch fonts without
                                   serifs.

            FF_MODERN (0x30)       Chooses a fixed-pitch font.

            FF_SCRIPT (0x40)       Chooses a cursive or script font.

            FF_DECORATIVE (0x50)   Chooses a novelty font.

   tmCharSet
   Specifies the character set of the font. It can be one of the following
   values.

            Value                   Meaning
            ---------------------------------------------------------------

            ANSI_CHARSET (0x00)     Indicates the ANSI character set.

            SYMBOL_CHARSET (0x02)   Indicates the Symbol character set.

            OEM_CHARSET (0xFF)      Indicates an OEM-specific character
                                    set. The characters and corresponding
                                    character codes depend on the computer.

   tmOverhang
   Specifies the amount of additional, synthesized width of a character or
   character string. This member may be is nonzero if the driver
   synthesizes character attributes, such as bold or italic, by modifying
   an existing font.

   tmDigitizedAspectX
   Specifies the horizontal aspect ratio for which this font was designed.
   This member is equal to the dfHorizRes member of the FONTINFO structure.

   tmDigitizedAspectY
   Specifies the vertical aspect ratio for which this font was designed.
   This member is equal to the dfVertRes member of the FONTINFO structure.


Comments

GDI makes a string bold by expanding the intracharacter spacing and
overstriking with an offset; the overhang is the distance by which the
overstrike is offset. GDI italicizes a font by skewing the string, and the
overhang is the amount the top of the font is skewed past the bottom of the
font.


See Also

EnumDFonts



TEXTXFORM

    typedef struct tagTEXTXFORM {
        short  txfHeight;
        short  txfWidth;
        short  txfEscapement;
        short  txfOrientation;
        short  txfWeight;
        char   txfItalic;
        char   txfUnderline;
        char   txfStrikeOut;
        char   txfOutPrecision;
        char   txfClipPrecision;
        short  txfAccelerator;
        short  txfOverhang;
    } TEXTXFORM;
The TEXTXFORM structure contains information describing the actual
appearance of text as displayed by the device. The StrBlt and ExtTextOut
functions check the the TEXTXFORM structure to determine what additional
actions are required to generate the desired text from the specified
physical font.


Members

   txfHeight
   Specifies the height of characters (ascent + descent) in device units.

   txfWidth
   Specifies the width in device units of the bounding box of the letter X.

   txfEscapement
   Specifies the angle in tenths of a degree counterclockwise from the
   x-axis of the vector passing through the origin of all the characters in
   the string.

   txfOrientation
   Specifies the angle in tenths of a degree counterclockwise from the
   x-axis of the baseline of the character.

   txfWeight
   Specifies the weight of the font ranging from 1 to 1000, with 400 being
   the value for the standard font.

   txfItalic
   Specifies whether the font is to be italic. If the low bit is set, the
   font is to be italic. All the other bits must be zero.

   txfUnderline
   Specifies whether the font is to be underlined. If the low bit is set,
   the font is to be underlined. All the other bits must be zero.

   txfStrikeOut
   Specifies whether to strike out the font. If the low bit is set, the
   font is to be struck out. All the other bits must be zero.

   txfOutPrecision
   Specifies the required output precision for text. This member can have
   one of the following values.

            Value                         Meaning
            ---------------------------------------------------------------

            OUT_DEFAULT_PRECIS (0x00)     Chooses a reasonable font.

            OUT_STRING_PRECIS (0x01)      Chooses the font whose size
                                          (height and width) most closely
                                          matches the requested size. The
                                          driver may disregard the
                                          requested orientation and
                                          escapement, but other attributes
                                          must match.

            OUT_CHARACTER_PRECIS (0x02)   Chooses the font whose size
                                          (height and width) most closely
                                          matches the requested size. The
                                          driver may disregard the
                                          requested orientation, but other
                                          attributes must match.

            OUT_STROKE_PRECIS (0x03)      Chooses a font whose attributes
                                          exactly match the requested
                                          attributes.

   txfClipPrecision
   Specifies the required clipping precision for text. This member can have
   one of the following values.

            Value                          Meaning
            ---------------------------------------------------------------

            CLIP_DEFAULT_PRECIS (0x00)     Chooses a reasonable font.

            CLIP_CHARACTER_PRECIS (0x01)   Chooses a font that allows
                                           clipping of individual
                                           characters. The driver must be
                                           able to clip a character if any
                                           portion of it lies outside the
                                           clipping rectangle.

            CLIP_STROKE_PRECIS (0x02)      Chooses a font that allows
                                           clipping of portions of a
                                           character. The driver must be
                                           able to clip any portion of a
                                           character that lies outside the
                                           clipping rectangle.

   txfAccelerator
   Specifies the requested text modifications using the same format as the
   the dpText member in the GDIINFO structure. Each bit in this member is
   set if the corresponding ability is required to modify the physical font
   into the requested font.

   txfOverhang
   Specifies same information as the tmOverhang member in the TEXTMETRIC
   structure. This member is set by the device for device-realized fonts
   and is in device units. GDI uses additional overhang if it makes the
   font bold.


Comments

Although most of the members in the TEXTXFORM structure correspond to the
members in the LFONT structure, these members may not always exactly match.
For example, if the logical font specified a 19-unit font at string
precision and the closest available was a 9-unit font on a device capable
of doubling, then the txfHeight member in the structure is 18.

A driver should check the dpText member in its GDIINFO structure to
determine whether the driver can carry out the requested text
modifications. In particular, the driver should check the bitwise
difference between the txfAccelerator member and the dpText member to
determine what abilities it should simulate. If the driver can not carry
out the modifications, GDI is responsible for simulating the required
modifications.


See Also

EngineRealizeFont, ExtTextOut, StrBlt

Chapter 13  Font Files

Microsoft Windows font files contain the font glyph information the
graphics-device interface (GDI) or a graphics driver needs to draw text on
a given device. The font-file format supports both raster and vector fonts.
Also, Windows extended the font file format for Windows 3.x to increase the
maximum size of a font file beyond 64K bytes.

This chapter does not describe the format of Microsoft TrueType font files.
For more information about TrueType fonts, see the Microsoft Windows
Installation and Update Guide.


13.1 Font Files

Font files consist of a font header, a character-width table, and the glyph
data. The font header has the following format:

    typedef struct tagFONTFILEHEADER {
        short dfVersion;
        long  dfSize;
        char  dfCopyright[60];
        FONTINFO dffi;
    } FONTFILEHEADER;
The dfVersion member specifies the version of Windows for which the font
was designed. For example, for fonts designed for Windows 3.1, this member
is set to 0x30A. The dfSize member specifies the size in bytes of the
entire font file and the dfCopyright member contains the font designer's
null-terminated copyright string. The rest of the FONTFILEHEADER structure
is identical to the FONTINFO structure.

The character-width table for the font file immediately follows the
FONTFILEHEADER structure. The format of the table depends on the font-file
version and whether the font contains raster or vector glyphs. For more
information about the character-width table formats, see the FONTINFO
structure in Chapter 12, Graphics-Driver Types and Structures.

The glyph data usually follows the character-width table. However, the
dfBitsOffset member in the FONTINFO structure always specifies the offset
from the beginning of the file to the start of the data. The data
represents either raster or vector glyphs. The following sections describe
these formats in detail.


13.2 Raster Glyphs

A raster-font file contains individual bitmaps for each glyph in the file.
Each glyph bitmap is stored as a contiguous set of bytes. The first byte
contains the first eight bits of the first scan line (that is, the top line
of the character). The second byte contains the first eight bits of the
second scan line. This continues until what amounts to a first column is
completely defined.

The following byte contains the next eight bits of the first scan line,
padded with zeros on the right if necessary (and so on, down through the
second column). If the glyph is quite narrow, each scan line is covered by
one byte, with bits set to zero as necessary for padding. If the glyph is
very wide, a third or even fourth set of bytes can be present.

All bitmaps must be stored contiguously and arranged in ascending order,
that is, the bitmap for the first character is first and the last character
is last.

The following example shows the the bytes that form a 12 x 14 pixel
character.

    00 06 09 10 20 20 20 3F 20 20 20 00 00 00   /* first column */
    00 00 00 80 40 40 40 C0 40 40 40 00 00 00   /* second column */
Notice that in the second set of bytes, the second digit corresponds to the
thirteenth through sixteenth pixels on the right side of the character.
Since the character is only 12 bits wide, these bits should always be zero.

The resulting character looks like this:

     ............
     .....**.....
     ....*..*....
     ...*....*...
     ..*......*..
     ..*......*..
     ..*......*..
     ..********..
     ..*......*..
     ..*......*..
     ..*......*..
     ............
     ............
     ............

13.3 Vector Glyphs

A vector-font file contains a series of vectors for each glyph in the file.
Each vector is a signed coordinate pair specifying the amount to move the
pen relative to the current position. The size of each coordinate depends
on the size of the font. If either the dfPixHeight or dfMaxWidth members in
the FONTINFO structure is greater than 128, the coordinates are stored as
2-byte quantities; otherwise, they are stored as 1-byte quantities.

Each coordinate pair may be preceded by a value indicating whether the
pen's tip should be lifted before moving. The tip-up value depends on the
size of the coordinates. For 1-byte coordinates, the value is -128 (0x80)
and for 2-byte coordinates, the value is -32768 (0x8000).

To draw the a vector glyph, a device moves the pen to the character cell
origin. The origin is assumed to be at the upper-left corner of the
character cell. The device moves the pen to new positions as specified by
each vector. Positive coordinates move the pen down and to the right;
negative coordinates up and to the left. If the tip-up value is given, the
tip stays up for the subsequent coordinate pair only. The number of vectors
for a glyph depends on the glyph. The number of bytes in the vector series
is equal to the difference between the offsets from the character-width
table for the given character and the next character.

The following series of vectors draws an exclamation point:

    -128,   /* pen tip up */
     5,   4,
    -1,   2,
     1,  12,
     1, -12,
    -1,  -2,
    -128,   /* pen tip up */
     0,   2,
     0,   6,
    -128,   /* pen tip up */
     0,  11,
    -1,   1,
     1,   1,
     1,  -1,
    -1,  -1
If the character is drawn in a 10 x 24 character cell, the resulting
character looks like this:

     ..........
     ..........
     ..........
     ....*.....
     ....*.....
     ...***....
     ...***....
     ...***....
     ...***....
     ...***....
     ...***....
     ...***....
     ....*.....
     ....*.....
     ....*.....
     ....*.....
     ....*.....
     ....*.....
     ..........
     ..........
     ..........
     ..........
     ....*.....
     ...*.*....
     ....*.....
Chapter 14  Setup Information Files

The Microsoft Windows Setup information (files with an .INF extension)
provides the data that the Windows Setup program and Control Panel need to
install device drivers and virtual devices from disk.


14.1 About the Information Files

An information file is an ASCII text file that contains lists of disk
names, filenames, and related information that Setup and Control Panel use
to install device drivers and virtual devices. The file lists the names of
the installation disks, the device driver and virtual-device files, and all
dependent files that must be installed with the device drivers and virtual
devices.

Windows supplies default information files, named SETUP.INF and
CONTROL.INF, that list all drivers and related files. Setup uses these
files to install Windows, then stores the files in the Windows SYSTEM
directory so that Setup and Control Panel can read the files whenever the
user requests changes to the Windows configuration. Setup and Control Panel
use information in SETUP.INF and CONTROL.INF to let the user replace the
existing display, network, keyboard, and pointing-device drivers or to
install new printer drivers and fonts.

IMPORTANT  Never modify or replace the SETUP.INF or CONTROL.INF files.

Setup and Control Panel can also read OEMSETUP.INF information files to
install drivers that are not listed in SETUP.INF or CONTROL.INF. Setup and
Control Panel search for and read OEMSETUP.INF files whenever the user
requests the installation of unlisted drivers.

To install a driver from an OEM distribution disk, Setup or Control Panel
reads the lists of available drivers from the OEMSETUP.INF file and
displays this list to the user. When the user selects a driver, Setup or
Control Panel copies the driver and its associated files from the specified
distribution disks to the WINDOWS directory. Setup or Control Panel also
updates settings in the initialization files, such as WIN.INI and
SYSTEM.INI, by copying the new settings to the sections specified in the
information file.

Setup also copies OEMSETUP.INF files to the WINDOWS directory (for network
installations), or the SYSTEM directory (for nonnetwork installations) as
OEMx.INF. The x is a unique number. This process applies to the
installation of pointing devices, keyboards, and screen displays.


14.1.1 Information-File Syntax

Information files consist of one or more sections. Each section starts with
a section name, enclosed in brackets ([]), and contains one or more entries
(or information lines). A setting specifies the names, settings, and
sections that Setup and Control Panel use to identify and install drivers.

Each setting consists of one or more parameters, separated by commas (,). A
parameter specifies information such as the driver filename, driver
description, and the filename of associated files. In some cases, a
parameter specifies the name of a related section in the information file
that contains additional settings for the driver.

The following example illustrates the general syntax of information files:

    ; Example OEMSETUP.INF information file

    [disks]
        1 =. ,"Generic Printer Distribution Disk",disk1

    [io.device]
        1:TTY.DRV,"Generic / Text Only","DEVICESPECIFIC"

    [io.dependent]
        tty.drv = 1:tty.hlp
This example has three sections, [disks], [io.device], and [io.dependent],
that specify the files that Control Panel needs to install the generic
printer, TTY.DRV, and its associated help file. Information files can
include comments, but each comment must be preceded by a semicolon (;).

Whenever a filename is given in an information file it must have the form:

    id:filename
In this example, id is a valid disk identifier and filename is a valid
MS-DOS filename. A valid disk identifier is any identifier given in the
[disks] section of the information file. This section names the
distribution disk or disks and assigns disk identifiers.


14.1.2 Information Files for Display Drivers

The OEMSETUP.INF file for a display driver must contain a [display]
section. The file may also contain the following sections:

    [disks]
    [sysfonts]
    [fixedfonts]
    [oemfonts]
    [fonts]
Display drivers often have many dependent files such as files for standard-
and 386 enhanced-mode grabbers, startup logo modules, and system, fixed,
OEM, and user fonts. These sections fully specify the files to be installed
with the display driver.

When installing a display driver, Setup selects fonts by matching the
aspect ratio of the display to that of the font. For configurations using
other than code page 437, Setup asks MS-DOS for code-page information and
selects an OEM font from the [codepages] section based on that information.
Because only MS-DOS version 3.30 and higher supports the call for code-page
information, Setup may (depending on the MS-DOS version) rely on the
defxlat setting in the [data] section to retrieve code-page information.


14.1.3 Information Files for Printer Drivers

The OEMSETUP.INF file for a printer driver must contain an [io.device]
section. The file may also contain the following sections:

    [io.dependent]
    [disks]
    [fonts]
Although Control Panel can install a printer without an information file,
Control Panel requires the file if the driver has any related files such as
help and font files.

If the user requests the installation of a printer that is not listed in
the CONTROL.INF file, Control Panel searches for printer drivers on the
specified disk. It will also look for an OEMSETUP.INF file and use that
information to copy any additional files the printer driver needs. Although
each entry in the [io.device] section contains a description for the
driver, Control Panel does not use this description. Instead, it scans for
and displays the description field in the driver's executable file.


14.1.4 Information Files for Network Installation

The OEMSETUP.INF file for a network driver contains [disks] and [networks]
sections, and a corresponding [netname.versions] section. The
[netname.versions] section specifies more sophisticated control over how
the network is installed.


14.2 Information-File Section Reference

The following is an alphabetical listing of the information-file sections
for installing fonts and display, printer, keyboard, and mouse device
drivers.

[data]

    [data]
    DataName = Value
The [data] section specifies default information if the user does not
explicitly specify installation options.


Parameters

   DataName
   Specifies a unique name identifying a default value. Setup recognizes
   the following settings:

Setting     Description
---------------------------------------------------------------------------

defkeydll   Specifies the default language-specific keyboard library. The
            corresponding value must be one of the keyboard-library names
            specified in the [keyboard.tables] section.

version     Specifies the Windows version for which the OEMSETUP.INF file
            is intended. The corresponding value can be version number
            having the form x.xx. If an information file is marked as a
            3.1, Setup will not attempt to translate filenames to preserve
            compatibility with Windows 3.0 driver disks.

   Value
   Specifies the default value associated with the name.


Example

This example shows a [data] section containing default definitions for the
code page and language-specific keyboard library:

    [data]
    defkeydll=ussrdll
    version=3.1

See Also

[codepages], [keyboard.tables]



[disks]

    [disks]
    ID = .,"Text_Description"
The [disks] section specifies the disk identifiers associated with each
file in the information file. The section also maps each disk identifier to
an installation disk, and to a specific directory on the installation disk.


Parameters

   ID
   Specifies a logical-disk identifier. It must be a single decimal digit
   (1-9), or uppercase letter (A-Z). No more than 35 identifiers are
   permitted. The logical-disk identifier zero (0) is reserved for use by
   the Setup program.

   Text_Description
   Specifies an ASCII string identifying the physical disk. Setup and
   Control Panel use this parameter to prompt the user to insert the
   appropriate disk before copying files. This parameter must be enclosed
   in double quotation marks (").


Comments

The period and comma (.,) immediately preceding the Text_Description
parameter are required.


Example

This example defines two logical-disk identifiers: 1 and 2. Files
associated with identifier 1 are in the root directory of the disk labelled
Disk #1. Files associated with identifier 2 are in the root directory of
the disk labelled Disk #2.

    [disks]
    1 =.,  "Disk #1"
    2 =.,  "Disk #2"


[display]

    [display]
    Devicename = Filename,
                   "Description",
                   "AspectRatio",
                   Grabber,
                   LogoCode,
                   VirtualDisplayDevice,
                   386Grabber,
                   [EGADOSDriver],
                   LogoData,
                   [AdditionalInfo]
The [display] section specifies the files and information required to
install a display driver.


Parameters

   Devicename
   Specifies the name of the display device. This name must be unique in
   the SETUP.INF file, or any other information file.

   Filename
   Specifies the MS-DOS filename of the display-driver file.

   Description
   Specifies an ASCII string describing the display driver. The string can
   be up to 47 characters long, but should be as concise as possible. It is
   placed in the display setting of the [boot.description] section of
   SYSTEM.INI. This parameter must be enclosed in double quotation marks
   (").

   AspectRatio
   Specifies the aspect ratio (relative dimensions) of the display device's
   pixels as well as the number of pixels-per-inch in both horizontal and
   vertical directions. This parameter must have the form:

    AspectXY,LogPixelsX,LogPixelsY
   The parameters AspectXY, LogPixelsX, and LogPixelsY are decimal values
   that are equal to the values of the dpAspectXY, dpLogPixelsX, and
   dpLogPixelsY members in the GDIINFO structure for the display driver.

   Setup uses this information to determine which raster fonts to install
   for the device. Setup searches for matching fonts in the [sysfonts],
   [fixedfonts], [oemfonts], or [fonts] sections of the information file,
   then installs any matching fonts in the [fonts] section of the WIN.INI
   file. This parameter must be enclosed in double quotation marks ("),
   exactly match the text in the [fonts] section, and not include spaces.

   Grabber
   Specifies the MS-DOS filename of the standard-mode grabber for the
   display. Standard-mode grabbers for Windows 3.0 have the extension .GR2.
   For 3.1, the extension is .2GR.

   LogoCode
   Specifies the MS-DOS filename of the logo display code Setup uses to
   build the WIN.COM file. Logo display code files have the extension .LGO.
   Include the appropriate .LGO files for Windows 3.1 on your
   driver-installation disks.

   VirtualDisplayDevice
   Specifies the MS-DOS filename of the virtual-display device (VDD) that
   386 enhanced-mode Windows uses. The standard naming convention for VDD
   files is to either begin or end the filename with VDD, for example
   VDDVGA.386. VDD filename extensions are .386 as is the case with all
   other virtual devices.

   386Grabber
   Specifies the MS-DOS filename of the 386 enhanced-mode grabber for the
   display. The 386Grabber parameter also specifies the name of the
   386-grabber fonts section. These fonts are found in the same information
   file as the grabbers. This section identifies the font files used by the
   grabber to draw text in MS-DOS application Windows. Enhanced-mode
   grabbers for Windows 3.0 have a .GR3 extension. For Windows 3.1, the
   extension is 3GR. For more information about the 386 grabber fonts
   section, see the following Comments section.

   EGADOSDriver
   Specifies the MS-DOS filename of an MS-DOS installable device driver
   used to virtualize the write-only registers on EGA display cards so that
   they can be read. This parameter is optional.

   LogoData
   Specifies the MS-DOS filename of the logo module Setup uses to build the
   WIN.COM file. Logo data files have the extension .RLE. Include the
   appropriate .RLE files from Windows 3.1 on your driver installation
   disks.

   AdditionalInfo
   Specifies the name of the additional information section (in the same
   information file) that contains additional commands for the Setup
   program to carry out when installing this display device. For example,
   this parameter is used for multiple-resolution displays. For more
   information about the additional-information section, see the following
   Comments section.


Comments

After installing the 386 enhanced-mode grabber specified by the 386Grabber
parameter, Setup searches the same information file for a section having
the same name as 386Grabber. This section lists the font files required to
support the given grabber and has the form:

    [386Grabber]
    ANSIFont,AlternateFont
The section contains one or more entries, each specifying two fonts: one
for the ANSI character set, and another for an alternate character set
(usually the International English character set, code page 850). A grabber
may have more than one set of fonts if the display supports more than one
display mode.

If the display driver supports multiple resolutions, the AdditionalInfo
parameter can be used to direct Setup to add additional-specific
information to an initialization file such as SYSTEM.INI, or to install
files on which the display driver is dependent. During initialization,
multiple-resolution display drivers examine the SYSTEM.INI file to
determine how to respond to calls to the GetDriverResourceID function.

If the AdditionalInfo parameter is given, the information file must contain
a resolution information section having the name specified by
AdditionalInfo. This section has the form:

    [AdditionalInfo]
    Filename,Destination,INI-Filename,Section,"DeleteLine","AddLine"
The following list outlines the parameters and provides a brief description
of each.

Parameter      Description
---------------------------------------------------------------------------

Filename       Specifies the MS-DOS filename of the driver-support file
               such as a dynamic-link file required to operate this display
               driver. This parameter must have the form id:filename where
               id specifies a disk identifier. This parameter is optional.

Destination    Specifies the Windows directory to receive the file
               specified by Filename. This parameter can be 0: or 0:system
               specifying the Windows root directory or the SYSTEM
               directory. This parameter is required only if a Filename
               parameter is given.

INI-Filename   Specifies either WIN.INI or SYSTEM.INI. Use SYSTEM.INI for
               all device-specific initialization settings. This parameter
               is optional.

Section        Specifies the name of the section to modify in the given
               initialization file. This parameter, usually the same as the
               display driver's filename, is required only if an
               INI-Filename parameter is given.

DeleteLine     Specifies a line of text to delete from the specified
               section in the initialization file. Setup uses the parameter
               as a regular expression to search for, and delete the first
               matching line. This search is not case sensitive. The
               parameter must be enclosed in double quotation marks (").

AddLine        Specifies a line of text to add to the specified section in
               the initialization file. The text must have the form
               keyname=value and must be enclosed in double quotation marks
               (").


Example

This example defines a single display device (zga). The sections [ZGA.GR3],
and [ZGAHI] define the screen-grabber fonts and display-resolution
information, respectively.

    [display]
    zga = 1:zga.drv,      "OEM ZGA Color",   "133,96,72",
          1:zgacolor.gr2, 1:zgalogo.lgo,     1:vddzga.386,
          1:zga.gr3,      1:zga.sys,         1:zgalogo.rle,
          zgahi


    [ZGA.GR3]
    1:CGA40WOA.FON,1:CGA40850.FON
    1:CGA80WOA.FON,1:CGA80850.FON
    1:EGA40WOA.FON,1:EGA40850.FON
    1:EGA80WOA.FON,1:EGA80850.FON

    [ZGAHI]
    1:zgahi.dll,0:system,system.ini,zga.drv,"ZGARes=800x600","ZGAmode=HI"

See Also

[disks]



[fixedfonts]

    [fixedfonts]
    FontFile,"Description","AspectRatio"
The [fixedfonts] section specifies the files and information needed to
install the fonts required to support a display or printer driver.


Parameters

   FontFile
   Specifies the MS-DOS filename of the font file.

   Description
   Specifies an ASCII string describing the font. This parameter must be
   enclosed in double quotation marks (").

   AspectRatio
   Specifies the aspect ratio (relative dimensions) of the device for which
   the font was designed. This parameter must be enclosed in double
   quotation marks ("). This parameter can have the form:

                    AspectXY,LogPixelsX,LogPixelsY
                    CONTINUOUSSCALING
   The parameters AspectXY, LogPixelsX, and LogPixelsY are decimal values
   that match the values of the dpAspectXY, dpLogPixelsX, and dpLogPixelsY
   members in the GDIINFO structure for the corresponding device driver.

   The CONTINUOUSSCALING keyword is used for vector fonts.


Example

This example shows the font sections that support a display driver:

    [fixedfonts]
    1:egafix.fon,"ZGA (640x350) resolution Fixed System Font","133,96,72"

See Also

[disks], [display], [fonts], [io.device], [oemfonts], [sysfonts]



[fonts]

    [fonts]
    FontFile,"Description","AspectRatio"
The [fonts] section specifies the files and information needed to install
the fonts required to support a display or printer driver.


Parameters

   FontFile
   Specifies the MS-DOS filename of the font file.

   Description
   Specifies an ASCII string describing the font. This parameter must be
   enclosed in double quotation marks (").

   AspectRatio
   Specifies the aspect ratio (relative dimensions) of the device for which
   the font was designed. This parameter must be enclosed in double
   quotation marks ("). This parameter can have the form:

                    AspectXY,LogPixelsX,LogPixelsY
                    CONTINUOUSSCALING
   The parameters AspectXY, LogPixelsX, and LogPixelsY are decimal values
   that match the values of the dpAspectXY, dpLogPixelsX, and dpLogPixelsY
   members in the GDIINFO structure for the corresponding device driver.

   The CONTINUOUSSCALING keyword is used for vector fonts.


Example

This example shows the font sections that support a display driver:

    [fonts]
    1:SSERIFB.FON, "MS Sans Serif 8,10,12,14,18,24 (ZGA res)", "133,96,72"
    1:COURB.FON,   "Courier 10,12,15 (ZGA res)",               "133,96,72"
    1:SERIFB.FON,  "MS Serif 8,10,12,14,18,24 (ZGA res)",      "133,96,72"
    1:SYMBOLB.FON, "Symbol 8,10,12,14,18,24 (ZGA res)",        "133,96,72"
    1:ROMAN.FON,   "Roman (All res)",  "CONTINUOUSSCALING"
    1:SCRIPT.FON,  "Script (All res)", "CONTINUOUSSCALING"
    1:MODERN.FON,  "Modern (All res)", "CONTINUOUSSCALING"

See Also

[disks], [display], [fixedfonts], [io.device], [oemfonts]



[io.dependent]

    [io.dependent]
    Printer-Filename=Dependent-Filename[,Dependent-Filename]...
The [io.dependent] section specifies dependent files for printer or display
drivers. The dependent files must be installed with the files.


Parameters

   Printer-Filename
   Specifies the MS-DOS filename of the printer-driver file. This parameter
   must must match a Filename parameter in an information line of the
   [io.device] section.

   Dependent-Filename
   Specifies the MS-DOS filename of a dependent file.


Comments

Typical dependent files are Help (.HLP) files, support libraries, and
font-installer utilities. More than one dependent file can be listed, but
each must have a unique name.


See Also

[io.device]



[io.device]

    [io.device]
    Filename,"Description","AspectRatio"[,"AspectRatio"...]
The [io.device] section specifies the files and information required to
install printer drivers.


Parameters

   Filename
   Specifies the MS-DOS filename of the printer-driver file.

   Description
   Specifies an ASCII string that describes the printer driver. This string
   should match the description field in the driver's executable file. This
   parameter must be enclosed in double quotation marks (").

   AspectRatio
   Specifies the aspect ratio (relative dimensions) of the printer as well
   as the number of pixels-per-inch in both horizontal and vertical
   directions. This parameter must be enclosed in double quotation marks
   ("). This parameter can have one or the following form:

                    "AspectXY,LogPixelsX,LogPixelsY"
                    "DEVICESPECIFIC"
   The parameters AspectXY, LogPixelsX, and LogPixelsY are decimal values
   that are equal to the values of the dpAspectXY, dpLogPixelsX, and
   dpLogPixelsY members in the GDIINFO structure for the printer driver.

   Control Panel uses this information to determine which raster fonts to
   install for the device. Control Panel searches for matching fonts in the
   [sysfonts], [fixedfonts], [oemfonts], or [fonts] sections of the
   information file, then installs any matching fonts in the [fonts]
   section of the WIN.INI file.

   Up to five different aspect ratio values may be listed; at least one is
   required. The DEVICESPECIFIC keyword is used if no raster-font
   installation is desired.


Comments

Control Panel uses the Filename parameter to check whether the driver has
been previously installed.

Control Panel combines the Filename and Description parameters to create a
setting that it adds to the [devices] and [PrinterPorts] sections in the
WIN.INI file. The settings have the following form:

    Description=Filename,Port[,Data]
If a portion of the Description parameter is enclosed in brackets ([]),
Control Panel uses that portion (instead of the Filename parameter) in the
WIN.INI file. In this case, the text in the brackets is typically the
generic name for a driver that supports many printer models.


Example

The following is an example of an OEMSETUP.INF file for the XYZ laser and
ink-jet printers:

    [disks]
    1 = . ,"XYZ Printers Disk"

    [io.device]
    1:XYZLASER.DRV,"XYZ Laser Printer","DEVICESPECIFIC"
    1:XYZINK.DRV,"XYZ Ink Jet Printer [XYZ Series]","100,120,120","100,96,96"

    [io.dependent]
    XYZLASER.DRV=1:XYZLASER.HLP,1:SFXYZ.DLL
If the driver is not found in the current drive, Control Panel prompts the
user for the specified disk. After Control Panel installs the driver, it
updates the WIN.INI file as follows:

    [printerports]
    XYZ Series=XYZINK,LPT1:,15,45
    XYZ Laser Printer=XYZLASER,LPT2:,15,45

    [devices]
    XYZ Series=XYZINK,LPT1:
    XYZ Laser Printer=XYZLASER,LPT2:

See Also

[disks], [io.dependent]



[keyboard.drivers]

    [keyboard.drivers]
    Name = Filename
The [keyboard.drivers] section specifies the filename required to install a
keyboard driver.


Parameters

   Name
   Specifies a unique name identifying the keyboard driver.

   Filename
   Specifies the MS-DOS filename of the keyboard-driver file.


Comments

When Setup installs a keyboard driver, it also checks the [keyboard.types]
and [keyboard.tables] sections in the file to determine the keyboard type
and subtype and to install a keyboard library.


Example

The following is an example of a [keyboard.drivers] and related sections in
an OEMSETUP.INF file for a specific keyboard driver:

    [data]
    defkeydll = ussrdll

    [disks]
    1 = . ,"Oem Keyboard disk #1"

    [keyboard.drivers]
    kbd = 1:keyboard.drv

    [keyboard.types]
    t3s9oem  = "Russian OEM Keyboard"

    [keyboard.tables]
    ussrdll = 1:kbdussr.dll,"Russian"

See Also

[data], [disks], [keyboard.tables], [keyboard.types]



[keyboard.tables]

    [keyboard.tables]
    Name = Filename,"Description"
The [keyboard.tables] section specifies the keyboard-library files required
to install foreign-language keyboard support.


Parameters

   Name
   Specifies the name of the keyboard library. If more than one setting is
   given, the Name parameter must be unique.

   Filename
   Specifies the MS-DOS filename of the keyboard-library file.

   Description
   Specifies an ASCII string that describes the keyboard library. This
   parameter must be enclosed in double quotation marks (").


Comments

If the user selects a keyboard type when Setup installs Windows, Setup also
selects the keyboard table where the Name parameter matches defkeydll
setting in the [data] section of the information file.


Example

The following is an example of an [keyboard.tables] section in an
OEMSETUP.INF file for a specific keyboard driver:

    [keyboard.tables]
    ussrdll = 1:kbdussr.dll,"Russian"

See Also

[data], [keyboard.drivers], [keyboard.types]



[keyboard.types]

    [keyboard.types]
    TypeSubtype = "Description"
The [keyboard.types] section specifies the type and subtype information
required to update the type and subtype settings in the [keyboard] section
of the SYSTEM.INI file.


Parameters

   TypeSubtype
   Specifies the type and subtype of the keyboard. This parameter has the
   following form:

                ttypessubtype
   The parameter type is a decimal number identifying the keyboard type and
   the subtype parameter is a decimal number and string of text identifying
   the subtype.

   Description
   Specifies an ASCII string that describes the keyboard.


Comments

Setup uses the keyboard type and subtype values to set the type and subtype
settings in the [keyboard] section of the SYSTEM.INI file.


Example

The following is an example of a [keyboard.types] section in an
OEMSETUP.INF file for a specific keyboard driver:

    [keyboard.types]
    t3s9oem  = "Russian OEM Keyboard"

See Also

[keyboard.drivers], [keyboard.tables]



[network]

    [network]
    Netname = Filename,"Description", [HelpFile], [OptionalFile],
             [WinIniSect], [SysIniSect],[VirtualDevice]...
The [network] section identifies the networks that are available for
installation. Setup uses the [network] and related sections to install
network drivers and update the SYSTEM.INI file.


Parameters

   Netname
   Specifies a unique name identifying the network driver.

   Filename
   Specifies the MS-DOS filename of the network-driver file. If no filename
   is given, Setup searches for a [netname.versions] section in the
   information file.

   Description
   Specifies an ASCII string that describes the network driver. This
   parameter must be enclosed in double quotation marks (").

   HelpFile
   Specifies the MS-DOS filename of the associated Help file. Setup copies
   this file to the WINDOWS directory. This parameter is optional.

   OptionalFile
   Specifies the MS-DOS filename of any file that may be necessary for a
   given network. Setup copies this file to the WINDOWS directory. This
   parameter is optional.

   WinIniSect
   Specifies the name of the section in the OEMSETUP.INF file that
   describes modifications to be made to the WIN.INI file. For more
   information about the section associated with this parameter, see the
   following Comments section.

   SysIniSect
   Specifies the name of the section in the OEMSETUP.INF file that
   describes modifications to be made to the SYSTEM.INI file. For more
   information about the section associated with this parameter, see the
   following Comments section.

   VirtualDevice
   Specifies the MS-DOS filename of an associated virtual device to be
   installed for running 386 enhanced-mode Windows.


Comments

The sections corresponding to the WinIniSect and SysIniSect parameters
contain one or more lines defining the modifications to make to the WIN.INI
and SYSTEM.INI files. For more information about the lines in these
sections, see the [netname.versions] section.

If a network has a corresponding [netname.versions] section, the
work-section (or sections) defined by the [netname.versions] section
specify most (if not all) of the files and initialization file changes that
need to be made to install the network. This means that, other than the
Netname and the Description parameters, all parameters in the [network]
section can be empty. If a network driver is specified in the [network]
section, it becomes the default driver if none is specified in the
work-section. If any of the OptionalFile, HelpFile, and VirtualDevice
parameters specify files, Setup adds the files to the list of such files
given in the work-section. The SysIniSect and WinIniSect parameters also
specify work-sections and actions that will be performed for all versions
of the network.


Example

The following is an example of a [network] section in the OEMSETUP.INF file
for a specific network driver:

    [disks]
    1 = . ,"Oem Network driver disk #1"

    [network]
    oem_net = 1:oem.drv, "OEM Network Driver", 1:oemnet.hlp,
            1:oem_app.exe, oem_winini, oem_sysini, 1:oem1.386, 1:oem2.386

    [oem_winini]
    Windows,load,oem_app.exe

    [oem_sysini]
    386enh,TimerCriticalSection,500
In this example, Setup adds the setting load=OEM_APP.EXE to the [windows]
section of the WIN.INI file, and adds the setting TimerCriticalSection=500
to the [386Enh] section of the SYSTEM.INI file. If a load setting already
exists in WIN.INI, Setup appends OEM_APP.EXE to the setting.

The following example relies on the section [mynet.versions] to identify
the files to install for the network:

    [networks]
    mynet=,"My Network"

See Also

[disks],[netname.versions]



[netname.versions]

    [netname.versions]
    ooMMmmrr=description,search-file,work-section,work-section2
The [netname.versions] section contains a list identifying the different
version of a network that can be installed. The netname in the section
title must be the same as a netname given in the [network] section of the
information file.


Parameters

   oo
   Specfies a two-digit option code. For example, Microsoft LAN Manager
   uses option code 00 to indicate the basic configuration and 01 to
   indicate the 386 enhanced configuration. The option can be an number or
   xx if an option code is not needed.

   MM
   Specifies a two-digit major version number.

   mm
   Specifies a two-digit minor version number.

   rr
   Specifies the revision number.

   description
   Specifies an ASCII string that describes the version for the
   corresponding network driver. This parameter must be enclosed in double
   quotation marks (").

   search-file
   Specifies the name of a file. This parameter can be left blank. If it is
   not, Setup searches for the specified file and uses the result of the
   search to determine whether to use the work-section or work-section2
   parameter to complete the installation. If search-file is left blank,
   Setup uses the work-section parameter to complete the installation.

   work-section
   Specifies the name of the section that defines how to install support
   for the network. Setup uses this section only if the search-file
   parameter is empty or the file specified by search-file could not be
   found.

   work-section2
   Specifies the name of the section that defines how to install support
   for the network. Setup uses this section only if the file specified by
   search-file is found.


Comments

For an OEM-supplied OEMSETUP.INF file, the version number used on the left
side of the equal sign is not critical; the values are important only when
Setup performs detection for the network during a first-time install. Setup
defaults to the highest numbered version in SETUP.INF that is less than or
equal to the detected version, provided that the option field matches or is
xx.

Each work section has the following form:

    [work-section]
    line
        .
        .
        .
Each line may define a file or initialization setting for the network. For
a complete description of the lines, see the Work Section Lines section.


Example

The following example supports three versions of the network. Each version
has a version-specific work section. The last version specifies a a file
(V2ENH.EXE) to search for and also two work sections.

    [networks]
    mynet=,"My Network"

    [mynet.versions]
    00010000="Version 1.00",,my ver1
    00020000="Version 2.00",,my ver2
    01020000="Version 2.00 ENHANCED",v2enh.exe,my_ver2,my_ver2_plus
When installing with this example, the user will choose from:

    My Network (Version 1.00)
    My Network (Version 2.00)
    My Network (Version 2.00 ENHANCED)

Work section lines

A work section may contain any of the following lines, in any order:

    section,tag,value
    system.ini=section,tag,value
    win.ini=section,tag,value
    driver=drive:filename
    vxd=drive:filename,...
    sysdir=drive:filename,...
    windir=drive:filename,...
    update=drive:filename,...
    warning=level
Each line is described in detail in subsequent sections.

The drive specifier refers to one of the disks defined in the OEMSETUP.INF
file. Filenames should appear without a path. In all such lines (except
driver), all files listed in all sections are copied. For example, a vxd
line in the version-specific section will add VxDs to any VxD listed in
another work-section, or the [networks] section. In general, when using
version-specific work sections, all files copied should be defined in that
section, and the other sections and [networks] section line should be
empty.

Setup carries out standard Windows version checking when copying files if
the specified files are Windows-format executables.


Initialization line

    section,tag,value
This line updates one of two initialization files. If the work-section is
specified by the WinIniSect of the network line in the [network] section,
the modification is applied to WIN.INI. Otherwise, the modification is
applied to SYSTEM.INI.

If this line specifies the load setting in the [windows] section of WIN.INI
or the drivers setting in the [boot] section of SYSTEM.INI, Setup appends
the value to the current setting value. All other tags are replaced.

In the case of the device setting in the [386Enh] section of SYSTEM.INI,
settings are not replaced; a new line will be added. In general, VxDs
should always appear on the VXD=command setting so that Setup can remove
them correctly should the network installation be modified using
Maintenance Mode Setup.

The following example puts the setting TimerCriticalSection=1000 in the
[386Enh] section of SYSTEM.INI.

    386Enh,TimerCriticalSection,1000

SYSTEM.INI line

    system.ini=section,tag,value
This line modifies a setting in SYSTEM.INI. For example, the following line
adds the setting UniqueDOSPSP=1 to the [386Enh] section of SYSTEM.INI.

    system.ini=386Enh,UniqueDOSPSP,1

WIN.INI line

    win.ini=section,tag,value
This line modified a setting in WIN.INI. For example, the following line
appends mybcast.exe to the load setting in the [windows] section of
WIN.INI.

    win.ini=windows,load,mybcast.exe

DRIVER line

    driver=drive:filename
This line sets the network driver in the [boot] section in SYSTEM.INI, and
copies the file from the disk to the SYSTEM directory. If a driver is
defined in more than one place in the OEMSETUP.INF file, Setup checks each
of the following sections or parameters (in the given order) until it finds
the name of a driver to copy:

o   The work-section specified by the [netname.versions] section.

o   The section specified by the SysIniSect parameter in the [network]
    section.

o   The section specified by the WinIniSect parameter in the [network]
    section.

o   The Filename specified by the [network] section.

The following example copies MYNET.DRV from the [disks] section of
OEMSETUP.INF to the SYSTEM directory, and adds the setting
network.drv=mynet.drv to the [boot] section of SYSTEM.INI.

    driver=9:mynet.drv

VXD line

    vxd=drive:filename,...
This line adds one or more VxDs to SYSTEM.INI and copies the files to the
SYSTEM directory, unless the VxD is internal to WIN386. For example, the
following line copies MYNET.386 from the [disks] section of OEMSETUP.INF to
the SYSTEM directory, and adds the setting
network=mynet.386,*dosnet,*vnetbios to the [386Enh] section of SYSTEM.INI.

    vxd=9:mynet.386,x:*dosnet,x:*vnetbios

SYSDIR line

    sysdir=drive:filename,...
This line copies one or more files to the SYSTEM directory. For example,
the following line copies MYNETLIB.DLL to the SYSTEM directory from disk as
defined in the OEMSETUP.INF file.

    sysdir=9:mynetlib.dll

WINDIR line

    windir=drive:filename,...
This line copies one or more files from disk to the WINDOWS directory. For
example, the following line copies the Help file for the driver to the
WINDOWS directory.

    windir=9:mynet.hlp

UPDATE line

    update=drive:filename,...
This line replaces a file found on the path, or, if not found, copies it to
the Windows directory. This allows Setup to update a network component
shipped with the network software in place. The following example searches
for V2ENH.EXE on the path. If found, a new version of the file is copied.

    update=9:v2enh.exe

WARNING line

    warning=level
This setting produces a warning dialog box. The level can be one of the
following values.

Value   Meaning
---------------------------------------------------------------------------

1       Indicates that the network is not compatible with Windows.

2       Indicates the network software is compatible, but updated software
        may be available.

3       Indicates that the network software is compatible, but some part of
        it is missing. Level 3 is generally used in a work-section when a
        search file is not found, so the user can be notified that they are
        missing that file.



[oemfonts]

    [oemfonts]
    FontFile,"Description","AspectRatio",CountryCode
The [oemfonts] section specifies the files and information needed to
install the OEM fonts required to support a display or printer driver.


Parameters

   FontFile
   Specifies the MS-DOS filename of the font file.

   Description
   Specifies an ASCII string describing the font. This parameter must be
   enclosed in double quotation marks (").

   AspectRatio
   Specifies the aspect ratio (relative dimensions) of the device for which
   the font was designed. This parameter must be enclosed in double
   quotation marks ("). This parameter can have the form:

             AspectXY,LogPixelsX,LogPixelsY
             CONTINUOUSSCALING
   The parameters AspectXY, LogPixelsX, and LogPixelsY are decimal values
   that match the values of the dpAspectXY, dpLogPixelsX, and dpLogPixelsY
   members in the GDIINFO structure for the corresponding device driver.

   The CONTINUOUSSCALING keyword is used for vector fonts.

   CountryCode
   Specifies the country for which the font was designed.


Example

This example shows the font sections that support a display driver:

    [oemfonts]
    1:egaoem.fon,"ZGA (640x350) resolution Terminal Font (USA)","133,96,72",1

See Also

[disks], [display], [fixedfonts], [fonts], [io.device], [sysfonts]



[pointing.device]

    [pointing.device]
    Name = Filename,"Description",VirtualDevice,[AdditionalInfo]
The [pointing.device] section specifies the files required to install a
mouse driver.


Parameters

   Name
   Specifies a unique name identifying the mouse driver.

   Filename
   Specifies the MS-DOS filename of the mouse-driver file.

   Description
   Specifies an ASCII string that describes the mouse driver. This
   parameter must be enclosed in double quotation marks (").

   VirtualDevice
   Specifies the MS-DOS filenames of the associated virtual-mouse devices
   to be installed for 386 enhanced-mode Windows. If more than one filename
   is given, the parameter must be enclosed in double quotation marks (").

   AdditionalInfo
   Specifies the name of the additional information section (in the same
   information file) that contains additional commands for the Setup
   program to carry out when installing this pointing device. This
   parameter can be used to direct Setup to add device-specific information
   to an initialization file such as SYSTEM.INI, or to install files on
   which the pointing device driver is dependent.


Comments

If the AdditionalInfo parameter is given, the information file must contain
an additional-information section having the name specified by
AdditionalInfo. This section has the form:

    [AdditionalInfo]
    Filename,Destination,INI-Filename,Section,"DeleteLine","AddLine"
The following list outlines the parameters and provides a brief description
of each.

Parameter      Description
---------------------------------------------------------------------------

Filename       Specifies the MS-DOS filename of the driver-support file
               such as a dynamic-link file required to operate this display
               driver. This parameter must have the form id:filename where
               id specifies a disk identifier. This parameter is optional.

Destination    Specifies the WINDOWS directory to receive the file
               specified by Filename. This parameter can be 0: or 0:system
               specifying the Windows root directory or the SYSTEM
               directory. This parameter is required only if a Filename
               parameter is given.

INI-Filename   Specifies either WIN.INI or SYSTEM.INI. Use SYSTEM.INI for
               all device-specific initialization settings. This parameter
               is optional.

Section        Specifies the name of the section to modify in the given
               initialization file. This parameter, usually the same as the
               pointing-device driver's filename, is required only if an
               INI-Filename parameter is given.

DeleteLine     Specifies a line of text to delete from the specified
               section in the initialization file. Setup uses the parameter
               as a regular expression to search for and delete the first
               matching line. This search is not case-sensitive. The
               parameter must be enclosed in double quotation marks (").

AddLine        Specifies a line of text to add to the specified section in
               the initialization file. The text must have the form
               keyname=value and must be enclosed in double quotation marks
               (").


Example

This example shows the [pointing.device] section in an OEMSETUP.INF file
for a specific mouse driver:

    [disks]
    1 =. ,"OEM Mouse driver disk #1"

    [pointing.device]
    oemmouse = 1:oemmouse.drv,"OEM Mouse driver",1:oemvmd.386

See Also

[disks]



[sysfonts]

    [sysfonts]
    FontFile,"Description","AspectRatio"
The [sysfonts] section specifies the files and information needed to
install the system font required to support a display or printer driver.


Parameters

   FontFile
   Specifies the MS-DOS filename of the font file.

   Description
   Specifies an ASCII string describing the font. This parameter must be
   enclosed in double quotation marks (").

   AspectRatio
   Specifies the aspect ratio (relative dimensions) of the device for which
   the font was designed. This parameter must be enclosed in double
   quotation marks ("). This parameter can have the form:

                    AspectXY,LogPixelsX,LogPixelsY
                    CONTINUOUSSCALING
   The parameters AspectXY, LogPixelsX, and LogPixelsY are decimal values
   that match the values of the dpAspectXY, dpLogPixelsX, and dpLogPixelsY
   members in the GDIINFO structure for the corresponding device driver.

   The CONTINUOUSSCALING keyword is used for vector fonts.


Example

This example shows the font sections that support a display driver:

    [sysfonts]
    1:egasys.fon,"ZGA (640x350) resolution System Font","133,96,72"

See Also

[disks], [display], [fixedfonts], [fonts], [io.device], [oemfonts]

Appendix A  Binary and Ternary Raster-Operation Codes

This appendix lists and describes the binary and ternary raster operations
used by graphics device interface (GDI). A binary raster operation involves
two operands: a pen and a destination bitmap. A ternary raster operation
involves three operands: a source bitmap, a brush, and a destination
bitmap. Both binary and ternary raster operations use Boolean operators.


1 Binary Raster Operations

This section lists the binary raster-operation codes used by functions.
Raster-operation codes define how GDI combines the bits from the selected
pen with the bits in the destination bitmap.

Each raster-operation code represents a Boolean operation in which the
values of the pixels in the selected pen and the destination bitmap are
combined. Following are the two operands used in these operations:

Operand   Meaning
---------------------------------------------------------------------------

P         Selected pen

D         Destination bitmap

The Boolean operators used in these operations follow:

Operator   Meaning
---------------------------------------------------------------------------

a          Bitwise AND

n          Bitwise NOT (inverse)

o          Bitwise OR

x          Bitwise exclusive OR (XOR)

All Boolean operations are presented in reverse Polish notation. For
example, the following operation replaces the values of the pixels in the
destination bitmap with a combination of the pixel values of the pen and
the selected brush:

    DPo
Each raster-operation code is a 32-bit integer whose high-order word is a
Boolean operation index and whose low-order word is the operation code. The
16-bit operation index is a zero-extended 8-bit value that represents all
possible outcomes resulting from the Boolean operation on two parameters
(in this case, the pen and destination values). For example, the operation
indexes for the DPo and DPan operations are shown in the following list:

---------------------------------------------------------------------------
P   D   DPo   DPan
---------------------------------------------------------------------------

0   0   0     1

0   1   1     1

1   0   1     1

1   1   1     0

---------------------------------------------------------------------------

The following list outlines the drawing modes and the Boolean operations
that they represent:

Raster operation   Boolean operation
---------------------------------------------------------------------------

R2_BLACK           0

R2_COPYPEN         P

R2_MASKNOTPEN      DPna

R2_MASKPEN         DPa

R2_MASKPENNOT      PDna

R2_MERGENOTPEN     DPno

R2_MERGEPEN        DPo

R2_MERGEPENNOT     PDno

R2_NOP             D

R2_NOT             Dn

R2_NOTCOPYPEN      Pn

R2_NOTMASKPEN      DPan

R2_NOTMERGEPEN     DPon

R2_NOTXORPEN       DPxn

R2_WHITE           1

R2_XORPEN          DPx

For a monochrome device, GDI maps the value zero to black and the value 1
to white. If an application attempts to draw with a black pen on a white
destination by using the available binary raster operations, the following
results occur:

Raster operation   Result
---------------------------------------------------------------------------

R2_BLACK           Visible black line

R2_COPYPEN         Visible black line

R2_MASKNOTPEN      No visible line

R2_MASKPEN         Visible black line

R2_MASKPENNOT      Visible black line

R2_MERGENOTPEN     No visible line

R2_MERGEPEN        Visible black line

R2_MERGEPENNOT     Visible black line

R2_NOP             No visible line

R2_NOT             Visible black line

R2_NOTCOPYPEN      No visible line

R2_NOTMASKPEN      No visible line

R2_NOTMERGEPEN     Visible black line

R2_NOTXORPEN       Visible black line

R2_WHITE           No visible line

R2_XORPEN          No visible line

For a color device, GDI uses RGB values to represent the colors of the pen
and the destination. An RGB color value is a long integer that contains a
red, a green, and a blue color field, each specifying the intensity of the
given color. Intensities range from 0 through 255. The values are packed in
the three low-order bytes of the long integer. The color of a pen is always
a solid color, but the color of the destination may be a mixture of any two
or three colors. If an application attempts to draw with a white pen on a
blue destination by using the available binary raster operations, the
following results occur:

Raster operation   Result
---------------------------------------------------------------------------

R2_BLACK           Visible black line

R2_COPYPEN         Visible white line

R2_MASKNOTPEN      Visible black line

R2_MASKPEN         Invisible blue line

R2_MASKPENNOT      Visible red/green line

R2_MERGENOTPEN     Invisible blue line

R2_MERGEPEN        Visible white line

R2_MERGEPENNOT     Visible white line

R2_NOP             Invisible blue line

R2_NOT             Visible red/green line

R2_NOTCOPYPEN      Visible black line

R2_NOTMASKPEN      Visible red/green line

R2_NOTMERGEPEN     Visible black line

R2_NOTXORPEN       Invisible blue line

R2_WHITE           Visible white line

R2_XORPEN          Visible red/green line


2 Ternary Raster Operations

This section lists the ternary raster-operation codes used by the BitBlt
and StretchBlt functions. Ternary raster-operation codes define how GDI
combines the bits in a source bitmap with the bits in the destination
bitmap.

Each raster-operation code represents a Boolean operation in which the
values of the pixels in the source, the selected brush, and the destination
are combined. Following are the three operands used in these operations:

Operand   Meaning
---------------------------------------------------------------------------

D         Destination bitmap

P         Selected brush (also called pattern)

S         Source bitmap

Boolean operators used in these operations follow:

Operator   Meaning
---------------------------------------------------------------------------

a          Bitwise AND

n          Bitwise NOT (inverse)

o          Bitwise OR

x          Bitwise exclusive OR (XOR)

All Boolean operations are presented in reverse Polish notation. For
example, the following operation replaces the values of the pixels in the
destination bitmap with a combination of the pixel values of the source and
brush:

    PSo
The following operation combines the values of the pixels in the source and
brush with the pixel values of the destination bitmap (there are
alternative spellings of the same function, so although a particular
spelling may not be in the list, an equivalent form would be):

    DPSoo
Each raster-operation code is a 32-bit integer whose high-order word is a
Boolean operation index and whose low-order word is the operation code. The
16-bit operation index is a zero-extended, 8-bit value that represents the
result of the Boolean operation on predefined brush, source, and
destination values. For example, the operation indexes for the PSo and
DPSoo operations are shown in the following list:

---------------------------------------------------------------------------
P                  S   D   PSo     DPSoo
---------------------------------------------------------------------------

0                  0   0   0       0

0                  0   1   0       1

0                  1   0   1       1

0                  1   1   1       1

1                  0   0   1       1

1                  0   1   1       1

1                  1   0   1       1

1                  1   1   1       1

Operation index:           00FCh   00FEh

---------------------------------------------------------------------------

In this case, PSo has the operation index 00FC (read from the bottom up);
DPSoo has the operation index 00FE. These values define the location of the
corresponding raster-operation codes, as shown in Table A.1,
Raster-Operation Codes. The PSo operation is in line 252 (00FCh) of the
table; DPSoo is in line 254 (00FEh).

The most commonly used raster operations have been given special names in
the Windows include file, WINDOWS.H. You should use these names whenever
possible in your applications.

When the source and destination bitmaps are monochrome, a bit value of zero
represents a black pixel and a bit value of 1 represents a white pixel.
When the source and the destination bitmaps are color, those colors are
represented with RGB values.

---------------------------------------------------------------------------
Boolean function   Raster operation   Boolean           Common name
(hexadecimal)      (hexadecimal)      function in       
                                      reverse Polish    
---------------------------------------------------------------------------

00                 00000042           0                 BLACKNESS

01                 00010289           DPSoon            -

02                 00020C89           DPSona            -

03                 000300AA           PSon              -

04                 00040C88           SDPona            -

05                 000500A9           DPon              -

06                 00060865           PDSxnon           -

07                 000702C5           PDSaon            -

08                 00080F08           SDPnaa            -

09                 00090245           PDSxon            -

0A                 000A0329           DPna              -

0B                 000B0B2A           PSDnaon           -

0C                 000C0324           SPna              -

0D                 000D0B25           PDSnaon           -

0E                 000E08A5           PDSonon           -

0F                 000F0001           Pn                -

10                 00100C85           PDSona            -

11                 001100A6           DSon              NOTSRCERASE

12                 00120868           SDPxnon           -

13                 001302C8           SDPaon            -

14                 00140869           DPSxnon           -

15                 001502C9           DPSaon            -

16                 00165CCA           PSDPSanaxx        -

17                 00171D54           SSPxDSxaxn        -

18                 00180D59           SPxPDxa           -

19                 00191CC8           SDPSanaxn         -

1A                 001A06C5           PDSPaox           -

1B                 001B0768           SDPSxaxn          -

1C                 001C06CA           PSDPaox           -

1D                 001D0766           DSPDxaxn          -

1E                 001E01A5           PDSox             -

1F                 001F0385           PDSoan            -

20                 00200F09           DPSnaa            -

21                 00210248           SDPxon            -

22                 00220326           DSna              -

23                 00230B24           SPDnaon           -

24                 00240D55           SPxDSxa           -

25                 00251CC5           PDSPanaxn         -

26                 002606C8           SDPSaox           -

27                 00271868           SDPSxnox          -

28                 00280369           DPSxa             -

29                 002916CA           PSDPSaoxxn        -

2A                 002A0CC9           DPSana            -

2B                 002B1D58           SSPxPDxaxn        -

2C                 002C0784           SPDSoax           -

2D                 002D060A           PSDnox            -

2E                 002E064A           PSDPxox           -

2F                 002F0E2A           PSDnoan           -

30                 0030032A           PSna              -

31                 00310B28           SDPnaon           -

32                 00320688           SDPSoox           -

33                 00330008           Sn                NOTSRCCOPY

34                 003406C4           SPDSaox           -

35                 00351864           SPDSxnox          -

36                 003601A8           SDPox             -

37                 00370388           SDPoan            -

38                 0038078A           PSDPoax           -

39                 00390604           SPDnox            -

3A                 003A0644           SPDSxox           -

3B                 003B0E24           SPDnoan           -

3C                 003C004A           PSx               -

3D                 003D18A4           SPDSonox          -

3E                 003E1B24           SPDSnaox          -

3F                 003F00EA           PSan              -

40                 00400F0A           PSDnaa            -

41                 00410249           DPSxon            -

42                 00420D5D           SDxPDxa           -

43                 00431CC4           SPDSanaxn         -

44                 00440328           SDna              SRCERASE

45                 00450B29           DPSnaon           -

46                 004606C6           DSPDaox           -

47                 0047076A           PSDPxaxn          -

48                 00480368           SDPxa             -

49                 004916C5           PDSPDaoxxn        -

4A                 004A0789           DPSDoax           -

4B                 004B0605           PDSnox            -

4C                 004C0CC8           SDPana            -

4D                 004D1954           SSPxDSxoxn        -

4E                 004E0645           PDSPxox           -

4F                 004F0E25           PDSnoan           -

50                 00500325           PDna              -

51                 00510B26           DSPnaon           -

52                 005206C9           DPSDaox           -

53                 00530764           SPDSxaxn          -

54                 005408A9           DPSonon           -

55                 00550009           Dn                DSTINVERT

56                 005601A9           DPSox             -

57                 00570389           DPSoan            -

58                 00580785           PDSPoax           -

59                 00590609           DPSnox            -

5A                 005A0049           DPx               PATINVERT

5B                 005B18A9           DPSDonox          -

5C                 005C0649           DPSDxox           -

5D                 005D0E29           DPSnoan           -

5E                 005E1B29           DPSDnaox          -

5F                 005F00E9           DPan              -

60                 00600365           PDSxa             -

61                 006116C6           DSPDSaoxxn        -

62                 00620786           DSPDoax           -

63                 00630608           SDPnox            -

64                 00640788           SDPSoax           -

65                 00650606           DSPnox            -

66                 00660046           DSx               SRCINVERT

67                 006718A8           SDPSonox          -

68                 006858A6           DSPDSonoxxn       -

69                 00690145           PDSxxn            -

6A                 006A01E9           DPSax             -

6B                 006B178A           PSDPSoaxxn        -

6C                 006C01E8           SDPax             -

6D                 006D1785           PDSPDoaxxn        -

6E                 006E1E28           SDPSnoax          -

6F                 006F0C65           PDSxnan           -

70                 00700CC5           PDSana            -

71                 00711D5C           SSDxPDxaxn        -

72                 00720648           SDPSxox           -

73                 00730E28           SDPnoan           -

74                 00740646           DSPDxox           -

75                 00750E26           DSPnoan           -

76                 00761B28           SDPSnaox          -

77                 007700E6           DSan              -

78                 007801E5           PDSax             -

79                 00791786           DSPDSoaxxn        -

7A                 007A1E29           DPSDnoax          -

7B                 007B0C68           SDPxnan           -

7C                 007C1E24           SPDSnoax          -

7D                 007D0C69           DPSxnan           -

7E                 007E0955           SPxDSxo           -

7F                 007F03C9           DPSaan            -

80                 008003E9           DPSaa             -

81                 00810975           SPxDSxon          -

82                 00820C49           DPSxna            -

83                 00831E04           SPDSnoaxn         -

84                 00840C48           SDPxna            -

85                 00851E05           PDSPnoaxn         -

86                 008617A6           DSPDSoaxx         -

87                 008701C5           PDSaxn            -

88                 008800C6           DSa               SRCAND

89                 00891B08           SDPSnaoxn         -

8A                 008A0E06           DSPnoa            -

8B                 008B0666           DSPDxoxn          -

8C                 008C0E08           SDPnoa            -

8D                 008D0668           SDPSxoxn          -

8E                 008E1D7C           SSDxPDxax         -

8F                 008F0CE5           PDSanan           -

90                 00900C45           PDSxna            -

91                 00911E08           SDPSnoaxn         -

92                 009217A9           DPSDPoaxx         -

93                 009301C4           SPDaxn            -

94                 009417AA           PSDPSoaxx         -

95                 009501C9           DPSaxn            -

96                 00960169           DPSxx             -

97                 0097588A           PSDPSonoxx        -

98                 00981888           SDPSonoxn         -

99                 00990066           DSxn              -

9A                 009A0709           DPSnax            -

9B                 009B07A8           SDPSoaxn          -

9C                 009C0704           SPDnax            -

9D                 009D07A6           DSPDoaxn          -

9E                 009E16E6           DSPDSaoxx         -

9F                 009F0345           PDSxan            -

A0                 00A000C9           DPa               -

A1                 00A11B05           PDSPnaoxn         -

A2                 00A20E09           DPSnoa            -

A3                 00A30669           DPSDxoxn          -

A4                 00A41885           PDSPonoxn         -

A5                 00A50065           PDxn              -

A6                 00A60706           DSPnax            -

A7                 00A707A5           PDSPoaxn          -

A8                 00A803A9           DPSoa             -

A9                 00A90189           DPSoxn            -

AA                 00AA0029           D                 -

AB                 00AB0889           DPSono            -

AC                 00AC0744           SPDSxax           -

AD                 00AD06E9           DPSDaoxn          -

AE                 00AE0B06           DSPnao            -

AF                 00AF0229           DPno              -

B0                 00B00E05           PDSnoa            -

B1                 00B10665           PDSPxoxn          -

B2                 00B21974           SSPxDSxox         -

B3                 00B30CE8           SDPanan           -

B4                 00B4070A           PSDnax            -

B5                 00B507A9           DPSDoaxn          -

B6                 00B616E9           DPSDPaoxx         -

B7                 00B70348           SDPxan            -

B8                 00B8074A           PSDPxax           -

B9                 00B906E6           DSPDaoxn          -

BA                 00BA0B09           DPSnao            -

BB                 00BB0226           DSno              MERGEPAINT

BC                 00BC1CE4           SPDSanax          -

BD                 00BD0D7D           SDxPDxan          -

BE                 00BE0269           DPSxo             -

BF                 00BF08C9           DPSano            -

C0                 00C000CA           PSa               MERGECOPY

C1                 00C11B04           SPDSnaoxn         -

C2                 00C21884           SPDSonoxn         -

C3                 00C3006A           PSxn              -

C4                 00C40E04           SPDnoa            -

C5                 00C50664           SPDSxoxn          -

C6                 00C60708           SDPnax            -

C7                 00C707AA           PSDPoaxn          -

C8                 00C803A8           SDPoa             -

C9                 00C90184           SPDoxn            -

CA                 00CA0749           DPSDxax           -

CB                 00CB06E4           SPDSaoxn          -

CC                 00CC0020           S                 SRCCOPY

CD                 00CD0888           SDPono            -

CE                 00CE0B08           SDPnao            -

CF                 00CF0224           SPno              -

D0                 00D00E0A           PSDnoa            -

D1                 00D1066A           PSDPxoxn          -

D2                 00D20705           PDSnax            -

D3                 00D307A4           SPDSoaxn          -

D4                 00D41D78           SSPxPDxax         -

D5                 00D50CE9           DPSanan           -

D6                 00D616EA           PSDPSaoxx         -

D7                 00D70349           DPSxan            -

D8                 00D80745           PDSPxax           -

D9                 00D906E8           SDPSaoxn          -

DA                 00DA1CE9           DPSDanax          -

DB                 00DB0D75           SPxDSxan          -

DC                 00DC0B04           SPDnao            -

DD                 00DD0228           SDno              -

DE                 00DE0268           SDPxo             -

DF                 00DF08C8           SDPano            -

E0                 00E003A5           PDSoa             -

E1                 00E10185           PDSoxn            -

E2                 00E20746           DSPDxax           -

E3                 00E306EA           PSDPaoxn          -

E4                 00E40748           SDPSxax           -

E5                 00E506E5           PDSPaoxn          -

E6                 00E61CE8           SDPSanax          -

E7                 00E70D79           SPxPDxan          -

E8                 00E81D74           SSPxDSxax         -

E9                 00E95CE6           DSPDSanaxxn       -

EA                 00EA02E9           DPSao             -

EB                 00EB0849           DPSxno            -

EC                 00EC02E8           SDPao             -

ED                 00ED0848           SDPxno            -

EE                 00EE0086           DSo               SRCPAINT

EF                 00EF0A08           SDPnoo            -

F0                 00F00021           P                 PATCOPY

F1                 00F10885           PDSono            -

F2                 00F20B05           PDSnao            -

F3                 00F3022A           PSno              -

F4                 00F40B0A           PSDnao            -

F5                 00F50225           PDno              -

F6                 00F60265           PDSxo             -

F7                 00F708C5           PDSano            -

F8                 00F802E5           PDSao             -

F9                 00F90845           PDSxno            -

FA                 00FA0089           DPo               -

FB                 00FB0A09           DPSnoo            PATPAINT

FC                 00FC008A           PSo               -

FD                 00FD0A0A           PSDnoo            -

FE                 00FE02A9           DPSoo             -

FF                 00FF0062           1                 WHITENESS

---------------------------------------------------------------------------

Appendix B  Character Sets

The Microsoft Windows operating system, version 3.1 supports multiple
character sets, allowing for customization. Among the character sets that
Windows 3.1 provides are the Windows, Symbol, and OEM character sets, shown
in the following sections.


1 ANSI Character Set

bitmap:  ansichar


2 Symbol Character Set

bitmap:  symbolch


3 OEM Character Set

bitmap:  oemchar

Appendix C  Windows Interrupt 2Fh Services and Notifications

The Microsoft Windows Interrupt 2Fh services and notifications help Windows
device drivers and related MS-DOS device drivers and
terminate-and-stay-resident (TSR) programs manage their operations in the
multitasking environment of Windows. The services let drivers carry out
actions such as relinquishing the CPU time slice. The notifications let
drivers respond to events, such as starting up Windows, that Windows
broadcasts using Interrupt 2Fh.

Although the Interrupt 2Fh services and notifications are primarily
available under 386 enhanced-mode Windows version 3.x, some services are
also available in standard-mode Windows.


1 About the Services and Notifications

The Interrupt 2Fh services are a set of functions that MS-DOS drivers and
TSRs call to direct Windows to carry out specific actions. The
notifications are a set of functions that Windows calls to notify drivers
and programs of Windows-related events. Although these functions were
initially designed for use by MS-DOS drivers and TSRs, some Windows device
drivers, such as display drivers and grabbers, also use them to manage the
multitasking features of Windows.

A driver can call the service functions using the MS-DOS multiplex
interrupt, Interrupt 2Fh. The driver sets one or more registers to
specified values, sets the AX register to the desired function number, and
issues the interrupt using the int instruction.

A driver can receive notifications by installing its own interrupt-handling
routine in the Interrupt 2Fh interrupt chain. Once the interrupt handler is
installed, the driver checks the AX register on each interrupt for function
numbers that match the notifications. When the driver matches a
notification, it can carry out any related actions.


1.1 Service Functions

The service functions let drivers and TSRs obtain the Windows version
number, obtain the current virtual-machine (VM) identifier, set critical
sections, and retrieve the addresses of the entry points for virtual-device
service functions. There are the following service functions:

o   Get Enhanced-Mode Windows Installed State (Interrupt 2Fh Function 1600h)

o   Get Enhanced-Mode Windows Entry-Point Address (Interrupt 2Fh Function
    1602h)

o   Release Current VM Time-Slice (Interrupt 2Fh Function 1680h)

o   Begin Critical Section (Interrupt 2Fh Function 1681h)

o   End Critical Section (Interrupt 2Fh Function 1682h)

o   Get Current Virtual Machine ID (Interrupt 2Fh Function 1683h)

o   Get Device Entry Point Address (Interrupt 2Fh Function 1684h)

o   Switch VMs and CallBack (Interrupt 2Fh Function 1685h)

o   Detect Interrupt 31h Services (Interrupt 2Fh Function 1686h)

The 386 enhanced-mode Windows display grabber uses the Get Device Entry
Point Address (Interrupt 2Fh Function 1684h) to retrieve the entry point
address for the virtual-display device (VDD). The grabber uses this address
to call VDD service functions to carry out capturing display contexts and
updating tasks.

Both standard- and 386 enhanced-mode Windows issues Windows Initialization
Notification (Interrupt 2Fh Function 1605h) and Windows Termination
Notification (Interrupt 2Fh Function 1606h). These notifications gives
MS-DOS drivers and TSR programs in either Windows environment the
opportunity to free extended memory before Windows starts, and reallocate
the memory when Windows stops.

Standard- and 386 enhanced-mode Windows also support Detect Interrupt 31h
Services. Supporting these services lets MS-DOS drivers and TSR programs
check for and use these service functions.

If the user starts a TSR program after Windows starts, the TSR program can
always use Get Enhanced-Mode Windows Installed State (Interrupt 2Fh
Function 1600h) to determine whether Windows is running.


1.2 Notification Functions

Windows broadcasts the notification functions by setting registers and
issuing Interrupt 2Fh. Drivers and TSRs use the notifications to load 386
enhanced-mode Windows installable devices, free extended memory, and enable
or disable various device services or features. There are the following
notification functions:

o   Windows Initialization Notification (Interrupt 2Fh Function 1605)

o   Windows Termination Notification (Interrupt 2Fh Function 1606h)

o   Device Call Out (Interrupt 2Fh Function 1607h)

o   Windows Initialization Complete Notification (Interrupt 2Fh Function
    1608h)

o   Windows Begin Exit (Interrupt 2Fh Function 1609h)

MS-DOS device drivers, such as network drivers, use Windows Initialization
Notification to direct 386 enhanced-mode Windows to load a protected-mode
installable device that provides 32-bit support for the real-mode driver
while 386 enhanced-mode Windows runs. Other MS-DOS drivers (for example,
disk-cache drivers) use the same notification to free any extended memory
before Windows starts. The TSRs also use Windows Termination Notification
to reclaim the extended memory when Windows stops.

If an MS-DOS driver or TSR programs installs a corresponding virtual
device, that device can send notifications of its own to the driver or TSR
using Device Call Out.


1.3 Critical Section Handling

Occasionally, an MS-DOS driver or TSR program may need to run for a period
of time that may exceed its regular time slice. In such cases, the driver
can create a critical section that prevents Windows from switching the CPU
away from the driver or program.

A driver starts a critical section by using Begin Critical Section
(Interrupt 2Fh Function 1681h). While the critical section is in effect,
only device interrupts can divert execution from the driver. A driver ends
the critical section by using End Critical Section (Interrupt 2Fh Function
1682h). In general, a driver should end the critical section as soon as
possible to ensure that all drivers and programs in the system receive CPU
time. If a driver starts a critical section n times, it must end the
critical section n times before the critical section is actually released.

Ordinarily, Windows prevents rescheduling of the current virtual machine if
the one-byte, MS-DOS InDOS flag is nonzero. One exception is when a driver
or program issues the MS-DOS Idle interrupt (Interrupt 28h). In such cases,
Windows may reschedule regardless of the value of the InDOS flag. The only
way to prevent this rescheduling is to start a critical section using Begin
Critical Section. While in a critical section, Windows disregards Interrupt
28h.

In previous versions of Windows (for example, Windows/386(TM) version 2.x),
service functions to support critical sections were not supplied. Drivers
and programs achieved a similar effect by incrementing and decrementing the
MS-DOS InDOS flag. Although this method was acceptable for previous
versions of Windows, drivers should not use this method in versions of
Windows that supply Begin Critical Section and End Critical Section
(Interrupt 2Fh Function 1682h).

Drivers and programs that use the InDOS flag method retrieve the address of
the InDOS flag using Get InDOS Flag Address (Interrupt 21h Function 34h).
The function returns the address in the ES:BX register pair. When using
this method, drivers and programs check the flag value before decrementing
because some error conditions (such as when the user types CTRL+C) set the
InDOS flag to zero regardless of its current value. Decrementing the InDOS
flag to a number less than zero is a serious error.


1.4 Releasing the Time Slice

MS-DOS applications can also use the Interrupt 2Fh service functions. In
particular, applications can use Release Current VM Time Slice (Interrupt
2Fh Function 1680h) to release the current virtual machine's time slice. An
MS-DOS application typically uses this function when waiting for user
input. This function helps 386 enhanced-mode Windows multitask more
efficiently by letting it reschedule the CPU for other work immediately,
rather than waiting for the idle application to spend its entire time
slice.


1.5 Virtual-Display Device Services and Notifications

The virtual display device for 386 enhanced-mode Windows also provides
Interrupt 2Fh service and notification functions. Windows display drivers
use these functions to check for and manage screen switching. There are the
following functions:

o   Enable VM-Assisted Save/Restore (Interrupt 2Fh Function 4000h)

o   Notify Background Switch (Interrupt 2Fh Function 4001h)

o   Notify Foreground Switch (Interrupt 2Fh Function 4002h)

o   Enter Critical Section (Interrupt 2Fh Function 4003h)

o   Exit Critical Section (Interrupt 2Fh Function 4004h)

o   Save Video Register State (Interrupt 2Fh Function 4005h)

o   Restore Video Register State (Interrupt 2Fh Function 4006h)

o   Disable VM-Assisted Save/Restore (Interrupt 2Fh Function 4007h)

For more information about using these functions, see Chapter 2, Display
Drivers.


2 Service and Notification Function Reference

The following is an alphabetical listing of the Interrupt 2Fh service and
notification functions.

Interrupt 2Fh Function 1600h

    mov     ax, 1600h   ; Get Enhanced-Mode Windows Installed State
    int     2Fh         ; multiplex interrupt

    test    al, 7Fh
    jz      No_EM_Win   ; 386 enhanced-mode Windows not running
Get Enhanced-Mode Windows Installed State (Interrupt 2Fh Function 1600h)
determines whether 386 enhanced-mode Windows is running. If a program
intends to use a 386 enhanced-mode Windows function, it must first use this
function to make sure that 386 enhanced-mode Windows is running.

This function is valid under all versions of 386 enhanced-mode Windows.


Parameters

This function has no parameters.


Return Value

The return value is 00h or 80h in the AL register if 386 enhanced-mode
Windows is not running. If 386 enhanced-mode Windows is running, the return
value depends on the version of Windows. Windows/386 version 2.x returns
01h or 0FFh. Windows version 3.x returns the major version number in the AL
register, and the minor version number in the AH register.


Example

The following example determines whether 386 enhanced-mode Windows is
running, then determines which version is running.

    mov     ax, 1600h
    int     2Fh
    test    al, 7Fh
    jz      No_EM_Win   ; 386 enhanced-mode Windows not running

    cmp     al, 1
    je      Ver_2x      ; Windows/386 version 2.x running
    cmp     al, -1
    je      Ver_2x      ; Windows/386 version 2.x running

    mov     byte ptr [MajorVer], al
    mov     byte ptr [MinorVer], ah


Interrupt 2Fh Function 1602h

    mov  ax, 1602h            ; Get Enhanced-Mode Windows Entry Point
    int  2Fh                  ; multiplex interrupt

    mov  word ptr [WinAddr], di
    mov  word ptr [WinAddr+2], es ; es:di contains entry-point address

Get Enhanced-Mode Windows Entry Point (Interrupt 2Fh Function 1602h)
returns the address of the 386 enhanced-mode Windows entry-point procedure.
Applications can call this procedure to direct Windows/386 version 2.x to
carry out specific actions.

This function applies to Windows/386 version 2.x only. It is provided under
Windows version 3.x for compatibility reasons.


Parameters

This function has no parameters.


Return Value

The return value contains the Windows entry-point address in the ES:DI
registers.


Comments

Although the Windows entry-point address is the same for every virtual
machine, an application can call this function any number of times.

To direct Windows to carry out a specific action, the application sets the
AX register to 0000h. This function retrieves the current VM identifier and
copies the identifier to the BX register.

Additionally, the application must place a return address in the ES:DI
register pair and use the jmp instruction to transfer control to the
Windows entry point.


Example

The following example shows how to obtain the current VM identifier:

        mov     di, cs
        mov     es, di
        mov     di, OFFSET Win_Return
        xor     ax, ax          ; Get Current VM Identifier
        jmp     [WinAddr]
    Win_Return:
        mov     [VM_Id], bx     ; bx contains the current VM identifier

See Also

    Interrupt 2Fh Function 1683h  Get Current Virtual Machine ID


Interrupt 2Fh Function 1605h

    xor     bx, bx
    mov     es, bx          ; es:bx contains 0000h:0000h

    mov     cx, 0000h
    mov     dx, [Flags]     ; bit 0 clear if 386 enhanced mode,
                            ; set if standard mode

    mov     di, [Ver_Num]   ; major/minor version numbers
                            ; (in high/low bytes)

    xor     si, si
    mov     ds, si          ; ds:si contains 0000h:0000h

    mov     ax, 1605h       ; Windows Initialization Notification
    int     2fh             ; multiplex interrupt

    cmp     cx, 0
    jne     no_initialize   ; if nonzero, don't continue initialization


Windows Initialization Notification (Interrupt 2Fh Function 1605h) notifies
MS-DOS device drivers and TSRs that standard- or 386 enhanced-mode Windows
is starting. Windows calls this function as it starts allowing MS-DOS
device drivers and TSRs that monitor Interrupt 2Fh the opportunity to
prepare for running in the Windows environment.


Parameters

   Flags
   Specifies whether standard- or 386 enhanced-mode Windows is
   initializing. 386 enhanced-mode Windows sets bit 0 to 0; standard-mode
   Windows sets bit 0 to 1. Only bit 0 is used; all other bits reserved and
   undefined.

   Ver_Num
   Specifies the version number of Windows. The major version number is in
   the high-order byte, the minor version number in low-order byte.


Return Value

The return value is 0 in the CX register if all MS-DOS device drivers and
TSRs monitoring Interrupt 2Fh can run in the Windows environment, and
Windows can proceed with initialization. Otherwise, the CX register is
nonzero and Windows must terminate.


Comments

Any MS-DOS device driver or TSR that either cannot run in the Windows
environment, or must adapt its operation when in the Windows environment
should add itself to the Interrupt 2Fh chain and watch for this function.

If the device driver or TSR cannot run in the Windows environment, it
should set the CX register to a nonzero value, display a message informing
the user of its incompatibility with Windows, and return. Windows does not
print a message of its own. Instead, it calls Windows Termination
Notification (Interrupt 2Fh Function 1606h) and returns to MS-DOS.

If the device driver or TSR can run in the Windows environment, it should
do the following:

1.  Call the next device driver or TSR in the Interrupt 2Fh chain to allow
    all device drivers and TSRs in the chain an opportunity to respond to
    this function.

2.  Upon return from the interrupt chain, carry out the following actions:

    o   Free any extended memory. The device driver or TSR takes this
        action only if it has previously allocated extended memory using
        the Extended Memory Specification (XMS) interface.

    o   Switch the processor to real mode, or set the DS:SI register pair
        to the address of an Enable/Disable Virtual 8086 Mode callback
        function. The device driver or TSR takes this action only if it has
        previously switched the processor to virtual 8086 mode. If
        standard-mode Windows is starting, the device driver or TSR must
        switch the processor to real mode--the callback function is
        permitted for 386 enhanced-mode Windows only.

    o   Initialize a Win386_Startup_Info_Struc structure, and copy the
        address of the structure to the ES:BX register pair. The device
        driver or TSR carries out this action only if 386 enhanced-mode
        Windows is starting.

3.  Return (using the iret instruction) but without changing the CX
    register.

For more information about these procedures, see the following Comments
section.

The device driver or TSR must preserve all registers and restore the
original values before returning. The only exceptions to this rule are
changes made to the BX, CX, DS, ES, and SI registers as a result of
following the previous procedure.


Enable/Disable Virtual 8086 Mode CallBack Function

Some device drivers and TSRs, such as expanded memory emulators, switch the
processor to virtual 8086 mode. Because 386 enhanced-mode Windows cannot
start successfully while the processor is in this mode, any device driver
or TSR that switches to virtual 8086 mode must either switch back to real
mode or supply the address of a callback function that can switch between
real and virtual 8086 modes.

Windows uses the callback function to disable virtual 8086 mode before
Windows itself enters protected mode. Windows calls the callback function
again to enable virtual 8086 mode after Windows exits protected mode.
Windows calls the callback function using a far call instruction, and it
specifies which action to take by setting the AX register to 0 or 1.

To disable virtual 8086 mode, Windows sets the AX register to 0, disables
interrupts, and calls the callback function. The function should switch the
processor to real mode, clear the carry flag to indicate success, and
return. If an error occurs, the function sets the carry flag and returns.
Windows checks the carry flag and terminates if it is set.

To enable virtual 8086 mode, Windows set the AX register to 1, disables
interrupts, and calls the callback function. The function should switch the
processor to virtual 8086 mode, clear the carry flag, and return. If an
error occurs, the function sets the carry flag and returns. However,
Windows ignores the carry flag, so if an error occurs no action is taken
and the processor is left in real mode.

Whether an error occurs when enabling or disabling virtual 8086 mode, it is
up to the callback function to display any error message to the user. Also,
the callback function must not enable interrupts unless an error occurs,
and the function sets the carry flag.

A device driver or TSR supplies a callback function by copying the address
of the function to the DS:SI register pair when it processes the Windows
Initialization Notification (Interrupt 2Fh Function 1605h). Windows permits
only one callback function, so the device driver or TSR should first check
to make sure that the DS and SI registers are both zero. If they are
nonzero, the device driver or TSR should set the CX register to a nonzero
value and return, directing Windows to terminate without starting.


Initializing a Win386_Startup_Info_Struc Structure

An MS-DOS device driver or TSR initializes a Win386_Startup_Info_Struc
structure to direct 386 enhanced-mode Windows to load the virtual device
and to reserve the instance data the device driver or TSR needs to operate
in the Windows environment. The device driver or TSR is also responsible
for establishing a chain of startup structures by copying the contents of
the ES:BX register pair to the Next_Dev_Ptr member. It is assumed that any
other device driver or TSR in the Interrupt 2Fh chain will have set the
ES:BX register pair to the address of its own startup structure prior to
returning.

Any device driver or TSR can use a Windows virtual device to help support
its operation in the 386 enhanced-mode Windows environment. To specify a
virtual device, the device driver or TSR sets the SIS_Virt_Dev_File_Ptr
member to the address of the virtual device's filename. The device file is
assumed to be in the Windows SYSTEM directory. The device driver or TSR can
also set the SIS_Reference_Data member to specify additional data to be
passed to the virtual device when loaded.

Any device driver or TSR can reserve instance data for itself. Instance
data is one or more blocks of memory used by the device or TSR, and managed
by Windows. For device drivers or TSRs loaded before 386 enhanced-mode
Windows starts, reserving instance data allows the device driver or TSR to
keep separate data for each virtual machine. Whenever Windows switches
virtual machines, it saves the previous VMs instance data and loads the
current VMs instance data. If a device driver or TSR does not specify
instance data, the same data is used for all virtual machines.

A device driver or TSR reserves instance data by appending an array of
Instance_Item_Struc structures to the Win386_Startup_Info_Struc structure.
The last structure in the array must be set to zero. Each
Instance_Item_Struc structure specifies the starting address and size (in
bytes) of an instance data block.

The device driver or TSR must copy the address of its startup structure to
the ES:BX register pair before returning.


See Also

    Interrupt 2Fh Function 1606h  Windows Termination Notification


Interrupt 2Fh Function 1606h

    mov     dx, [Flags]  ; bit 0 clear if 386 enhanced-mode,
                         ; set if standard-mode

    mov     ax, 1606h    ; Windows Termination Notification
    int     2fh          ; multiplex interrupt
Windows Termination Notification (Interrupt 2Fh Function 1606h) notifies
MS-DOS device drivers and TSRs that standard- or 386 enhanced-mode Windows
is terminating. Windows calls this function as it terminates allowing
MS-DOS device drivers and TSRs that monitor Interrupt 2Fh the opportunity
to prepare for leaving the Windows environment.


Parameters

   Flags
   Specifies whether standard- or 386 enhanced-mode Windows is terminating.
   386 enhanced-mode Windows sets bit 0 to 0; standard-mode Windows sets
   bit 0 to 1. Only bit 0 is used; all other bits reserved and undefined.


Return Value

This function has no return value.


Comments

Windows calls this function when the processor is in real mode.


See Also

    Interrupt 2Fh Function 1605h  Windows Initialization Notification


Interrupt 2Fh Function 1607h

    mov     bx, [DeviceID]  ; device identifier

    mov     ax, 1607h       ; Device Call Out
    int     2fh             ; Multiplex Interrupt
Device Call Out (Interrupt 2Fh Function 1607h) directs an MS-DOS device
driver or TSR to provide information to the calling virtual device.
Although the BX register specifies a device identifier, other registers may
be used to specify the action to take.


Parameters

   DeviceID
   Specifies the device identifier for a virtual device.


Return Value

The return value depends on the specific action requested.


Comments

This function typically is used by a virtual device to communicate with the
driver or TSR that explicitly loaded the virtual device. It is up to the
virtual device to supply a correct device identifier and any other
parameters that specify what action to take. It is up to the driver or TSR
to monitor Interrupt 2Fh, and respond to the function appropriately.

A virtual device can call this function at any time, either in real mode or
after 386 enhanced-mode Windows has started.


See Also

    Interrupt 2Fh Function 1684h  Get Device Entry Point Address


Interrupt 2Fh Function 1608h

    mov     ax, 1608h   ; Windows Initialization Complete Notification
    int     2Fh         ; multiplex interrupt
Windows Initialization Complete Notification (Interrupt 2Fh Function 1608h)
notifies MS-DOS device drivers and TSRs that 386 enhanced-mode Windows has
completed its initialization. Windows calls this function after it has
installed and initialized all virtual devices allowing MS-DOS device
drivers and TSRs that monitor Interrupt 2Fh the opportunity to identify
instance data and perform other functions that are restricted to 386
enhanced-mode Windows initialization.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

When Windows calls this function, all virtual-device initialization is
complete, so a device driver or TSR can call virtual-device entry points.

Windows does not necessarily call this function immediately after calling
Windows Initialization Notification (Interrupt 2Fh Function 1605h). In
particular, virtual devices may call Device Call Out (Interrupt 2Fh
Function 1607h) or other functions prior to Windows calling this function.
In such cases, any MS-DOS device driver or TSR responding to these calls is
responsible for detecting and properly handling these calls.


See Also

    Interrupt 2Fh Function 1605h  Windows Initialization Notification


Interrupt 2Fh Function 1609h

    mov     ax, 1609h   ; Windows Begin Exit
    int     2fh         ; multiplex interrupt
Windows Begin Exit (Interrupt 2Fh Function 1609h) notifies MS-DOS device
drivers and TSRs that Windows is about to terminate. Windows calls this
function when it first begins termination to allow a device driver or TSR
to prepare for a return to a non-Windows environment.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

Windows calls this function at the start of the Sys_VM_Terminate device
control call. All virtual devices still exist, so a device driver or TSR
can call a virtual device's entry point if necessary.

Windows does not call this function in the event of a fatal system crash.

Windows may execute real-mode code after this function has been called and
before 386 enhanced-mode Windows returns to real mode. It is the
responsibility of the device driver or TSR to detect and properly handle
these situations.



Interrupt 2Fh Function 1680h

    mov     ax, 1680h   ; Release Current VM Time-Slice
    int     2Fh         ; multiplex interrupt
Release Current VM Time-Slice (Interrupt 2Fh Function 1680h) directs
Windows to suspend the time slice of the current VM and start a new time
slice for another VM. MS-DOS programs use this function when they are idle,
such as when waiting for user input, to allow 386 enhanced-mode Windows to
run other programs that are not idle.


Parameters

This function has no parameters.


Return Value

The return value is 00h in the AL register if the function is supported.
Otherwise, AL is unchanged (contains 80h).


Comments

Only non-Windows programs should use Release Current VM Time-Slice; Windows
applications should yield by calling the WaitMessage function. A program
can call this function at any time, even when running in environments other
than 386 enhanced-mode Windows environment. If the current environment does
not support the function, the function returns and the program continues
execution.

Windows suspends the current VM only if there is another VM scheduled to
run. If no other VM is ready, the function returns to the program and
execution continues. A program should call the function frequently (for
example, once during each pass of the program's idle loop) to give Windows
ample opportunity to check for other VMs that are ready for execution.

Before calling this function, a program should check that the Interrupt 2Fh
address is not zero.


Example

The following example checks for for a valid Interrupt 2Fh address, then
releases the current VM time slice:

        mov     ax, 352Fh       ; Get Interrupt Vector
        int     21h

        mov     ax, es
        or      ax, bx
        jz      Skip_Idle_Call  ; es:bx is equal to 0:0

        mov     ax, 1680h       ; otherwise, Release Current VM Time-Slice
        int     2Fh
    Skip_Idle_Call:


Interrupt 2Fh Function 1681h

    mov     ax, 1681h   ; Begin Critical Section
    int     2Fh         ; multiplex interrupt
Begin Critical Section (Interrupt 2Fh Function 1681h) prevents Windows from
switching execution from the current VM to some other. MS-DOS device
drivers and TSRs use this function to prevent a task-switch from occurring.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

When a virtual machine is in a critical section, no other task will be
allowed to run except to service hardware interrupts. For this reason, the
critical section should be released using End Critical Section (Interrupt
2Fh Function 1682h) as soon as possible.


See Also

    Interrupt 2Fh Function 1682h  End Critical Section


Interrupt 2Fh Function 1682h

    mov     ax, 1682h   ; End Critical Section
    int     2Fh         ; multiplex interrupt
End Critical Section (Interrupt 2Fh Function 1682h) releases the critical
section previously started using Begin Critical Section (Interrupt 2Fh
Function 1681h). Every call to Begin Critical Section must be followed by a
matching call to End Critical Section.


Parameters

This function has no parameters.


Return Value

This function has no return value.


See Also

    Interrupt 2Fh Function 1681h  Begin Critical Section


Interrupt 2Fh Function 1683h

    mov     ax, 1683h   ; Get Current Virtual Machine ID
    int     2Fh         ; multiplex interrupt
Get Current Virtual Machine ID (Interrupt 2Fh Function 1683h) returns the
identifier for the current virtual machine. MS-DOS device drivers, TSRs,
and other programs use this function to determine which virtual machine is
running. This is especially important for programs that independently
manage separate data or execution contexts for separate virtual machines.


Parameters

This function has no parameters.


Return Value

The return value is the current virtual-machine identifier in the BX
register.


Comments

Each virtual machine has a unique, nonzero identifier. Although Windows
currently runs in virtual machine 1, programs should not rely on this.
Windows assigns the identifier when it creates the virtual machine, and
releases the identifier when it destroys the virtual machine. Since Windows
may reuse identifiers from previous destroyed virtual machines, programs
should monitor changes to virtual machines to ensure no mismatches.



Interrupt 2Fh Function 1684h

    mov     bx, [DeviceID]  ; Device identifier

    mov     ax, 1684h       ; Get Device Entry Point Address
    int     2Fh             ; multiplex interrupt

    mov     word ptr [DevAddr], di
    mov     word ptr [DevAddr+2], es    ; es:di contains entry point address
Get Device Entry Point Address (Interrupt 2Fh Function 1684h) retrieves the
entry point address for a virtual device's service functions. MS-DOS device
drivers or TSRs typically use this function to communicate with virtual
devices they have explicitly loaded.


Parameters

   DeviceID
   Identifies a virtual device.


Return Value

The return value is the entry-point address contained in the ES:DI register
pair if the function is supported. Otherwise, ES:DI contain zero.


Comments

Any virtual device can provide service functions to be used by MS-DOS
programs. For example, the virtual-display device provides services that
the Windows old application program uses to display MS-DOS programs in a
window. It is the responsibility of the MS-DOS program to provide the
appropriate virtual-device identifier. The function returns a valid address
if the virtual device supports the entry point.

MS-DOS programs call the entry point using a far call instruction. The
services provided by the virtual device depend on the device. It is the
responsibility of the MS-DOS program to set registers to values that are
appropriate to the specific virtual device.

For versions of Windows prior to version 3.0, the program must set the
ES:DI register pair to zero before calling this function.


Example

The following retrieves the entry point address for the virtual device
identified by My_Device_ID:

    xor     di, di              ; set es:di to zero for version 2.x
    mov     es, di
    mov     bx, My_Device_ID

    mov     ax, 1684h
    int     2Fh

    mov     ax, es
    or      ax, di
    jz      API_Is_Not_Supported


Interrupt 2Fh Function 1685h

    mov     bx, [VM_Id]             ; virtual-machine identifier
    mov     cx, [Flags]             ; switch conditions

    mov     dx, word ptr [Priority+2]
    mov     si, word ptr [Priority] ; dx:si contains 32-bit priority boost

    mov     es, seg [CallBack]
    mov     di, offset [CallBack]   ; es:di contains callback function address

    mov     ax, 1685h   ; Switch VMs and CallBack
    int     2Fh         ; multiplex interrupt
Switch VMs and CallBack (Interrupt 2Fh Function 1685h) directs Windows to
switch to a specific virtual machine and begin execution. After Windows
switches, it calls the specified callback function allowing a device driver
or TSR to access the data associated with the specified virtual machine.
This function is typically used by MS-DOS device drivers and TSRs that
support networks, and that need to perform functions in a specific virtual
machine.


Parameters

   VM_Id
   Identifies the virtual machine to switch to.

   Flags
   Specifies when to switch. This parameter is a combination of the
   following bit values.

    Bit   Meaning
    -----------------------------------------------------------------------

    0     Set to 1 to wait until interrupts are enabled.

    1     Set to 1 to wait until critical section is released.

   All other bits are reserved and must be 0.

   Priority
   Specifies the priority boost for the virtual machine. It can be one of
   the following values.

    Value                    Meaning
    -----------------------------------------------------------------------

    Critical_Section_Boost   VM priority is boosted by this value when
                             Begin_Critical_Section is called.

    Cur_Run_VM_Boost         Time-slice scheduler boosts each VM in turn by
                             this value to force them to run for their
                             allotted time slice.

    High_Pri_Device_Boost    Time critical operations that should not
                             circumvent the critical section boost should
                             use this boost.

    Low_Pri_Device_Boost     Used by virtual devices that need an event to
                             be processed in a timely fashion but that are
                             not extremely time critical.

    Reserved_High_Boost      Reserved; do not use.

    Reserved_Low_Boost       Reserved; do not use.

    Time_Critical_Boost      Events that must be processed even when
                             another VM is in a critical section should use
                             this boost. For example, VPICD uses this when
                             simulating hardware interrupts.

   The DX register contains the high-order word, the SI register the
   low-order word.

   CallBack
   Points to the callback function.


Return Value

The return value is a cleared carry flag if successful. Otherwise, the
function sets the carry flag and sets the AX register to one of the
following error values.

Value   Meaning
---------------------------------------------------------------------------

0001h   Invalid VM ID

0002h   Invalid priority boost

0003h   Invalid flags


Comments

Windows calls the callback function as soon as the conditions specified by
the Flags parameter are met. This may be before or after Switch VMs and
CallBack returns.

The callback function can carry out any action, but must save and restore
all registers it modifies. The function must execute an iret instruction to
return to Windows. The priority for the virtual machine remains at the
level specified by Priority until the callback function executes the iret
instruction.


See Also

    Interrupt 2Fh Function 1605h Windows Initialization Notification


Interrupt 2Fh Function 1686h

    mov     ax, 1686h   ; Detect Interrupt 31h Services
    int     2Fh         ; multiplex interrupt

    or      ax,0
    jz      int31_avail ; ax is zero if interrupt 31h services available
Detect Interrupt 31h Services (Interrupt 2Fh Function 1686h) determines
whether a set of protected-mode functions are available for use by
protected-mode applications. Applications use the Interrupt 31h services to
allocate and manage protected-mode memory.


Parameters

This function has no parameters.


Return Value

The return value is zero in the AX register if the Interrupt 31h services
are available. Otherwise, the AX register contains a nonzero value.


Comments

Both standard- and 386 enhanced-mode Windows support the Interrupt 31h
services. Interrupt 31h services are only supported for protected-mode
programs.


3 Virtual-Display Device Function Reference

The following is an alphabetical listing of the Virtual-Display Device
(VDD) service functions.



Interrupt 2Fh Function 4000h

    mov ax, 4000h             ; Enable VM-Assisted Save/Restore
    int 2fh

    mov [ModesSupported], al  ; video modes supported while in background
Enable VM-Assisted Save/Restore directs the virtual-display device (VDD) to
notify the virtual machine (VM) application whenever the VDD needs to
access the video hardware registers. The VDD returns a value specifying the
number and type of video modes the VDD supports when the VM application is
in the background.

A VM application calls this function during its initialization.


Parameters

This function has no parameters.


Return Value

The return value is one of the following values, if successful.

Value   Meaning
---------------------------------------------------------------------------

01h     No modes virtualized in background.

02h     Only text modes virtualized in background.

03h     Only text and single-plane graphics modes virtualized.

04h     Only text, single-plane, and VGA multiplane graphics modes
        virtualized.

0FFh    All supported video modes virtualized.

Otherwise, the function returns zero in the AL register if virtualization
is not supported.


Comments

When a VM application calls this function, the VDD disables I/O trapping of
unreadable registers. Thereafter, the VDD calls Save Video Register State
and Restore Video Register State (Interrupt 2Fh Functions 4005h and 4006h)
if it needs to access the video registers. The VM application must provide
an appropriate interrupt handler to process these functions.

When an VM application calls this function, the VDD saves the current state
of the video registers. The VDD uses this saved state later to restore
video registers before it calls Notify Foreground Switch and Restore Video
Register State (Interrupt 2Fh Functions 4002h and 4006h).

After a VM application calls Enable VM-Assisted Save/Restore, the VDD no
longer saves video memory across screen switches; it becomes the
application's responsibility to completely reinitialize video memory after
a Notify Foreground Switch request.


See Also

    Interrupt 2Fh Functions 4002h  Notify Foreground Switch
    Interrupt 2Fh Functions 4005h  Save Video Register State
    Interrupt 2Fh Functions 4006h  Restore Video Register State


Interrupt 2Fh Function 4001h

    mov ax, 4001h   ; Notify Background Switch
    int 2fh
Notify Background Switch notifies a VM application that it is being
switched to the background. The VM application can carry out any actions,
but should do so within 1000ms. This is the amount of time the system waits
before switching the application.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

After switching to the background, the application continues to run unless
it attempts to access video memory. If the video adapter is in a video mode
that the virtual display device (VDD) does not support in the background,
the VDD freezes the application until the application can be switched back
to the foreground.

VM applications that have called Enable VM-Assisted Save/Restore (Interrupt
2Fh Function 4000h) should avoid accessing video memory and registers to
avoid being frozen. Applications that have not called Enable VM-Assisted
Save/Restore, call access video memory and registers since the VDD saves
theses after this function returns.


See Also

    Interrupt 2Fh Function 4000h  Enable VM-Assisted Save/Restore
    Interrupt 2Fh Function 4002h  Notify Foreground Switch


Interrupt 2Fh Function 4002h

    mov ax, 4002h       ; Notify Foreground Switch
    int 2fh
Notify Foreground Switch notifies a VM application that it has been
switched to the foreground and can now access the video memory and
registers without being frozen.

The virtual-display device (VDD) calls this function.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

If the VM application has called Enable VM-Assisted Save/Restore (Interrupt
2Fh Function 4000h), VDD restores the video registers to their state prior
to the call to Enable VM-Assisted Save/Restore; the application is
responsible for restoring video memory. If the VM application has not
called Enable VM-Assisted Save/Restore (Interrupt 2Fh Function 4000h), the
VDD automatically restores both video memory and registers.

Under certain error conditions, the VDD may call this function without
calling a corresponding Notify Background Switch (Interrupt 2Fh Function
4001h).


See Also

    Interrupt 2Fh Function 4000h  Enable VM-Assisted Save/Restore
    Interrupt 2Fh Function 4001h  Notify Background Switch


Interrupt 2Fh Function 4003h

    mov ax, 4003h       ; Enter Critical Section
    int 2fh
Enter Critical Section notifies the virtual-display device that the VM
application has entered a critical section and cannot respond to Save Video
Register State (Interrupt 2Fh Function 4005h).

A VM application calls this function when it has started critical section
processing.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

After the VM application enters the critical section, the virtual-display
device postpones calling Save Video Register State for up to 1000ms or
until the VM application calls Exit Critical Section (Interrupt 2Fh
Function 4004h), whichever comes first.

If time elapses without the VM application calling Exit Critical Section,
the virtual-display device reprograms the video hardware anyway and, when
its operation is complete, calls Notify Foreground Switch (Interrupt 2Fh
Function 4002h) in an attempt to reinitialize the application properly.


See Also

    Interrupt 2Fh Function 4002h  Notify Foreground Switch
    Interrupt 2Fh Function 4004h  Exit Critical Section
    Interrupt 2Fh Function 4005h  Save Video Register State


Interrupt 2Fh Function 4004h

    mov ax, 4004h       ; Exit Critical Section
    int 2fh
Exit Critical Section notifies the virtual-display device that a VM
application has completed a critical section and can now respond to Save
Video Register State (Interrupt 2Fh Function 4005h).

A VM application calls this function when it has completed critical section
processing.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

Calls to Exit Critical Section not preceded by a corresponding call to
Enter Critical Section (Interrupt 2Fh Function 4003h) are ignored.


See Also

    Interrupt 2Fh Function 4003h  Enter Critical Section
    Interrupt 2Fh Function 4005h  Save Video Register State


Interrupt 2Fh Function 4005h

    mov ax, 4005h       ; Save Video Register State
    int 2fh
The Save Video Register State function notifies VM applications that the
virtual-display device (VDD) requires access to the video hardware
registers. The VDD calls this function, for example, when preparing to copy
the entire screen to the clipboard.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The VDD calls this function only if the VM application has called Enable
VM-Assisted Save/Restore (Interrupt 2Fh Function 4000h). VM applications
that receive Save Video Register State must save any data necessary to
restore the current video state and must return within 1000ms. If the
application fails to return in time, the virtual-display device accesses
the video hardware anyway. After accessing the video hardware registers,
the VDD calls Restore Video Register State (Interrupt 2Fh Function 4006h)
to notify the application that it can restore its video state.

The VDD calls Save Video Register State only at times when the hardware
must be reprogrammed for what are essentially brief and nonvisible
operations. For example, the VDD does not call this function prior to
calling Notify Background Switch (Interrupt 2Fh Function 4001h).


See Also

    Interrupt 2Fh Function 4000h  Enable VM-Assisted Save/Restore
    Interrupt 2Fh Function 4001h  Notify Background Switch
    Interrupt 2Fh Function 4006h  Restore Video Register State


Interrupt 2Fh Function 4006h

    mov ax, 4006h   ; Restore Video Register State
    int 2fh
Restore Video Register State notifies a VM application that the
virtual-display device (VDD) has relinquished its access to the video
registers. The VM application should restore the video registers to any
state necessary to continue uninterrupted foreground operation.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

The VDD calls this function only if the VM application has called Enable
VM-Assisted Save/Restore (Interrupt 2Fh Function 4000h). Before calling
this function, the VDD restores any registers it modified to the values
they had when the VM application originally called Enable VM-Assisted
Save/Restore. In other words, every register is guaranteed to be either
unchanged or reset to a previous state; precisely which registers may be
reset is undefined, but the set is restricted to those Sequencer and
Graphics Controller registers that do not affect the display.


See Also

    Interrupt 2Fh Function 4000h  Enable VM-Assisted Save/Restore


Interrupt 2Fh Function 4007h

    mov ax, 4007h       ; Disable VM-Assisted Save/Restore
    int 2fh
Disable VM-Assisted Save/Restore directs the virtual-display device (VDD)
to discontinue notifying the VM application when it needs access to video
registers.

VM applications call this function when they terminate.


Parameters

This function has no parameters.


Return Value

This function has no return value.


Comments

This function directs the VDD to restore I/O trapping of unreadable
registers and to discontinue calling Save Video Register State and Restore
Video Register State (Interrupt 2Fh Functions 4005h and 4006h) when it
needs access to the registers. Furthermore, the VDD ignores any subsequent
calls to Enter Critical Section and Exit Critical Section (Interrupt 2Fh
Functions 4003h and 4004h).

This function does not disable Notify Background Switch and Notify
Foreground Switch (Interrupt 2Fh Functions 4001h and 4002h).


See Also

    Interrupt 2Fh Function 4001h  Notify Background Switch
    Interrupt 2Fh Function 4002h  Notify Foreground Switch
    Interrupt 2Fh Function 4003h  Enter Critical Section
    Interrupt 2Fh Function 4004h  Exit Critical Section
    Interrupt 2Fh Function 4005h  Save Video Register State
    Interrupt 2Fh Function 4006h  Restore Video Register State

4 Structure Reference

The following is an alphabetical listing of the structures used with the
Interrupt 2Fh service and notification functions.



Win386_Startup_Info_Struc

    Win386_Startup_Info_Struc STRUC
    SIS_Version                     db      3, 0
    SIS_Next_Dev_Ptr                dd      ?
    SIS_Virt_Dev_File_Ptr           dd      0
    SIS_Reference_Data              dd      ?
    SIS_Instance_Data_Ptr           dd      0
    Win386_Startup_Info_Struc ENDS
The Win386_Startup_Info_Struc structure contains information that Windows
uses to prepare an MS-DOS device driver or TSR program for operation with
Windows.


Members

   SIS_Version
   Specifies the version number of the structure. 386 enhanced-mode Windows
   uses this member to determine the size of the structure. This member
   should contain 3 in the low-order byte and 10 in the high-order byte to
   indicate that it is version 3.1.

   SIS_Next_Dev_Ptr
   Points to the next structure in the list. The address of the next
   structure must be supplied by the next handler in the Interrupt 2Fh
   chain. A driver or TSR calls the next handler, then sets this member to
   the address returned by the handler in the ES:BX register pair.

   SIS_Virt_Dev_File_Ptr
   Points to a null-terminated string that contains the name of a 386
   enhanced-mode Windows virtual device file. MS-DOS devices such as
   networks use this to force a special 386 enhanced-mode Windows virtual
   device to be loaded. If this member is zero, no device is loaded.

   SIS_Reference_Data
   Specifies reference data for the virtual device. This member, used only
   when SIS_Virt_Dev_File_Ptr is nonzero, is passed to the virtual device
   when it is initialized. The member can contain any value and often
   contains a pointer to some device-specific structure.

   SIS_Instance_Data_Ptr
   Points to a list of data to be instanced, that is, allocated uniquely
   for each new virtual machine. If the member is zero, then no data is
   instanced. Each entry in the list is an Instance_Item_Struc structure.
   The list is terminated with a 32-bit zero.


See Also

    Interrupt 2Fh Function 1605h  Windows Initialization Notification


Instance_Item_Struc

    Instance_Item_Struc STRUC
        IIS_Ptr     dd  ?
        IIS_Size    dw  ?
    Instance_Item_Struc ENDS
The Instance_Item_Struc structure specifies the starting address and size
of a block of instance data.


Members

   IIS_Ptr
   Points to the starting address of a block of instance data.

   IIS_Size
   Specifies the size (in bytes) of the block of instance data pointed to
   by the IIS_Ptr member.

