SetPrinter 函数

  • 项目

SetPrinter 函数设置指定打印机的数据，或通过暂停打印、恢复打印或清除所有打印作业来设置指定打印机的状态。

语法

BOOL SetPrinter(
  _In_ HANDLE hPrinter,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter,
  _In_ DWORD  Command
);

参数

hPrinter [in]

打印机的句柄。 使用 OpenPrinter、 OpenPrinter2 或 AddPrinter 函数检索打印机句柄。

级别 [in]

函数存储在 pPrinter 指向的缓冲区中的数据类型。 如果 Command 参数不等于零， 则 Level 参数必须为零。

此值可以是 0、2、3、4、5、6、7、8 或 9。

pPrinter [in]

指向缓冲区的指针，该缓冲区包含要为打印机设置的数据，或包含 Command 参数指定的命令的信息。 缓冲区中的数据类型由 Level 值决定。

级别 结构
0
 如果 Command 参数 PRINTER_CONTROL_SET_STATUS， pPrinter 必须包含 一个 DWORD 值，该值指定要设置的新打印机状态。 有关可能的状态值的列表，请参阅PRINTER_INFO_2结构的 Status 成员。 请注意， PRINTER_STATUS_PAUSED 和 PRINTER_STATUS_PENDING_DELETION 不是要设置的有效状态值。
如果 Level 为 0，但 Command 参数未 PRINTER_CONTROL_SET_STATUS， 则 pPrinter 必须为 NULL。
2
 包含打印机详细信息 的PRINTER_INFO_2 结构。
3
 包含打印机安全信息的 PRINTER_INFO_3 结构。
4
 包含最少打印机信息（包括打印机名称、服务器名称以及打印机是远程还是本地）的 PRINTER_INFO_4 结构。
5
 包含打印机信息（如打印机属性和超时设置） 的PRINTER_INFO_5 结构。
6
 指定打印机状态值的 PRINTER_INFO_6 结构。
7
 PRINTER_INFO_7结构。 此结构的 dwAction 成员指示 SetPrinter 是应在目录服务中发布、取消发布、重新发布还是更新打印机的数据。
8
 指定全局默认打印机设置 的PRINTER_INFO_8 结构。
9
 指定每用户默认打印机设置 的PRINTER_INFO_9 结构。

命令 [in]

要执行的操作。

如果 Level 参数为非零，请将此参数的值设置为零。 在这种情况下，打印机将保留其当前状态，函数会根据 Level 和 pPrinter 参数指定重新配置打印机数据。

如果 Level 参数为零，请将此参数的值设置为以下值之一。

值 含义
PRINTER_CONTROL_PAUSE
 暂停打印机。
PRINTER_CONTROL_PURGE
 删除打印机中的所有打印作业。
PRINTER_CONTROL_RESUME
 恢复暂停的打印机。
PRINTER_CONTROL_SET_STATUS
 设置打印机状态。
将 pPrinter 参数设置为指向指定新打印机状态的 DWORD 值的指针。

返回值

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

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

如果 Level 为 7 且发布操作失败， SetPrinter 将返回 ERROR_IO_PENDING 并尝试在后台完成该操作。 如果 Level 为 7 且更新操作失败， SetPrinter 将返回 ERROR_FILE_NOT_FOUND。

备注

注意

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

不能使用 SetPrinter 更改默认打印机。

若要修改当前打印机设置，请调用 GetPrinter 函数以将当前设置检索到 PRINTER_INFO_2 结构中，根据需要修改该结构的成员，然后调用 SetPrinter。

SetPrinter 函数忽略PRINTER_INFO_2结构的 pServerName、AveragePPM、Status 和 cJobs 成员。

暂停打印机会暂停该打印机的所有打印作业的计划，当前可能打印的一个打印作业除外。 打印作业可以提交到暂停的打印机，但在打印恢复之前，不会安排任何作业在该打印机上打印。 如果清除打印机，则删除该打印机的所有打印作业，当前打印作业除外。

如果使用 SetPrinter 修改打印机的默认 DEVMODE 结构， (全局设置打印机默认值) ，则必须首先调用 DocumentProperties 函数来验证 DEVMODE 结构。

对于包含指向安全描述符的指针的 PRINTER_INFO_2 和 PRINTER_INFO_3 结构，函数只能设置调用方有权修改的安全描述符的那些组件。 若要设置特定的安全描述符组件，在调用 OpenPrinter 或 OpenPrinter2 函数以检索打印机句柄时，必须指定必要的访问权限。 下表显示了修改各种安全描述符组件所需的访问权限。

访问权限 安全描述符组件
WRITE_OWNER 所有者
主要组
WRITE_DAC DACL) (任意访问控制列表
ACCESS_SYSTEM_SECURITY SACL) (系统访问控制列表

如果安全描述符包含调用方没有访问权限修改的组件， SetPrinter 将失败。 你不想修改的安全描述符的那些组件应为 NULL 或不存在（视情况而定）。 如果不想修改安全描述符，并且使用PRINTER_INFO_2结构调用 SetPrinter，请将该结构的 pSecurityDescriptor 成员设置为 NULL。

Internet 连接防火墙 (ICF) 默认阻止打印机端口，但可以启用文件和打印共享的例外。 如果计算机管理员调用 SetPrinter ，则会启用异常。 如果它由非管理员调用，但尚未启用异常，则调用将失败。

可以将级别 7 与 PRINTER_INFO_7 结构配合使用，以发布、取消发布或更新打印机的目录服务数据。 打印机的目录服务数据包括通过调用打印机的 SetPrinterDataEx 函数存储在 SPLDS_* 键下的所有数据。 在调用 SetPrinter 之前，请将 PRINTER_INFO_7 的 pszObjectGUID 成员设置为 NULL，并将 dwAction 成员设置为以下值之一。

值 说明
DSPRINT_PUBLISH
 发布目录服务数据。
DSPRINT_REPUBLISH
 打印机的目录服务数据将取消发布，然后再次发布，刷新已发布打印机中的所有属性。 重新发布还会更改已发布打印机的 GUID。 如果怀疑打印机的已发布数据已损坏，请使用此值。
DSPRINT_UNPUBLISH
 取消发布目录服务数据。
DSPRINT_UPDATE
 汇报目录服务数据。 这与 DSPRINT_PUBLISH相同，不同之处在于，如果尚未发布打印机， SetPrinter 会因 ERROR_FILE_NOT_FOUND 失败。
使用 DSPRINT_UPDATE 更新已发布的属性，但不强制发布。 打印机驱动程序应始终使用 DSPRINT_UPDATE 而不是 DSPRINT_PUBLISH。

DSPRINT_PENDING不是 SetPrinter 的有效 dwAction 值。

要求

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

另请参阅

打印

打印后台处理程序 API 函数

AddPrinter

GetPrinter

OpenPrinter

OpenPrinter2

PRINTER_INFO_2

PRINTER_INFO_3

PRINTER_INFO_4

PRINTER_INFO_5

PRINTER_INFO_6

PRINTER_INFO_7

PRINTER_INFO_8

PRINTER_INFO_9

SetPrinterDataEx