OpenPrinter 函数
OpenPrinter 函数检索指定打印机或打印服务器或打印子系统中其他类型的句柄的句柄。
语法
BOOL OpenPrinter(
_In_ LPTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault
);
参数
-
pPrinterName [in]
-
指向以 null 结尾的字符串的指针，该字符串指定打印机或打印服务器、打印机对象、XcvMonitor 或 XcvPort 的名称。
对于打印机对象，请使用：PrinterName、Job xxxx。 对于 XcvMonitor，请使用：ServerName、XcvMonitor MonitorName。 对于 XcvPort，请使用：ServerName、XcvPort PortName。
如果 为 NULL，则表示本地打印机服务器。
-
phPrinter [out]
-
指向变量的指针，该变量接收打开的打印机或打印服务器对象的句柄 (非线程安全) 。
phPrinter 参数可以返回 Xcv 句柄，以便与 XcvData 函数一起使用。 有关 XcvData 的详细信息，请参阅 DDK。
-
pDefault [in]
-
指向 PRINTER_DEFAULTS 结构的指针。 此值可以为 NULL。
返回值
如果函数成功，则返回值为非零值。
如果函数失败，则返回值为零。
注解
请勿在 DllMain 中调用此方法。
注意
通过调用远程打印机的 OpenPrinter 为远程打印机获取的句柄通过打印后台处理程序服务中的本地缓存访问打印机。 此缓存不实时准确。 若要获取准确的数据，请将 OpenPrinter 调用替换为 OpenPrinter2 ，并将 pOptions.dwFlags 设置为 PRINTER_OPTION_NO_CACHE。 请注意，只有 OpenPrinter2W 正常工作。 函数返回使用其他打印 API 调用并绕过本地缓存的打印机句柄。 此方法在等待与远程打印机的网络通信时阻止，因此它可能不会立即返回。 此函数的返回速度取决于运行时因素，例如网络状态、打印服务器配置以及编写应用程序时难以预测的打印机驱动程序实现因素。 从管理用户界面交互的线程调用此函数可能会使应用程序显得无响应。
注意
调用远程打印机 OpenPrinter 获取的句柄将通过打印后台处理程序服务中的本地缓存访问打印机。 根据设计，此缓存并非实时准确。 如果需要获取准确的数据，请将 OpenPrinter 调用替换为 OpenPrinter2 ，并将 pOptions.dwFlags 设置为 PRINTER_OPTION_NO_CACHE。 请注意，只有 OpenPrinter2W 正常工作。 这样，函数将返回一个打印机句柄，该句柄使其他打印 API 调用绕过本地缓存。 请注意，此方法在等待与远程打印机的往返网络通信时会阻止，因此它可能不会立即返回。 此函数返回的速度取决于运行时因素（例如网络状态、打印服务器配置和打印机驱动程序实现），这些因素在编写应用程序时难以预测。 因此，从管理与用户界面交互的线程调用此函数可能会使应用程序看起来无响应。
phPrinter 指向的句柄不是线程安全的。 如果调用方需要在多个线程上同时使用它，则必须使用同步函数提供对打印机句柄的自定义 同步访问。 为了避免编写自定义代码，应用程序可以根据需要在每个线程上打开打印机句柄。
使用 pDefault 参数可以指定用于打印 StartDocPrinter 函数提交的文档的数据类型和设备模式值。 但是，可以在文档启动后使用 SetJob 函数替代这些值。
在 StartDocPrinter 调用的 pDocInfo 参数中传递的 DOC_INFO_1 pDatatype 成员的 pDatatype 成员的值为“RAW”时，不使用 pDefault 参数的 PRINTER_DEFAULTS 结构中定义的 DEVMODE 设置。 将高级文档 (（例如 Adobe PDF 或 Microsoft Word 文件) 或其他打印机数据） (PCL、PS 或 HPGL) 直接发送到 pDatatype 设置为“RAW”的打印机时，文档必须以硬件理解的语言充分描述 DEVMODE 样式的打印作业设置。
可以调用 OpenPrinter 函数来打开打印服务器的句柄或确定客户端对打印服务器的访问权限。 为此，请在 pPrinterName 参数中指定打印服务器的名称，将 PRINTER_DEFAULTS 结构的 pDatatype 和 pDevMode 成员设置为 NULL，并将 DesiredAccess 成员设置为指定服务器访问掩码值，例如SERVER_ALL_ACCESS。 完成句柄后，将其传递给 ClosePrinter 函数以将其关闭。
使用 PRINTER_DEFAULTS 结构的 DesiredAccess 成员指定打印机所需的访问权限。 访问权限可以是以下其中一项。 (如果 pDefault 为 NULL，则访问权限为 PRINTER_ACCESS_USE.)
| 所需访问值 | 含义 |
|---|---|
| PRINTER_ACCESS_ADMINISTER | 执行管理任务，例如 SetPrinter 提供的任务。 |
| PRINTER_ACCESS_USE | 执行基本打印操作。 |
| PRINTER_ALL_ACCESS | 若要执行除 SYNCHRONIZE (之外的所有管理任务和基本打印操作，请参阅 标准访问权限。 |
| PRINTER_ACCESS_MANAGE_LIMITED | 执行管理任务，例如 SetPrinter 和 SetPrinterData 提供的任务。 此值从Windows 8.1开始可用。 |
| 泛型安全值，例如 WRITE_DAC | 允许特定控制访问权限。 请参阅 标准访问权限。 |
如果用户无权使用所需访问权限打开指定的打印机或打印服务器， OpenPrinter 调用将失败，返回值为零， GetLastError 将返回ERROR_ACCESS_DENIED的值。
示例
有关使用此函数的示例程序，请参阅 如何：使用 GDI 打印 API 进行打印。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 |
Windows 2000 Professional [仅限桌面应用] |
| 最低受支持的服务器 |
Windows 2000 Server [仅限桌面应用] |
| 标头 |
|
| 库 |
|
| DLL |
|
| Unicode 和 ANSI 名称 |
OpenPrinterW (Unicode) 和 OpenPrinterA (ANSI) |