startXpsPrintJob 函数 (xpsprint.h)

  • 项目

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

开始将 XPS 文档流打印到打印机。

语法

HRESULT StartXpsPrintJob(
  [in]  LPCWSTR            printerName,
  [in]  LPCWSTR            jobName,
  [in]  LPCWSTR            outputFileName,
  [in]  HANDLE             progressEvent,
  [in]  HANDLE             completionEvent,
  [in]  UINT8              *printablePagesOn,
  [in]  UINT32             printablePagesOnCount,
  [out] IXpsPrintJob       **xpsPrintJob,
  [out] IXpsPrintJobStream **documentStream,
  [out] IXpsPrintJobStream **printTicketStream
);

参数

[in] printerName

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

[in] jobName

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

[in] outputFileName

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

[in] progressEvent

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

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

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

如果不需要进度通知，则可以将此参数设置为 NULL。

[in] completionEvent

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

如果不需要完成通知，则可以将此参数设置为 NULL。

[in] printablePagesOn

参数引用一个 UINT8 数组，该数组的元素指定要打印的文档页面的子集。 如下表所示，每个元素的值指示是否打印页面。

Array 元素值 含义
0
 不要打印页面。
非零值
 打印页面。
 

仅针对指定打印的页面发出进度事件信号。

数组中的元素表示 XPS 包的所有文档中指定用于打印的所有页面。 例如，如果包包含两个文档，每个文档各有三页，则下表中显示的数组指定从文档 1 打印第 0 页和第 2 页，以及从文档 2 打印页 0 页和第 2 页。

元素索引 元素值 打印？ 文档编号 页码
5 1 是 2 2
4 0 否 2 1
3 1 是 2 0
2 1 是 1 2
1 0 否 1 1
0 1 是 1 0
 

如果 printablePagesOn 为 NULL，则将打印包中的所有页面。

如果 printablePagesOn 的元素比包中的页面多，将忽略多余的元素。

如果数组的元素少于文档中的页面数，则数组的最后一个数组元素的值将应用于其余页面。 通过此规则，可以更轻松地指定一个开放式或只打印一个大型文档的几页的区域。

[in] printablePagesOnCount

由 printablePagesOn 引用的数组中的元素数。 如果 printablePagesOn 为 NULL，则忽略此参数。

[out] xpsPrintJob

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

[out] documentStream

指向 IXpsPrintJobStream 接口的指针，调用方在该接口中写入要由此打印作业打印的 XPS 文档。

[out] printTicketStream

指向 IXpsPrintJobStream 接口的指针，调用方使用该接口写入将与此作业关联的作业级打印票证。 如果此参数设置为 NULL，则打印票证 (如果有任何) 来自写入 documentStream 的 XPS 文档。

返回值

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

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

注解

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

在成功返回 StartXpsPrintJob 之前，不得使用 xpsPrintJob、documentStream 和 printTicketStream 中返回的接口。

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

打印作业完成后，无论是否成功，在 completionEvent 中传递的事件都将收到一次且仅一次的信号。 为防止数据丢失，调用方应监视此事件，在发出事件信号之前，不应终止调用方线程或应用程序。

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

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

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

documentStream 和 printTicketStream 中返回的 IXpsPrintJobStream 接口是不允许查找但可以关闭的只写流。 调用方将 XPS 文档和票证内容打印到这些流中，然后在写入所有数据后调用 Close 。 对流的 Write 方法的调用是线程安全的;但是，如果此类调用是从不同的线程进行的，则不能保证它们按预期顺序提交到流。

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

要求

   
最低受支持的客户端 Windows 7 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 [仅限桌面应用]
目标平台 Windows
标头 xpsprint.h
Library XpsPrint.lib
DLL XpsPrint.dll

请参阅

文档

StartXpsPrintJob1

XML 纸张规范