OpenPrinter2 function

Article
01/07/2021

Retrieves a handle to the specified printer, print server, or other types of handles in the print subsystem, while setting some of the printer options.

Syntax

BOOL OpenPrinter2(
  _In_  LPCTSTR            pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault,
  _In_  PPRINTER_OPTIONS   pOptions
);

Parameters

pPrinterName [in]

A pointer to a constant null-terminated string that specifies the name of the printer or print server, the printer object, the XcvMonitor, or the XcvPort.

For a printer object, use: PrinterName,Job xxxx. For an XcvMonitor, use: ServerName,XcvMonitor MonitorName. For an XcvPort, use: ServerName,XcvPort PortName.

Windows Vista: If NULL, it indicates the local print server.

phPrinter [out]

A pointer to a variable that receives a handle to the open printer or print server object.

pDefault [in]

A pointer to a PRINTER_DEFAULTS structure. This value can be NULL.

pOptions [in]

A pointer to a PRINTER_OPTIONS structure. This value can be NULL.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. For extended error information, call GetLastError.

Remarks

Do not call this method in DllMain.

Note

This is a blocking or synchronous function and might not return immediately. How quickly this function returns depends on run-time factors such as network status, print server configuration, and printer driver implementation factors that are difficult to predict when writing an application. Calling this function from a thread that manages interaction with the user interface could make the application appear to be unresponsive.

The ANSI version of this function is not implemented and returns ERROR_NOT_SUPPORTED.

The pDefault parameter enables you to specify the data type and device mode values that are used for printing documents submitted by the StartDocPrinter function. However, you can override these values by using the SetJob function after a document has been started.

You can call the OpenPrinter2 function to open a handle to a print server or to determine client access rights to a print server. To do this, specify the name of the print server in the pPrinterName parameter, set the pDatatype and pDevMode members of the PRINTER_DEFAULTS structure to NULL, and set the DesiredAccess member to specify a server access mask value such as SERVER_ALL_ACCESS. When you are finished with the handle, pass it to the ClosePrinter function to close it.

Use the DesiredAccess member of the PRINTER_DEFAULTS structure to specify the necessary access rights. The access rights can be one of the following.

Desired Access value	Meaning
PRINTER_ACCESS_ADMINISTER	To perform administrative tasks, such as those provided by SetPrinter.
PRINTER_ACCESS_USE	To perform basic printing operations.
PRINTER_ALL_ACCESS	To perform all administrative tasks and basic printing operations except SYNCHRONIZE. See Standard Access Rights.
PRINTER_ACCESS_MANAGE_LIMITED	To perform administrative tasks, such as those provided by SetPrinter and SetPrinterData. This value is available starting from Windows 8.1.
generic security values, such as WRITE_DAC	To allow specific control access rights. See Standard Access Rights.

If a user does not have permission to open a specified printer or print server with the desired access, the OpenPrinter2 call will fail, and GetLastError will return the value ERROR_ACCESS_DENIED.

When pPrinterName is a local printer, then OpenPrinter2 ignores all values of the dwFlags that the PRINTER_OPTIONS structure pointed to using pOptions, except PRINTER_OPTION_CLIENT_CHANGE. If the latter is passed, then OpenPrinter2 will return ERROR_ACCESS_DENIED. Accordingly, when opening a local printer, OpenPrinter2 provides no advantage over OpenPrinter.

Windows Vista: The printer data returned by OpenPrinter2 is retrieved from a local cache unless the PRINTER_OPTION_NO_CACHE flag is set in the dwFlags field of the PRINTER_OPTIONS structure referenced by pOptions.

Examples

In this example, OpenPrinter2 fails when PRINTER_ACCESS_MANAGE_LIMITED is passed to the PRINTER_DEFAULTS structure, and the user does not have the appropriate permission.

// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;

// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
                     &printer,                  // Printer handle
                     &defaults,                 // Printer defaults
                     nullptr));                 // Printer options

assert(GetLastError() == ERROR_ACCESS_DENIED);

if (printer)
{
    ClosePrinter(printer);
}

For a sample program that shows how to use this function, see How To: Print Using the GDI Print API.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Winspool.h (include Windows.h)
Library	Winspool.lib
DLL	Spoolss.dll
Unicode and ANSI names	OpenPrinter2W (Unicode) and OpenPrinter2A (ANSI)