SetJob 函式

  • 發行項

SetJob函式會在指定的印表機上暫停、繼續、取消或重新開機列印工作。 您也可以使用 SetJob 函式來設定列印工作參數，例如列印工作優先順序和檔案名稱。

您可以使用 SetJob 函式來提供命令給列印工作，或設定列印工作參數，或在相同的呼叫中執行兩者。 Command參數的值不會影響函式如何使用Level和pJob參數。 此外，您可以使用 SetJob 搭配 JOB_INFO_3 ，將一組列印工作連結在一起。 如需詳細資訊，請參閱「備註」。

語法

BOOL SetJob(
  _In_ HANDLE hPrinter,
  _In_ DWORD  JobId,
  _In_ DWORD  Level,
  _In_ LPBYTE pJob,
  _In_ DWORD  Command
);

參數

hPrinter [in]

感興趣的印表機物件的控制碼。 使用OpenPrinter、OpenPrinter2或AddPrinter函式來擷取印表機控制碼。

JobId [in]

指定列印工作的識別碼。 您可以藉由呼叫 AddJob 函式或 StartDoc 函式來取得列印工作識別碼。

如果Level參數設定為 3，JobId參數必須符合pJob所指向之JOB_INFO_3結構的JobId成員

層級 [in]

pJob參數所指向的作業資訊結構類型。

所有版本的 Windows：您可以將 Level 參數設定為 0、1 或 2。 當您將 Level 設定為 0 時， pJob 應該是 Null。 當您未設定任何列印工作參數時，請使用這些值。

您也可以將 Level 參數設定為 3。

從 Windows Vista開始：您也可以將 Level 參數設定為 4。

pJob [in]

設定列印工作參數之結構的指標。

所有版本的 Windows： pJob 可以指向 JOB_INFO_1 或 JOB_INFO_2 結構。

pJob 也可以指向 JOB_INFO_3 結構。 您必須擁有JOB_ACCESS_ADMINISTERJOB_INFO_3結構之 JobId和NextJobId成員所指定的作業存取權限。

從 Windows Vista開始： pJob 也可以指向 JOB_INFO_4 結構。

如果 Level 參數為 0， pJob 應該是 Null。

命令 [in]

要執行的列印工作作業。 此參數可以是下列其中一個值。

值 意義
JOB_CONTROL_CANCEL
 請勿使用。 若要刪除列印工作，請使用 JOB_CONTROL_DELETE。
JOB_CONTROL_PAUSE
 暫停列印工作。
JOB_CONTROL_RESTART
 重新開機列印工作。 只有在正在列印時，才能重新開機作業。
JOB_CONTROL_RESUME
 繼續暫停的列印工作。
JOB_CONTROL_DELETE
 刪除列印工作。
JOB_CONTROL_SENT_TO_PRINTER
 由埠監視器用來結束列印工作。
JOB_CONTROL_LAST_PAGE_EJECTED
 由語言監視器用來結束列印工作。
JOB_CONTROL_RETAIN
 Windows Vista 和更新版本：在工作列印之後，將作業保留在佇列中。
JOB_CONTROL_RELEASE
 Windows Vista 和更新版本：釋放列印工作。

您可以使用 SetJob 函式的相同呼叫來設定列印工作參數，並提供命令給列印工作。 因此，如果您要設定列印工作參數， 則命令 不需要是 0，雖然它可以。

傳回值

如果函式成功，則傳回值是非零值。

如果此函式失敗，則傳回值為零。

備註

注意

這是封鎖或同步函式，可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器設定，以及撰寫應用程式時難以預測的印表機驅動程式實作因素。 從管理與使用者介面互動的執行緒呼叫此函式，可能會使應用程式看起來沒有回應。

您可以使用 SetJob 函式來設定各種列印工作參數，方法是提供包含必要資料的 JOB_INFO_1、 JOB_INFO_2、 JOB_INFO_3或 JOB_INFO_4 結構指標。

若要移除或刪除特定印表機的所有列印工作，請呼叫 SetPrinter 函式，並將其 Command 參數設定為 PRINTER_CONTROL_PURGE。

呼叫SetJob時會忽略下列JOB_INFO_1、JOB_INFO_2或JOB_INFO_4結構的成員：JobId、pPrinterName、pMachineName、pUserName、pDrivername、Size、Submitted、Time和TotalPages。

您必須擁有 印表機的PRINTER_ACCESS_ADMINISTER 存取權限，才能變更列印佇列中的列印工作位置。

如果您不想在列印佇列中設定列印工作的位置，您應該將JOB_INFO_1、JOB_INFO_2或JOB_INFO_4結構的Position成員設定為JOB_POSITION_UNSPECIFIED。

使用 SetJob 函式搭配 JOB_INFO_3 結構，將一組列印工作連結在一起， (也稱為鏈結) 。 在單一檔是由您想要個別轉譯的數個部分所組成的情況下，這非常有用。 若要依序列印工作 A、B、C 和 D，請使用JOB_INFO_4呼叫SetJob，將 A 連結至 B、B 至 C 和 C 至 D。

如果您連結列印工作，請注意下列事項：

  • 作業可以新增至鏈結的開頭或結尾。

  • 鏈結中的所有作業都必須具有相同的資料類型。

  • 鏈結必須在多工緩衝處理開始之前完全連結，否則多工緩衝處理常式可以在連結所有作業之前先列印和刪除多工緩衝處理工作。 有兩種方式可讓鏈結提前列印：

    • 暫停鏈結中的第一個作業，直到鏈結完全連結為止。 第一個作業的暫停狀態會控管鏈結中所有作業的狀態。
    • 保留第一個作業不完整，也就是說，請勿針對第一個作業呼叫 EndDoc 或 ScheduleJob 。 不過，如果啟用「多工緩衝處理時列印」 (預設) ，此方法會在建置鏈結時封鎖埠，這也會防止列印非相關的作業。

  • 應用程式必須在鏈結完成列印之前，處理使用者刪除鏈結中作業的情況。 當 JobID 不存在時，GetLastError會傳回INVALID_PARAMETER。

規格需求

需求 值
最低支援的用戶端
 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器
 Windows 2000 Server [僅限桌面應用程式]
標頭
WinSpool.h (包含 Windows.h)
程式庫
WinSpool.lib
DLL
WinSpool.drv
Unicode 與 ANSI 名稱
 SetJobW (Unicode) 和 SetJobA (ANSI)

另請參閱

列印

列印多工緩衝處理器 API 函式

AddJob

GetJob

OpenPrinter

SetPrinter

JOB_INFO_1

JOB_INFO_2

JOB_INFO_3

JOB_INFO_4