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
發生下列其中一個列印作業變更時發出訊號的事件句柄：
- 作業標識碼會指派給列印作業
- 頁面的列印已完成
- 檔列印完成
- 列印作業已取消或因為錯誤而結束
XPS 列印 API 不會重設此事件，也就是呼叫者的責任。
如果您不想收到進度的通知，請將此參數設定為 NULL 。
[in, optional] completionEvent
當列印作業完成時發出訊號的事件句柄。 此事件保證每個 StartXpsPrintJob1 呼叫只發出一次訊號。 XPS 列印 API 不會重設此事件，也就是呼叫者的責任。
如果不想收到完成的通知，請將此參數設定為 NULL 。
[out, optional] xpsPrintJob
IXpsPrintJob 介面的指標，代表 StartXpsPrintJob1 建立的列印作業。 若要取得列印作業的狀態或取消它，請使用 IXpsPrintJob 介面。 如果您不需要此參數，請將此參數設定為 NULL 。
[out] printContentReceiver
這個函式所建立 之 IXpsOMPackageTarget 介面的指標。 這是必要參數，您無法將其設定為 NULL。
若要將文件內容傳送至此函式所建立的列印作業，請使用您建立的IXpsOMPackageWriter 介面，方法是呼叫 xpsOMPackageTarget 中傳回之 IXpsOMPackageTarget 介面的 CreateXpsOMPackageWriter 方法。
傳回值
方法會傳回 HRESULT。 可能的值包括 (但不限於) 下表中的這些值。
| 傳回碼 | 描述 |
|---|---|
|
此方法已成功。 |
|
printerName 或 xpsOMPackageTarget 為 NULL。 |
|
記憶體不足，無法建立新的 IXpsPrintJob 物件。 |
備註
StartXpsPrintJob1 是異步函式，因此可以在列印後台處理程式建立或啟動列印作業之前傳回。
請勿使用 xpsPrintJob 和 xpsOMPackageTarget 中傳回的介面，直到 StartXpsPrintJob1 成功傳回為止。
呼叫端開始傳送數據之後，最好進行程式設計做法，監視傳送至進行中事件訊號的 進度事件。 當事件發出訊號時，呼叫端必須呼叫 IXpsPrintJob：：GetJobStatus 以取得列印作業的目前狀態。
當列印作業完成時，不論是否成功，在 completionEvent 中傳遞的事件只會發出一次訊號。 為了防止數據遺失，呼叫端監視完成事件是很好的程式設計做法，並確保線程和建立列印作業的應用程式都不會終止，直到完成事件收到訊號為止。
作業狀態不會由列印後台處理程式儲存或排入佇列。 由於作業處理不會等候在事件發出訊號之後讀取狀態，因此呼叫端可能會遺漏某些狀態變更，視應用程式收到變更通知的時間與稱為 IXpsPrintJob：：GetJobStatus 的時間之間的延遲而定。 若要接收後續通知，應用程式必須在收到通知之後重設進度事件。
如果呼叫 StartXpsPrintJob1 失敗，列印後台處理程式會更新作業狀態、發出完成和進度事件的訊號，並傳回錯誤碼。 若要取得失敗列印作業的狀態，請呼叫 IXpsPrintJob：：GetJobStatus。
StartXpsPrintJob1 會在 completionEvent 和 progressEvent 上呼叫 DuplicateHandle，以確保它們對作業的存留期保持有效。 由於列印多任務緩衝處理器會針對事件使用重複的句柄，因此呼叫端可以在任何時間點關閉這些句柄，而不會影響作業執行。 不過，我們建議呼叫端只有在 completedEvent 事件收到訊號且呼叫端觀察到它之後，才關閉這些句柄。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 適用於 Windows Vista 的 Windows 7 SP1、Windows Vista 和平臺更新補充 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 R2 SP1、Windows Server 2008 和適用於 Windows Server 2008 的平臺更新補充 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | xpsprint.h |
| 程式庫 | XpsPrint.lib |
| Dll | XpsPrint.dll |