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
發生下列列印工作變更時發出訊號的事件控制碼：
- 作業識別碼會指派給列印工作
- 頁面的列印已完成
- 檔列印已完成
- 列印工作已取消或因為錯誤而結束
XPS 列印 API 不會重設此事件，這是呼叫者的責任。
如果不需要進度通知，此參數可以設定為 Null。
[in] completionEvent
當列印工作完成時發出訊號的事件控制碼。 此事件保證在每個 StartXpsPrintJob 呼叫上都只發出一次訊號。 XPS 列印 API 不會重設此事件，這是呼叫者的責任。
如果不需要任何完成通知，則可以將此參數設定為 Null。
[in] printablePagesOn
參數會參考 UINT8 陣列，其元素會指定要列印之檔頁面的子集。 如下表所示，每個元素的值會指出是否要列印頁面。
| Array 元素值 | 意義 |
|---|---|
|
請勿列印頁面。 |
|
列印頁面。 |
進度事件只會針對指定列印的頁面發出訊號。
陣列中的元素代表 XPS 封裝之所有檔中指定列印的所有頁面。 例如，如果套件包含兩份檔，其中各有三頁，下表所示的陣列會指定從檔 1 列印第 0 頁和 2 頁，以及從檔 2 列印第 0 頁和第 2 頁。
| 元素索引 | 元素值 | 列印？ | 文件編號 | 頁碼 |
|---|---|---|---|---|
| 5 | 1 | Yes | 2 | 2 |
| 4 | 0 | 否 | 2 | 1 |
| 3 | 1 | Yes | 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 是非同步函式，可在列印多工緩衝處理器建立或啟動列印工作之前傳回。
在 xpsPrintJob、documentStream和printTicketStream中傳回的介面，必須等到StartXpsPrintJob成功傳回之後才使用。
呼叫端開始傳送資料之後，它應該監視傳送至 progressEvent中事件所發出訊號的進度事件。 當事件收到訊號時，呼叫端必須呼叫 IXpsPrintJob：：GetJobStatus 以取得列印工作的目前狀態。
當列印工作順利完成時，傳入 completedEvent 的事件會發出一次且只有一次的訊號。 為避免資料遺失，呼叫端應該監視此事件，而且在事件收到訊號之前，不應結束通話端的執行緒或應用程式。
作業狀態不會由列印多工緩衝處理器儲存或排入佇列。 由於工作處理不會等候在事件發出訊號之後讀取狀態，因此呼叫端可能會遺漏某些狀態變更，視應用程式收到變更通知的時間與稱為 IXpsPrintJob：：GetJobStatus的時間之間的延遲而定。 若要接收後續通知，應用程式必須在收到通知之後重設進度事件。
如果呼叫 StartXpsPrintJob 失敗，將會更新作業狀態、發出完成和進度事件的訊號，並傳回錯誤碼。 若要取得失敗列印工作的狀態，請呼叫 IXpsPrintJob：：GetJobStatus。
StartXpsPrintJob會在completionEvent和progressEvent上呼叫DuplicateHandle，以確保它們在作業的存留期內保持有效。 由於列印多工緩衝處理器會針對事件使用重複的控制碼，因此呼叫端可以在任何時間點關閉這些控制碼，而不會影響作業執行。 不過，建議的程式是讓呼叫端只有在 完成Event 事件收到訊號並被呼叫端觀察到之後，才關閉這些控制碼。
documentStream和printTicketStream中傳回的IXpsPrintJobStream介面是不允許搜尋但可以關閉的僅限寫入資料流程。 呼叫端會將 XPS 檔寫入這些資料流程並列印票證內容，然後在寫入所有資料之後呼叫 Close 。 呼叫資料流程的 Write 方法是安全線程;不過，如果這類呼叫是從不同的執行緒進行，則不保證會以預期的順序認可至資料流程。
規格需求
| 最低支援的用戶端 | Windows 7 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 R2 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | xpsprint.h |
| 程式庫 | XpsPrint.lib |
| Dll | XpsPrint.dll |