startXpsPrintJob1 函数 (xpsprint.h)

  • 项目

[StartXpsPrintJob1 不受支持，将来可能会更改或不可用。 ]

创建用于将 XPS 文档内容发送到打印机的打印作业。此函数创建比 StartXpsPrintJob 更高效的打印路径。

语法

HRESULT StartXpsPrintJob1(
  [in]            LPCWSTR             printerName,
  [in, optional]  LPCWSTR             jobName,
  [in, optional]  LPCWSTR             outputFileName,
  [in, optional]  HANDLE              progressEvent,
  [in, optional]  HANDLE              completionEvent,
  [out, optional] IXpsPrintJob        **xpsPrintJob,
  [out]           IXpsOMPackageTarget **printContentReceiver
);

参数

[in] printerName

将与此作业关联的打印机的名称。

[in, optional] jobName

要与此作业关联的用户指定的作业名称。 如果作业不需要单独的用户指定名称，则可以将此参数设置为 NULL 。

[in, optional] outputFileName

要将此作业的输出重定向到的文件或端口的文件名。 设置此值将导致打印作业的输出定向到指定的文件或端口。 若要将打印作业发送到 printerName 指定的打印机，必须将此参数设置为 NULL。

[in, optional] progressEvent

以下打印作业发生更改之一时发出信号的事件句柄：

  • 作业 ID 分配给打印作业
  • 页面打印已完成
  • 文档打印已完成
  • 打印作业已取消或因错误而结束
注意 直到应用程序开始向打印作业发送数据后，才会发出此事件信号。
 

XPS 打印 API 不会重置此事件，这是调用方的责任。

如果不希望收到有关进度的通知，请将此参数设置为 NULL 。

[in, optional] completionEvent

在打印作业完成时发出信号的事件句柄。 保证每次 StartXpsPrintJob1 调用都向此事件发出一次信号。 XPS 打印 API 不会重置此事件，这是调用方的责任。

如果不希望收到有关完成的通知，请将此参数设置为 NULL 。

[out, optional] xpsPrintJob

指向 IXpsPrintJob 接口的指针，该接口表示 StartXpsPrintJob1 创建的打印作业。 若要获取打印作业的状态或取消打印作业，请使用 IXpsPrintJob 接口。 如果不需要此参数，请将此参数设置为 NULL 。

[out] printContentReceiver

指向此函数创建的 IXpsOMPackageTarget 接口的指针。 此参数是必需的，不能将其设置为 NULL。

若要将文档内容发送到此函数创建的打印作业，请使用通过调用 xpsOMPackageTarget 中返回的 IXpsOMPackageTarget 接口的 CreateXpsOMPackageWriter 方法创建的 IXpsOMPackageWriter 接口。

返回值

该方法返回 HRESULT。 可能的值包括（但并不限于）下表中的项。

返回代码 说明
S_OK
 方法成功。
E_POINTER
 printerName 或 xpsOMPackageTarget 为 NULL。
E_OUTOFMEMORY
 内存不足，无法创建新的 IXpsPrintJob 对象。

注解

StartXpsPrintJob1 是一个异步函数，因此它可以在打印后台处理程序创建或启动打印作业之前返回 。

在 StartXpsPrintJob1 成功返回之前，请勿使用 xpsPrintJob 和 xpsOMPackageTarget 中返回的接口。

调用方开始发送数据后，监视向 progressEvent 中传递的事件发出信号的进度事件是一种很好的编程做法。 发出事件信号时，调用方必须调用 IXpsPrintJob：：GetJobStatus 以获取打印作业的当前状态。

打印作业完成后，无论是否成功，在 completionEvent 中传递的事件只会发出一次信号。 为防止数据丢失，调用方监视完成事件并确保在发出完成事件信号之前，不会终止创建打印作业的线程和应用程序，这是一种良好的编程做法。

打印后台处理程序既不存储作业状态，也不排队。 由于作业处理不会在发出事件信号后等待读取状态，因此调用方可能会错过某些状态更改，具体取决于应用程序收到更改通知的时间与调用 IXpsPrintJob：：GetJobStatus 之间的延迟。 若要接收后续通知，应用程序必须在收到通知后重置进度事件。

如果调用 StartXpsPrintJob1 失败，打印后台处理程序将更新作业状态，发出完成和进度事件信号，并返回错误代码。 若要获取失败打印作业的状态，请调用 IXpsPrintJob：：GetJobStatus。

StartXpsPrintJob1 在 completionEvent 和 progressEvent 上调用 DuplicateHandle，以确保它们在作业的生存期内保持有效。 由于打印后台处理程序对事件使用重复句柄，因此调用方可以随时关闭这些句柄，而不会影响作业执行。 但是，我们建议调用方仅在 向 completionEvent 事件发出信号并且调用方观察到该事件后才关闭这些句柄。

注意 当应用程序打印到文件时，应用程序负责提供值以传入 outputFileName 参数以执行打印到文件操作。 若要打印到使用输出到 FILE： 端口的驱动程序的打印机，调用方必须通过显示通用文件对话框从用户检索文件名。
 

要求

要求 值
最低受支持的客户端 Windows 7 SP1、Windows Vista 和适用于 Windows Vista 的平台更新补充 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 SP1、Windows Server 2008 和适用于 Windows Server 2008 的平台更新补充 [仅限桌面应用]
目标平台 Windows
标头 xpsprint.h
Library XpsPrint.lib
DLL XpsPrint.dll

请参阅

文档

IXpsOMPackageTarget

IXpsOMPackageWriter

XML 纸张规范