SetPrinterDataEx 函数

  • 项目

SetPrinterDataEx 函数设置打印机或打印服务器的配置数据。 函数将配置数据存储在打印机的注册表项下。

语法

DWORD SetPrinterDataEx(
  _In_ HANDLE  hPrinter,
  _In_ LPCTSTR pKeyName,
  _In_ LPCTSTR pValueName,
  _In_ DWORD   Type,
  _In_ LPBYTE  pData,
  _In_ DWORD   cbData
);

parameters

hPrinter [in]

函数为其设置配置数据的打印机或打印服务器的句柄。 使用 OpenPrinter、 OpenPrinter2 或 AddPrinter 函数检索打印机句柄。

pKeyName [in]

指向以 null 结尾的字符串的指针，该字符串指定包含要设置的值的键。 如果指定的键或子项不存在，函数将创建它们。

若要存储可在 DS) 目录服务 (发布的配置数据，请指定以下预定义注册表项之一。

值 含义
SPLDS_DRIVER_KEY
 打印机驱动程序使用此密钥来存储驱动程序属性。
SPLDS_SPOOLER_KEY
 保留。 仅由打印后台处理程序用于存储内部后台处理程序属性。
SPLDS_USER_KEY
 应用程序使用此密钥来存储打印机属性，例如打印机资产编号。

仅当架构中存在相应的属性时，存储在 SPLDS_USER_KEY 键下的值才会在目录服务中发布。 域管理员必须创建 属性（如果尚不存在）。 若要在使用 SetPrinterDataEx 添加或更改值后发布用户定义的属性，请调用 Level = 7 且将 PRINTER_INFO_7 的 dwAction 成员设置为 DSPRINT_UPDATE 的 SetPrinter。

可以指定其他密钥来存储非 DS 配置数据。 使用反斜杠 ( \ ) 字符作为分隔符来指定具有一个或多个子项的路径。

如果 hPrinter 是打印机的句柄，而 pKeyName 为 NULL 或空字符串， 则 SetPrinterDataEx 返回 ERROR_INVALID_PARAMETER。

如果 hPrinter 是打印服务器的句柄，则忽略 pKeyName 。

请勿使用 SPLDS_SPOOLER_KEY。 若要更改后台处理程序打印机属性，请使用 Level = 2 的 SetPrinter。

pValueName [in]

指向以 null 结尾的字符串的指针，该字符串标识要设置的数据。

对于打印机，此字符串指定 pKeyName 键下的值的名称。

对于打印服务器，此字符串是以下备注部分中列出的预定义字符串之一。

键入 [in]

指示 pData 参数指向的数据类型的代码。 有关可能的类型代码的列表，请参阅 注册表值类型。

如果 pKeyName 指定预定义目录服务密钥之一， 则 Type 必须为 REG_SZ、 REG_MULTI_SZ、 REG_DWORD或 REG_BINARY。 如果使用 REG_BINARY ， 则 cbData 必须等于 1，并且目录服务会将数据视为布尔值。

pData [in]

指向包含打印机配置数据的缓冲区的指针。

cbData [in]

数组的大小（以字节为单位）。

返回值

如果函数成功，则返回值 ERROR_SUCCESS。

如果函数失败，则返回值为错误值。

备注

注意

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

若要检索打印机或打印后台处理程序的现有配置数据，请调用 GetPrinterDataEx 函数。

调用设置为“PrinterDriverData”的 pKeyName 参数设置为“PrinterDriverData”的 SetPrinterDataEx 等效于调用 SetPrinterData 函数。

如果 hPrinter 是打印服务器的句柄， pValueName 可以指定以下预定义值之一。

值 注释
SPLREG_ALLOW_USER_MANAGEFORMS 具有 Service Pack 2 的 Windows XP (SP2) 及更高版本
Windows Server 2003 Service Pack 1 (SP1) 及更高版本
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP Windows Server 2003 及更高版本中不支持
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS Windows 7 及更高版本
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE Windows 7 及更高版本
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE Windows 7 及更高版本
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT Windows 7 及更高版本
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY Windows 7 及更高版本
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY Windows 7 及更高版本
SPLREG_RETRY_POPUP 成功返回时，如果服务器设置为重试所有作业的弹出窗口， 则 pData 包含 1;如果服务器不重试所有作业的弹出窗口，则 pData 包含 0。
Windows Server 2003 及更高版本中不支持
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT Windows Server 2003 及更高版本

将以下预定义值之一作为 pValueName 传递将设置发生错误时的池打印行为。

值 注释
SPLREG_RESTART_JOB_ON_POOL_ERROR pData 的值指示发生错误后在另一个端口上重启作业的时间（以秒为单位）。 此设置与 SPLREG_RESTART_JOB_ON_POOL_ENABLED 一起使用。
SPLREG_RESTART_JOB_ON_POOL_ENABLED pData 中的非零值指示已启用SPLREG_RESTART_JOB_ON_POOL_ERROR。

SPLREG_RESTART_JOB_ON_POOL_ERROR中指定的时间是最短时间。 实际时间可能会更长，具体取决于以下端口监视器设置，这些设置是此注册表项下的注册表值：

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports

调用 RegSetValueEx 函数来设置这些值。

端口监视器设置 数据类型 含义
StatusUpdateEnabled REG_DWORD 如果为非零值，则允许端口监视器使用端口状态更新后台处理程序。
StatusUpdateInterval REG_DWORD 指定端口监视器使用端口状态更新后台处理程序时的间隔（以分钟为单位）。

若要确保后台处理程序将作业重定向到池中的下一个可用打印机， (打印作业未在设置的时间内打印) ，端口监视器必须支持 SNMP，并且池中的网络端口必须配置为“启用 SNMP 状态”。支持 SNMP 的端口监视器是标准 TCP/IP 端口监视器。

在 Windows 7 及更高版本的 Windows 中，发送到打印服务器的打印作业默认呈现在客户端上。 通过将 pKeyName 设置为“PrinterDriverData”，将 pValueName 设置为下表中的设置值，可以配置打印作业的客户端呈现。

设置 数据类型 说明
EMFDespoolingSetting REG_DWORD 如果值为 0，或者如果注册表中不存在此值，则启用打印作业的默认客户端呈现。
如果值为 1，则禁用打印作业的客户端呈现。
ForceClientSideRendering REG_DWORD 如果值为 0，或者如果注册表中不存在此值，将导致打印作业在客户端上呈现。 如果打印作业无法在客户端上呈现，则会在服务器上呈现。 如果打印作业无法在服务器上呈现，它将失败。
值为 1 将在客户端上呈现打印作业。 如果打印作业无法在客户端上呈现，它将失败。

要求

要求 值
最低受支持的客户端
 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器
 Windows 2000 Server [仅限桌面应用]
标头
Winspool.h (包括 Windows.h)
库
Winspool.lib
DLL
Winspool.drv
Unicode 和 ANSI 名称
 SetPrinterDataExW (Unicode) 和 SetPrinterDataExA (ANSI)

另请参阅

打印

打印后台处理程序 API 函数

GetPrinterDataEx

OpenPrinter

SetPrinter

PRINTER_INFO_7