共用方式為

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。 可能的值包括 (但不限於) 下表中的這些值。

傳回碼 描述
S_OK
 此方法已成功。
E_POINTER
 printerName 或 xpsOMPackageTarget 為 NULL。
E_OUTOFMEMORY
 記憶體不足，無法建立新的 IXpsPrintJob 物件。

備註

StartXpsPrintJob1 是異步函式，因此可以在列印後台處理程式建立或啟動列印作業之前傳回。

請勿使用 xpsPrintJob 和 xpsOMPackageTarget 中傳回的介面，直到 StartXpsPrintJob1 成功傳回為止。

呼叫端開始傳送數據之後，最好進行程式設計做法，監視傳送至進行中事件訊號的 進度事件。 當事件發出訊號時，呼叫端必須呼叫 IXpsPrintJob：：GetJobStatus 以取得列印作業的目前狀態。

當列印作業完成時，不論是否成功，在 completionEvent 中傳遞的事件只會發出一次訊號。 為了防止數據遺失，呼叫端監視完成事件是很好的程式設計做法，並確保線程和建立列印作業的應用程式都不會終止，直到完成事件收到訊號為止。

作業狀態不會由列印後台處理程式儲存或排入佇列。 由於作業處理不會等候在事件發出訊號之後讀取狀態，因此呼叫端可能會遺漏某些狀態變更，視應用程式收到變更通知的時間與稱為 IXpsPrintJob：：GetJobStatus 的時間之間的延遲而定。 若要接收後續通知，應用程式必須在收到通知之後重設進度事件。

如果呼叫 StartXpsPrintJob1 失敗，列印後台處理程式會更新作業狀態、發出完成和進度事件的訊號，並傳回錯誤碼。 若要取得失敗列印作業的狀態，請呼叫 IXpsPrintJob：：GetJobStatus。

StartXpsPrintJob1 會在 completionEvent 和 progressEvent 上呼叫 DuplicateHandle，以確保它們對作業的存留期保持有效。 由於列印多任務緩衝處理器會針對事件使用重複的句柄，因此呼叫端可以在任何時間點關閉這些句柄，而不會影響作業執行。 不過，我們建議呼叫端只有在 completedEvent 事件收到訊號且呼叫端觀察到它之後，才關閉這些句柄。

注意 當您的應用程式列印到檔案時，應用程式會負責提供值，以傳入 outputFileName 參數以進行列印到檔案作業。 若要列印至使用輸出至 FILE： 埠之驅動程式的印表機，呼叫端必須藉由顯示通用檔案對話框，從使用者擷取檔名。
 

規格需求

需求 值
最低支援的用戶端 適用於 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

另請參閱

文件

IXpsOMPackageTarget

IXpsOMPackageWriter

XML Paper Specification