ExtDeviceMode

int ExtDeviceMode(
  HWND hWnd, 
  HANDLE hDriver, 
  LPDEVMODE lpDevModeOutput, 
  LPSTR lpDeviceName, 
  LPSTR lpPort, 
  LPDEVMODE lpDevModeInput, 
  LPSTR lpProfile, 
  WORD  wMode
 );
 

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.

• 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.

hWnd

Parent window for the dialog box.

hDriver

Module instance of the device driver.

lpDevModeOutput

Address of a DEVMODE structure. The driver writes the initialization information supplied in the lpDevModeInput parameter to this structure.

lpDeviceName

Address of a null-terminated string that contains the name of the device, such as PCL/HP LaserJet.

lpPort

Address of a null-terminated string that contains the name of the port to which the device is connected, such as LPT1.

lpDevModeInput

Address of a DEVMODE structure that contains initialization information set by the application.

lpProfile

Address of 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

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:

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.

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.