OpenPrinter2 function
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 |
|
| Library |
|
| DLL |
|
| Unicode and ANSI names |
OpenPrinter2W (Unicode) and OpenPrinter2A (ANSI) |