Configuring Printer Settings programmatically

The usage of DocumentProperties and SetPrinter API functions gives an opportunity to change the printer settings. But, when using them, I could not have a stable method of changing settings on all Windows OS versions. Below, all possible methods of changing printer parameters will be described and also the solution of how to obtain the stabler behavior for different Windows OS versions. In this article, I will describe the method of setting the printer settings and the problems I faced on different OS versions.

Contents:

Changing Printer Settings
Changing Settings Using the DocumentProperties Function
Changing Settings Using the SetPrinter Function
Description of the Project Modules

Changing Printer Settings

You can change the printer settings with the help of API:

DocumentProperties – retrieves and changes the printer parameters;
SetPrinter – determines data for printer, changes the state, and also can manage the printing and tasks.

Changing Settings Using the DocumentProperties Function

To use the DocumentProperties function to change the printer settings, you should do as follows:

Get the number of bytes required for the DEVMODE structure:

DWORD dwNeeded = ::DocumentProperties(NULL, hPrinter, szPrinterName, NULL, NULL, 0)

where

hPrinter – a HANDLE to your local printer that can be obtained by calling OpenPrinter or AddPrinter;
szPrinterName – name of the local printer.

Allocate memory for the DEVMODE structure:

LPDEVMODE pDevMode = (LPDEVMODE)::malloc(dwNeeded);

Get the current printer settings with the DM_OUT_BUFFER parameter:

::DocumentProperties(NULL, hPrinter, szPrinterName, pDevMode, NULL, DM_OUT_BUFFER);

DM_OUT_BUFFER – points that the function will write the current settings to the pDevMode structure.
Change the required parameters:

// check that the driver supports changes 
if(pDevMode ->dmFields & DM_COPIES )
    {
	      pDevMode ->dmCopies = 3;   		// define the number of copies as 3
        pDevMode ->dmFields |= DM_COPIES;  // define, which field was changed
    }

The next call of DocumentProperties with DM_IN_BUFFER and DM_OUT_BUFFER parameters configures settings for the printer. The returned structure can be used as an argument in the call of the CreateDC function:

::DocumentProperties(NULL, hPrinter, szPrinterName, pDevMode, pDevMode, DM_IN_BUFFER | DM_OUT_BUFFER);

The utilizing of the DocumentProperties function doesn’t always make it possible to change the printer settings on different OS versions. Let’s take a look at the solution of this problem below.

Changing Settings Using the SetPrinter Function

To use the SetPrinter function to change the printer settings, do as follows:

Call the GetPrinter function to get the size of the PRINTER_INFO_2 structure:

::GetPrinter(hPrinter, 2, 0, 0, &dwNeeded);

where

hPrinter – a HANDLE to your local printer that can be obtained by calling OpenPrinter or AddPrinter;
2 – a level, which indicates that the size of the PRINTER_INFO_2 structure is inquired and that it contains the detailed information about the printer (for more detailed information about different structure types, see MSDN);
dwNeeded – size of the PRINTER_INFO_2 structure in bytes.
Allocate memory for the PRINTER_INFO_2 structure:

PRINTER_INFO_2 *pi2 = (PRINTER_INFO_2 *)::GlobalAlloc(GPTR,dwNeeded);

Get the PRINTER_INFO_2 structure:

GetPrinter(hPrinter, 2, (LPBYTE)pi2, dwNeeded, &dwNeeded);

Change the required parameters:

// check that the driver supports the changes 
    if(pi2->pDevMode->dmFields & DM_PAPERSIZE )
    {
// define the page size as A3
         pi2->pDevMode->dmPaperSize = DMPAPER_A3;
// define, which field was changed
         pi2->pDevMode->dmFields |= DM_PAPERSIZE;      
 }

Update data:

::DocumentProperties (NULL, hPrinter, PrinterName, pi2->pDevMode, pi2->pDevMode, DM_IN_BUFFER | DM_OUT_BUFFER);

Update the printer information by calling the SetPrinter function:

::SetPrinter(hPrinter, 2, (LPBYTE)pi2, 0);

On some operating systems, the call of the SetPrinter function causes the program crash or this function do not work. The research of this problem brought me to the following results.

Before calling the SetPrinter function, call the DocumentProperties function with some additional actions to update the DEVMODE structure. The following piece of code demonstrates the methods of settings updating for different operating systems:

PDEVMODE pDevmodeSupport = NULL;
if( WinVerUtils::IsWin2k() )
{
	 // the DevmodeCopy function copies the fields from one structure to another byte by byte
 DevmodeCopy(srcDevmode, *pi2.pDevMode);
 // the ChangePrinterProperties function changes the printer parameters and returns the changed structure
 pDevmodeSupport = ChangePrinterProperties(szPrinterName, &srcDevmode, Printer);
}
else if( WinVerUtils::IsWin2k3OrLower() )
{
 DevmodeCopy(srcDevmode, *pi2.pDevMode);
 // an attempt to change the printer parameters
        pDevmodeSupport = ChangePrinterProperties(szPrinterName, &srcDevmode, NULL);
if ( pDevmodeSupport )
{
	// do not try to install the security descriptor
pi2.pSecurityDescriptor = NULL; 
// restore the bit mask of the supported data
       		pi2.pDevMode->dmFields = pDevmodeSupport->dmFields;
// dmDriverExtra contains an amount of private data that follows the structure immediately 
       		pi2.pDevMode->dmDriverExtra = 0; 
}
}
else if( WinVerUtils::IsWin2008R2() )
{
	// save the bit mask of the supported data
pDevmodeSupport = ChangePrinterProperties(szPrinterName, &srcDevmode, NULL);
       if ( pDevmodeSupport )
        {
            DevmodeCopy(srcDevmode, *pi2.pDevMode);
	     // restore the bit mask
            pi2.pDevMode->dmFields = pDevmodeSupport->dmFields;
        }
}
else
{
 DevmodeCopy(srcDevmode, *pi2.pDevMode);
}
if ( pDevmodeSupport )
{
::free(pDevmodeSupport);
}

Let’s consider the function:

ChangePrinterProperties(  IN CString& szPrinterName, 
  OUT PRINTER_INFO_2& pi2,
  IN DEVMODE& srcDevmode,
  IN HANDLE hPrinter )

This function returns the modified DEVMODE structure after the the pSrcDevMode structure was used with the help of the DocumentProperties API function.

{
       …
	pDevMode->dmFields |= pSrcDevMode->dmFields & DM_YRESOLUTION;
    	pDevMode->dmYResolution = pSrcDevMode->dmYResolution;
if ( IDOK != ::DocumentProperties(NULL, hPrinter, szPrinterName.GetBuffer(), pDevMode, pDevMode, DM_IN_BUFFER | DM_OUT_BUFFER) )
    	{
//The function fails. To get extended error information, call GetLastError.
    	}

Using the method described above I managed to obtain the stable method to apply the settings to local printers on different Windows OS versions.

Description of the Project Modules

PrinterUtils.h, PrinterUtils.cpp

The function that returns the DEVMODE structure after applying the pSrcDevMode structure:

PDEVMODEW ChangePrinterProperties( IN CString& szPrinterName, 
    IN PDEVMODE  pSrcDevMode, 
    IN HANDLE    hPrinter )

The function that defines the DEVMODE printer structure for the current OS:

VOID ChangePrinterSettingsForCurrentOS( IN  CString&       szPrinterName, 
               			      OUT PRINTER_INFO_2& pi2, 
         				      IN  DEVMODE&        srcDevMode, 
         				      IN  HANDLE           hPrinter )

The function that performs copying from fromDevMode to toDevMode by fields:

VOID DevmodeCopy( IN const DEVMODE& fromDevMode, OUT DEVMODE& toDevMode )

The fucntion that sets the settings with devMode to the printer with the szPrinterName name:

BOOL SetPrinterSetting( IN CString& szPrinterName, IN DEVMODE& devMode )

WinVerUtils.h, WinVerUtils.cpp contain the functions for checking of the current OS version. For example:

BOOL WinVerUtils::IsWin2k();

WinErrorUtils.h contains the function of obtaining the error code description:

CString winErrorUtils::GetErrorDescription( DWORD dwErrorCode )

traceUtils.h contains the macros for the displaying of the text and error description in the console.

#define PRINT(message) \
            std::wcout<<message<<"\n";
#define PRINT_ERROR(error) \
            PRINT(winErrorUtils::GetErrorDescription(error).GetBuffer());