OpenPrinter2 函数

在设置某些打印机选项时，检索打印子系统中指定打印机、打印服务器或其他类型的句柄的句柄。

语法

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

参数

pPrinterName [in]

指向以 null 结尾的常量字符串的指针，该字符串指定打印机或打印服务器、打印机对象、XcvMonitor 或 XcvPort 的名称。

对于打印机对象，请使用：PrinterName，Job xxxx。 对于 XcvMonitor，请使用：ServerName，XcvMonitor MonitorName。 对于 XcvPort，请使用：ServerName，XcvPort PortName。

Windows Vista： 如果 为 NULL，则表示本地打印服务器。

phPrinter [out]

指向接收打开的打印机或打印服务器对象的句柄的变量的指针。

pDefault [in]

指向 PRINTER_DEFAULTS 结构的指针。 此值可以为 NULL。

pOptions [in]

指向 PRINTER_OPTIONS 结构的指针。 此值可以为 NULL。

返回值

如果函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 有关扩展的错误信息，请调用 GetLastError。

备注

请勿在 DllMain 中调用此方法。

注意

这是一个阻塞或同步函数，可能不会立即返回。 此函数的返回速度取决于运行时因素，例如网络状态、打印服务器配置以及编写应用程序时难以预测的打印机驱动程序实现因素。 从管理与用户界面交互的线程调用此函数可能会使应用程序看起来无响应。

此函数的 ANSI 版本未实现，返回ERROR_NOT_SUPPORTED。

pDefault 参数可用于指定用于打印 StartDocPrinter 函数提交的文档的数据类型和设备模式值。 但是，可以在文档启动后使用 SetJob 函数替代这些值。

可以调用 OpenPrinter2 函数来打开打印服务器的句柄或确定客户端对打印服务器的访问权限。 为此，请在 pPrinterName 参数中指定打印服务器的名称，将 PRINTER_DEFAULTS 结构的 pDatatype 和 pDevMode 成员设置为 NULL，并将 DesiredAccess 成员设置为指定服务器访问掩码值（如 SERVER_ALL_ACCESS）。 完成句柄后，将其传递给 ClosePrinter 函数以将其关闭。

使用 PRINTER_DEFAULTS 结构的 DesiredAccess 成员指定必要的访问权限。 访问权限可以是以下项之一。

所需访问权限值	含义
PRINTER_ACCESS_ADMINISTER	执行管理任务，例如 SetPrinter 提供的任务。
PRINTER_ACCESS_USE	执行基本打印操作。
PRINTER_ALL_ACCESS	执行除 SYNCHRONIZE 之外的所有管理任务和基本打印操作。 请参阅 标准访问权限。
PRINTER_ACCESS_MANAGE_LIMITED	执行管理任务，例如 SetPrinter 和 SetPrinterData 提供的任务。 此值从 Windows 8.1 开始可用。
泛型安全值，例如WRITE_DAC	允许特定的控制访问权限。 请参阅 标准访问权限。

如果用户无权使用所需的访问权限打开指定的打印机或打印服务器， OpenPrinter2 调用将失败， GetLastError 将返回值ERROR_ACCESS_DENIED。

当 pPrinterName 是本地打印机时，OpenPrinter2 将使用 pOptions 忽略PRINTER_OPTIONS结构指向的 dwFlags 的所有值，PRINTER_OPTION_CLIENT_CHANGE除外。 如果传递后者，则 OpenPrinter2 将返回ERROR_ACCESS_DENIED。 因此，打开本地打印机时， OpenPrinter2 与 OpenPrinter 没有优势。

Windows Vista：OpenPrinter2 返回的打印机数据从本地缓存中检索，除非在 pOptions 引用的PRINTER_OPTIONS结构的 dwFlags 字段中设置了PRINTER_OPTION_NO_CACHE标志。

示例

在此示例中，当PRINTER_ACCESS_MANAGE_LIMITED传递到 PRINTER_DEFAULTS 结构，并且用户没有适当的权限时，OpenPrinter2 将失败。

// 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);
}

有关演示如何使用此函数的示例程序，请参阅 如何：使用 GDI 打印 API 进行打印。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
标头	Winspool.h (包括 Windows.h)
库	Winspool.lib
DLL	Spoolss.dll
Unicode 和 ANSI 名称	OpenPrinter2W (Unicode) 和 OpenPrinter2A (ANSI)

另请参阅

打印

打印后台处理程序 API 函数

ClosePrinter

PRINTER_DEFAULTS

PRINTER_OPTIONS

SetJob

SetPrinter

StartDocPrinter

OpenPrinter