描述
开始将XPS文档流打印到打印机。
C++ 语法
HRESULT WINAPI StartXpsPrintJob( __in const LPCWSTR printerName, __in const LPCWSTR jobName, __in const LPCWSTR outputFileName, __in HANDLE progressEvent, __in HANDLE completionEvent, __in UINT8 *printablePagesOn, __in UINT32 printablePagesOnCount, __out IXpsPrintJob **xpsPrintJob, __out IXpsPrintJobStream **documentStream, __out IXpsPrintJobStream **printTicketStream ); |
PowerBASIC 语法
METHOD StartXpsPrintJob ( _ BYREF printerName AS WSTRINGZ, _ BYREF jobName AS WSTRINGZ, _ BYREF outputFileName AS WSTRINGZ, _ BYVAL progressEvent AS DWORD, _ BYVAL completionEvent AS DWORD, _ BYREF printablePagesOn AS BYTE, _ BYVAL printablePagesOnCount AS DWORD, _ BYREF xpsPrintJob AS IXpsPrintJob, _ BYREF documentStream AS IXpsPrintJobStream, _ BYREF printTicketStream AS IXpsPrintJobStream _ ) AS LONG |
参数
printerName
[in]与此作业关联的打印机的名称。
jobName
[in]与此作业关联的用户指定作业名称。如果作业不需要单独的用户指定的名称，则此参数可以设置为NULL。
outputFileName
[in]要将此作业的输出重定向到的文件或端口的文件名。设置此值将导致打印作业的输出被引导到指定的文件或端口。要将打印作业发送到PRINTERNAME指定的打印机，此参数必须设置为NULL。
progressEvent
[in]发生以下打印作业更改时发出信号的事件句柄：
| · | 作业ID已分配给打印作业 |
| · | 打印页面已经完成 |
| · | 打印文档已经完成 |
| · | 由于错误，打印作业已被取消或已经结束 |
注意在应用程序开始向打印作业发送数据之前，不会发出此事件。
The XPS Print API does not reset this event梩hat is the caller's responsibility.
如果不需要进度通知，则该参数可以设置为NULL。
printablePagesOn
[in]该参数引用一个UINT8数组，其元素指定要打印的文档页面的子集。如下表所示，每个元素的值表示是否打印页面。
数组元素值 |
含义 |
0 |
不要打印页面。 |
非零 |
打印页面。 |
进度事件只会被指定用于打印的页面。
在XPS包的所有文档中，数组中的元素表示指定用于打印的所有页面。例如，如果包含两个文档，每个文档有三个页面，则下表中列出的数组指定从文档1打印第0页和第2页，从文档2中打印第0页和第2页。
元素索引 |
元素值 |
打印？ |
文件号码 |
页码 |
5 |
1 |
是 |
2 |
2 |
4 |
0 |
No |
2 |
1 |
3 |
1 |
是 |
2 |
0 |
2 |
1 |
是 |
1 |
2 |
1 |
0 |
No |
1 |
1 |
0 |
1 |
是 |
1 |
0 |
如果printablePagesOn为NULL，则将打印包中的所有页面。
如果printablePagesOn具有比包中的页面更多的元素，则多余的元素将被忽略。
如果数组的元素少于文档中的页面，则数组的最后一个数组元素的值将应用于剩余的页面。该规则可以更容易地指定一个开放式的范围，也可以只打印几页大型文档。
printablePagesOnCount
[in]printablePagesOn引用的数组中的元素数。如果printablePagesOn为NULL，则忽略此参数。
xpsPrintJob
[out]指向IXpsPrintJob接口的指针，表示由StartXpsPrintJob创建的打印作业。要获取打印作业的状态或取消打印作业，请使用IXpsPrintJob界面。如果不需要IXpsPrintJob，则可以将此参数设置为NULL。
documentStream
[out]指向IXpsPrintJobStream接口的指针，调用者将XPS文档打印到该打印作业中。
printTicketStream
[out]指向IXpsPrintJobStream接口的指针，由调用者用来编写与此作业相关联的作业级打印机票。如果此参数设置为NULL，则将使用XPS文档中写入documentStream的打印票据（如果存在）。
返回值
该方法返回一个HRESULT。可能的值包括但不限于下表中的值。
退货代码 |
描述 |
S_OK |
该方法成功。 |
E_POINTER |
PRINTERNAME或documentStream为NULL。 |
E_OUTOFMEMORY |
没有足够的内存来创建一个新的IXpsPrintJob对象。 |
备注
StartXpsPrintJob是一个异步函数，可以在打印后台处理程序创建或启动打印作业之前返回。
xpsPrintJob，documentStream和printTicketStream中返回的接口在StartXpsPrintJob已成功返回之前不得使用。
呼叫者开始发送数据后，应监视通过progressEvent传递的事件发出的进度事件。当事件发出信号时，主叫方必须调用IXpsPrintJob.GetJobStatus以获取打印作业的当前状态。
无论打印作业是否成功完成，completionEvent中传递的事件将发出一次且仅一次。为防止数据丢失，呼叫者应监视此事件，线程或呼叫者的应用程序不应终止，直到事件发出信号。
作业状态既不由打印后台处理程序存储也不排队。因为作业处理不等待在事件发出信号后状态被读取，呼叫者可能会错过一些状态改变，这取决于应用程序接收到更改通知的时间与它所要求的时间之间的延迟（989796337）。要接收后续通知，应用程序必须在收到通知后重置进度事件。
如果调用StartXpsPrintJob失败，则作业状态将被更新，完成和进度事件将发出信号，并返回错误代码。要获取打印作业失败的状态，请调用IXpsPrintJob.GetJobStatus.
DuplicateHandleDuplicateHandle致电completionEvent和progressEvent，以确保在作业的整个生命周期内保持有效。因为打印后台处理程序正在使用事件的重复句柄，呼叫者可能会在任何时候关闭这些句柄，而不会影响作业的执行。但是，推荐的过程是仅在呼叫者发出completionEvent事件发出信号并观察到之后才能关闭这些句柄。
在documentStream和printTicketStream中返回的IXpsPrintJobStream接口是只读流，不允许寻找，但可以关闭。调用者将XPS文档和打印票据内容打印到这些流中，然后在写入所有数据之后调用“关闭”。对流的写入方法的调用是线程安全的;然而，如果这种呼叫是由不同的线程进行的，那么它们不能保证以预期的顺序提交给流。
注意 打印到文件时，应用程序负责提供用于打印到文件操作的outputFileName参数中传递的值。要打印到使用输出到FILE：端口的驱动程序的打印机，调用者必须通过显示公共文件对话框从用户检索文件名。
引用文件 #INCLUDE Once
XpsPrint.inc