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 元素值 | 含义 |
|---|---|
|
不要打印页面。 |
|
打印页面。 |
仅针对指定打印的页面发出进度事件信号。
数组中的元素表示 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。 可能的值包括（但并不限于）下表中的项。
| 返回代码 | 说明 |
|---|---|
|
方法成功。 |
|
printerName 或 documentStream 为 NULL。 |
|
内存不足，无法创建新的 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 方法的调用是线程安全的;但是，如果此类调用是从不同的线程进行的，则不能保证它们按预期顺序提交到流。
要求
| 最低受支持的客户端 | Windows 7 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 R2 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | xpsprint.h |
| Library | XpsPrint.lib |
| DLL | XpsPrint.dll |
请参阅
文档