| #include <print.h> |
| int ExtDeviceMode(hwnd, hDriver, lpdmOutput, lpszDevice, lpszPort, lpdmInput, lpszProfile, fwMode) | |||||
| HWND hwnd; | /* handle of window, */ | ||||
| HANDLE hDriver; | /* handle of driver, */ | ||||
| LPDEVMODE lpdmOutput; | /* address of structure for driver output | */ | |||
| LPSTR lpszDevice; | /* string for name of device | */ | |||
| LPSTR lpszPort; | /* string for name of port | */ | |||
| LPDEVMODE lpdmInput; | /* address of structure for driver input | */ | |||
| LPSTR lpszProfile; | /* string for profile filename | */ | |||
| WORD fwMode; | /* operations mask, */ | ||||
The ExtDeviceMode function retrieves or modifies device initialization information for a given printer driver or displays a driver-supplied dialog box for configuring the printer driver. Printer drivers that support device initialization by applications export ExtDeviceMode so that applications can call it.
hwnd
Identifies a window. If the application calls the ExtDeviceMode function to display a dialog box, the specified window is the parent window of the dialog box.
hDriver
Identifies the device-driver module. The GetModuleHandle function or LoadLibrary function returns a module handle.
lpdmOutput
Points to a DEVMODE structure. The driver writes the initialization information supplied in the lpdmInput parameter to this structure. The DEVMODE structure has the following form:
#include <print.h>
typedef struct tagDEVMODE { /* dm */
char dmDeviceName[CCHDEVICENAME];
UINT dmSpecVersion;
UINT dmDriverVersion;
UINT dmSize;
UINT dmDriverExtra;
DWORD dmFields;
int dmOrientation;
int dmPaperSize;
int dmPaperLength;
int dmPaperWidth;
int dmScale;
int dmCopies;
int dmDefaultSource;
int dmPrintQuality;
int dmColor;
int dmDuplex;
int dmYResolution;
int dmTTOption;
} DEVMODE;For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.
lpszDevice
Points to a null-terminated string that contains the name of the printer device—for example, PCL/HP LaserJet.
lpszPort
Points to a null-terminated string that contains the name of the port to which the device is connected—for example, LPT1.
lpdmInput
Points to a DEVMODE structure that supplies initialization information to the printer driver.
lpszProfile
Points to a null-terminated string that contains the name of the initialization file, where initialization information is recorded and read from. If this parameter is NULL, WIN.INI is the default initialization file.
fwMode
Specifies a mask of values that determines the operations the function performs. If this parameter is zero, the ExtDeviceMode function returns the number of bytes required by the printer driver's DEVMODE structure. Otherwise, the fwMode parameter can be one or more of the following values (to change the print settings, the application must specify at least one input value and one output value):
| Value | Meaning |
| DM_IN_BUFFER | Input value. Before prompting, copying, or updating, this value merges the printer driver's current print settings with the settings in the DEVMODE structure identified by the lpdmInput parameter. The structure is updated only for those members indicated by the application in the dmFields member. This value is also defined as DM_MODIFY. |
| DM_IN_PROMPT | Input value. This value presents the printer driver's Print Setup dialog box and then changes the settings in the printer's DEVMODE structure to values specified by the user. This value is also defined as DM_PROMPT. |
| DM_OUT_BUFFER | Output value. This value writes the printer driver's current print settings (including private data) to the DEVMODE structure identified by the lpdmOutput parameter. The calling application must allocate a buffer sufficiently large to contain the information. If this bit is clear, lpdmOutput can be NULL. This value is also defined as DM_COPY. |
| DM_OUT_DEFAULT | Output value. This value updates graphics device interface (GDI)'s current printer environment and the WIN.INI file, using the contents of the printer driver's DEVMODE structure. Avoid using this value, because it permanently changes the print settings for all applications. This value is also defined as DM_UPDATE. |
If the fwMode parameter is zero, the return value is the size of the buffer required to contain the printer driver initialization data. (Note that this buffer can be larger than a DEVMODE structure, if the printer driver appends private data to the structure.) If the function displays the initialization dialog box, the return value is either IDOK or IDCANCEL, depending on which button the user selects. If the function does not display the dialog box and is successful, the return value is IDOK. The return value is less than zero if the function fails.
The ExtDeviceMode function is part of the printer's device driver and not part of GDI. To use this function, an application must retrieve the address of the function by calling the LoadLibrary and GetProcAddress functions, and it must include the header file PRINT.H. The application can then use the address to set up the printer.
ExtDeviceMode is not supported by all printer drivers. If the GetProcAddress function returns NULL, ExtDeviceMode is not supported.
To make changes to print settings that are local to the application, an application should call the ExtDeviceMode function, specifying the DM_OUT_BUFFER value; modify the returned DEVMODE structure; and then pass the modified DEVMODE structure back to ExtDeviceMode, specifying DM_IN_BUFFER and DM_OUT_BUFFER (combined by using the OR operator). The DEVMODE structure returned by this second call to ExtDeviceMode can be used as an argument in a call to the CreateDC function.
Any call to ExtDeviceMode must set either DM_OUT_BUFFER or DM_OUT_DEFAULT.
An application can set the fwMode parameter to DM_OUT_BUFFER to obtain a DEVMODE structure filled with the printer driver's initialization data. The application can then pass this structure to the CreateDC function to set a private environment for the printer device context.
CreateDC, DeviceMode, GetModuleHandle, GetProcAddress, LoadLibrary