SetJob 函数

SetJob 函数暂停、恢复、取消或重新启动指定打印机上的打印作业。 还可以使用 SetJob 函数设置打印作业参数,例如打印作业优先级和文档名称。

可以使用 SetJob 函数向打印作业提供命令,或设置打印作业参数,或在同一调用中同时执行这两项操作。 Command 参数的值不会影响函数使用 LevelpJob 参数的方式。 此外,还可以将 SetJobJOB_INFO_3 结合使用,将一组打印作业链接在一起。 有关更多信息,请参见备注。

语法

BOOL SetJob(
  _In_ HANDLE hPrinter,
  _In_ DWORD  JobId,
  _In_ DWORD  Level,
  _In_ LPBYTE pJob,
  _In_ DWORD  Command
);

参数

hPrinter [in]

感兴趣的打印机对象的句柄。 使用 OpenPrinterOpenPrinter2AddPrinter 函数检索打印机句柄。

JobId [in]

指定打印作业的标识符。 通过调用 AddJob 函数或 StartDoc 函数获取打印作业标识符。

如果 Level 参数设置为 3,则 JobId 参数必须与 pJob 指向的 JOB_INFO_3 结构的 JobId 成员匹配

级别 [in]

pJob 参数指向的作业信息结构的类型。

所有版本的 Windows:可以将 Level 参数设置为 0、1 或 2。 将 Level 设置为 0 时, pJob 应为 NULL。 如果未设置任何打印作业参数,请使用这些值。

还可以将 Level 参数设置为 3。

Windows Vista 开始:还可以将 Level 参数设置为 4。

pJob [in]

指向设置打印作业参数的 结构的指针。

所有版本的 WindowspJob 可以指向 JOB_INFO_1JOB_INFO_2 结构。

pJob 还可以指向 JOB_INFO_3 结构。 您必须对 JOB_INFO_3 结构的 JobIdNextJobId 成员指定的作业具有 JOB_ACCESS_ADMINISTER 访问权限。

Windows Vista 开始: pJob 也可以指向 JOB_INFO_4 结构。

如果 Level 参数为 0, 则 pJob 应为 NULL

命令 [in]

要执行的打印作业操作。 此参数的取值可为下列值之一:

含义
JOB_CONTROL_CANCEL
请勿使用。 若要删除打印作业,请使用 JOB_CONTROL_DELETE
JOB_CONTROL_PAUSE
暂停打印作业。
JOB_CONTROL_RESTART
重启打印作业。 只有在打印作业时才能重启作业。
JOB_CONTROL_RESUME
恢复暂停的打印作业。
JOB_CONTROL_DELETE
删除打印作业。
JOB_CONTROL_SENT_TO_PRINTER
由端口监视器用于结束打印作业。
JOB_CONTROL_LAST_PAGE_EJECTED
由语言监视器用于结束打印作业。
JOB_CONTROL_RETAIN
Windows Vista 及更高版本:打印后将作业保留在队列中。
JOB_CONTROL_RELEASE
Windows Vista 及更高版本:释放打印作业。

可以使用对 SetJob 函数的相同调用来设置打印作业参数,并为打印作业提供命令。 因此,如果要设置打印作业参数, 则 Command 不需要为 0,尽管它可以是。

返回值

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

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

注解

注意

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

可以使用 SetJob 函数设置各种打印作业参数,方法是提供指向包含必要数据的 JOB_INFO_1JOB_INFO_2JOB_INFO_3JOB_INFO_4 结构的指针。

若要删除特定打印机的所有打印作业,请调用 SetPrinter 函数,其 Command 参数设置为 PRINTER_CONTROL_PURGE

调用 SetJob 时,将忽略 JOB_INFO_1JOB_INFO_2JOB_INFO_4 结构的以下成员:JobIdpPrinterNamepMachineNamepUserNamepDrivernameSizeSubmittedTimeTotalPages

必须具有 打印机PRINTER_ACCESS_ADMINISTER 访问权限才能更改打印作业在打印队列中的位置。

如果不想设置打印作业在打印队列中的位置,则应将JOB_INFO_1JOB_INFO_2JOB_INFO_4结构的 Position 成员设置为JOB_POSITION_UNSPECIFIED

SetJob 函数与 JOB_INFO_3 结构结合使用,将一组打印作业 (也称为链) 链接在一起。 当单个文档包含要单独呈现的多个部分时,这非常有用。 若要按顺序打印作业 A、B、C 和 D,请使用 JOB_INFO_4调用 SetJob 以将 A 链接到 B、B 到 C 以及将 C 链接到 D。

如果链接打印作业,请注意以下事项:

  • 作业可以添加到链的开头或结尾。

  • 链中的所有作业都必须具有相同的数据类型。

  • 在后台打印开始之前,链必须完全链接,否则后台处理程序可能会在链接所有后台处理程序作业之前打印和删除这些作业。 可通过两种方法防止链条过早打印:

    • 暂停链中的第一个作业,直到链完全链接。 第一个作业的暂停状态控制链中所有作业的状态。
    • 保持第一个作业不完整,即不要为第一个作业调用 EndDocScheduleJob 。 但是,如果“后台打印时打印” (默认) 启用,则此方法会在生成链时阻止端口,这也会阻止打印不相关的作业。
  • 应用程序必须处理用户在链完成打印之前删除链中的作业的情况。 当 JobID 不存在时,GetLastError 返回INVALID_PARAMETER

要求

要求
最低受支持的客户端
Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器
Windows 2000 Server [仅限桌面应用]
标头
WinSpool.h (包括 Windows.h)

WinSpool.lib
DLL
WinSpool.drv
Unicode 和 ANSI 名称
SetJobW (Unicode) 和 SetJobA (ANSI)

另请参阅

打印

打印后台处理程序 API 函数

AddJob

GetJob

OpenPrinter

SetPrinter

JOB_INFO_1

JOB_INFO_2

JOB_INFO_3

JOB_INFO_4