SetPrinter 函式

SetPrinter函式會設定指定印表機的資料，或藉由暫停列印、繼續列印或清除所有列印工作來設定指定印表機的狀態。

語法

BOOL SetPrinter(
  _In_ HANDLE hPrinter,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter,
  _In_ DWORD  Command
);

參數

hPrinter [in]

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

層級 [in]

函式儲存至 pPrinter所指向之緩衝區的資料類型。 如果 Command 參數不等於零， Level 參數必須是零。

此值可以是 0、2、3、4、5、6、7、8 或 9。

pPrinter [in]

緩衝區的指標，其中包含要為印表機設定的資料，或包含 Command 參數所指定之命令的資訊。 緩衝區中的資料類型取決於 Level的值。

層級	結構
0	如果 Command 參數 PRINTER_CONTROL_SET_STATUS， pPrinter 必須包含 DWORD 值，指定要設定的新印表機狀態。 如需可能的狀態值清單，請參閱PRINTER_INFO_2結構的Status成員。 請注意， PRINTER_STATUS_PAUSED 和 PRINTER_STATUS_PENDING_DELETION 不是要設定的有效狀態值。 如果 Level 為 0，但 Command 參數未 PRINTER_CONTROL_SET_STATUS， 則 pPrinter 必須是 Null。
2	包含印表機詳細資訊 的PRINTER_INFO_2 結構。
3	包含印表機安全性資訊的 PRINTER_INFO_3 結構。
4	包含最少印表機資訊的 PRINTER_INFO_4 結構，包括印表機的名稱、伺服器的名稱，以及印表機是遠端還是本機。
5	包含印表機屬性和逾時設定等印表機資訊的 PRINTER_INFO_5 結構。
6	指定印表機狀態值的 PRINTER_INFO_6 結構。
7	PRINTER_INFO_7結構。 這個結構的 dwAction 成員指出 SetPrinter 是否應該發佈、取消發佈、重新發佈或更新目錄服務中的印表機資料。
8	指定全域預設印表機設定 的PRINTER_INFO_8 結構。
9	指定每個使用者預設印表機設定 的PRINTER_INFO_9 結構。

命令 [in]

要執行的動作。

如果 Level 參數為非零，請將此參數的值設定為零。 在此情況下，印表機會保留其目前狀態，而且函式會重新設定 Level 和 pPrinter 參數所指定的印表機資料。

如果 Level 參數為零，請將此參數的值設定為下列其中一個值。

值	意義
PRINTER_CONTROL_PAUSE	暫停印表機。
PRINTER_CONTROL_PURGE	刪除印表機中的所有列印工作。
PRINTER_CONTROL_RESUME	繼續暫停的印表機。
PRINTER_CONTROL_SET_STATUS	設定印表機狀態。 將 pPrinter 參數設定為指定新印表機狀態 之 DWORD 值的指標。

傳回值

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

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

如果 Level 為 7 且發佈動作失敗， SetPrinter 會傳回 ERROR_IO_PENDING ，並嘗試在背景中完成動作。 如果 Level 為 7 且更新動作失敗， SetPrinter 會傳回 ERROR_FILE_NOT_FOUND。

備註

注意

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

您無法使用 SetPrinter 來變更預設印表機。

若要修改目前的印表機設定，請呼叫 GetPrinter 函式，以將目前的設定擷取至 PRINTER_INFO_2 結構、視需要修改該結構的成員，然後呼叫 SetPrinter。

SetPrinter函式會忽略PRINTER_INFO_2結構的pServerName、AveragePPM、Status和cJobs成員。

暫停印表機會暫停該印表機的所有列印工作排程，但目前可能列印的列印工作除外。 列印工作可以提交至暫停的印表機，但不會排程在該印表機上列印，直到列印繼續為止。 如果清除印表機，則會刪除該印表機的所有列印工作，但目前列印工作除外。

如果您使用 SetPrinter 修改印表機的預設 DEVMODE 結構， (全域設定印表機預設值) ，您必須先呼叫 DocumentProperties 函式來驗證 DEVMODE 結構。

對於包含安全性描述元指標的 PRINTER_INFO_2 和 PRINTER_INFO_3 結構，函式只能設定呼叫端有權修改之安全性描述元的那些元件。 若要設定特定的安全性描述元元件，您必須在呼叫 OpenPrinter 或 OpenPrinter2 函式時指定必要的存取權限，才能擷取印表機的控制碼。 下表顯示修改各種安全性描述元元件所需的存取權限。

存取權限	安全性描述項元件
WRITE_OWNER	擁有者 主要群組
WRITE_DAC	DACL () 的任意存取控制清單
ACCESS_SYSTEM_SECURITY	SACL (系統存取控制清單)

如果安全性描述項包含呼叫端沒有修改存取權限的元件， SetPrinter 就會失敗。 您不想要修改之安全性描述元的那些元件應該為 Null 或不存在，視需要。 如果您不想修改安全性描述元，並且呼叫具有PRINTER_INFO_2結構的SetPrinter，請將該結構的pSecurityDescriptor成員設定為Null。

根據預設，網際網路連線防火牆 (ICF) 封鎖印表機埠，但可以啟用檔案和列印共用的例外狀況。 如果電腦系統管理員呼叫 SetPrinter ，則會啟用例外狀況。 如果由非系統管理員呼叫，且尚未啟用例外狀況，呼叫就會失敗。

您可以使用層級 7 搭配 PRINTER_INFO_7 結構來發佈、取消發佈或更新印表機的目錄服務資料。 印表機的目錄服務資料會透過呼叫印表機的 SetPrinterDataEx 函式，包含儲存在 SPLDS_* 索引鍵下的所有資料。 呼叫SetPrinter之前，請將PRINTER_INFO_7的pszObjectGUID成員設定為Null，並將dwAction成員設定為下列其中一個值。

值	描述
DSPRINT_PUBLISH	發佈目錄服務資料。
DSPRINT_REPUBLISH	印表機的目錄服務資料會取消發佈，然後再次發佈，重新整理已發行印表機中的所有屬性。 重新發佈也會變更已發行印表機的 GUID。 如果您懷疑印表機的已發佈資料已損毀，請使用此值。
DSPRINT_UNPUBLISH	取消發佈目錄服務資料。
DSPRINT_UPDATE	更新目錄服務資料。 這與 DSPRINT_PUBLISH相同，不同之處在于，如果印表機尚未發佈， SetPrinter 會失敗 並ERROR_FILE_NOT_FOUND 。 使用 DSPRINT_UPDATE 來更新已發佈的屬性，但不強制發佈。 印表機驅動程式應該一律使用 DSPRINT_UPDATE ，而不是 DSPRINT_PUBLISH。

DSPRINT_PENDING不是SetPrinter的有效dwAction值。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
標頭	WinSpool.h (包括 Windows.h)
程式庫	WinSpool.lib
DLL	WinSpool.drv
Unicode 與 ANSI 名稱	SetPrinterW (Unicode) 和 SetPrinterA (ANSI)

另請參閱

列印

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

AddPrinter

GetPrinter

OpenPrinter

OpenPrinter2

PRINTER_INFO_2

PRINTER_INFO_3

PRINTER_INFO_4

PRINTER_INFO_5

PRINTER_INFO_6

PRINTER_INFO_7

PRINTER_INFO_8

PRINTER_INFO_9

SetPrinterDataEx