DrvConvertDevMode

A printer interface DLL's DrvConvertDevMode function is responsible for converting a printer's DEVMODE structure from one version to another.

BOOL
  DrvConvertDevMode(
    LPTSTR  pPrinterName,
    PDEVMODE  pdmIn,
    PDEVMODE  pdmOut,
    PLONG  pcbNeeded,
    DWORD  fMode
    );

Parameters

pPrinterName

Caller-supplied pointer to a printer name string.

pdmIn

Caller-supplied pointer to an input DEVMODE structure. If fMode is CDM_DRIVER_DEFAULT, this pointer is NULL.

pdmOut

Caller-supplied pointer to a buffer to receive an output DEVMODE structure. If fMode is CDM_CONVERT the buffer contains, on input, a valid DEVMODE structure indicating the target driver version.

pcbNeeded

Caller-supplied pointer to the size, in bytes, of the buffer pointed to by pdmOut. On output, the printer interface DLL should overwrite the received size value with the actual size of the converted DEVMODE structure. If the received buffer is too small, the printer interface DLL should overwrite the received size value with the required buffer size.

fMode

Caller-supplied bit flag indicating the type of operation to be performed. This can be one of the flags in the following table.

Flag	Definition
CDM_CONVERT
	The function should convert the contents of the input DEVMODE structure (pointed to by pdmIn) into a new DEVMODE structure, and place the result in the DEVMODE structure pointed to by pdmOut. The initial contents of the received output DEVMODE structure (pointed to by pdmOut) should be used to determine the output version.
CDM_CONVERT351
	The function should convert the contents of the input DEVMODE structure (pointed to by pdmIn), creating an output DEVMODE structure that is compatible with Windows NT 3.51, and place the result in the DEVMODE structure pointed to by pdmOut. If the driver does not support a DEVMODE structure for Windows NT 3.51, the function should convert the input DEVMODE to the current version.
CDM_DRIVER_DEFAULT
	The function should copy the current version of its default DEVMODE structure to the buffer pointed to by pdmOut.

Return Value

If the operation succeeds, the function should return TRUE; otherwise, it should call SetLastError to set an error code, and return FALSE.

Headers

Declared in winddiui.h. Include winddiui.h.

Comments

In a client/server environment, a client might be running one version of the operating system or printer driver while the server (spooler) is running another, which means a printer's DEVMODE structure definition might be inconsistent between the client and server. The DrvConvertDevMode function must be capable of performing conversions from one version of the printer's DEVMODE structure to another.

When converting from one DEVMODE version to another, both public and private DEVMODE members must be included.

The printer name pointed to by pPrinterName can be used as an input argument to the OpenPrinter function, which can be called to obtain stored default values when the CDM_DRIVER_DEFAULT flag is received.

The function should verify that both pdmIn and pdmOut (if applicable) point to valid DEVMODE structures. If they don't, the function should call SetLastError(ERROR_INVALID_PARAMETER) and return FALSE. If the output DEVMODE size specified by pcbNeeded is too small, the driver should overwrite the size value supplied by pcbNeeded with the required buffer size, call SetLastError(ERROR_INSUFFICIENT_BUFFER), and return FALSE.

The DrvConvertDevMode function runs in the spooler's context and must therefore not display a user interface.