共用方式為


SetPrinter 函式

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

語法

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

參數

hPrinter [in]

印表機的控制碼。 使用 OpenPrinterOpenPrinter2AddPrinter 函式來擷取印表機控制碼。

層級 [in]

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

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

pPrinter [in]

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

層級 結構
0
如果 Command 參數 PRINTER_CONTROL_SET_STATUSpPrinter 必須包含 DWORD 值,指定要設定的新印表機狀態。 如需可能的狀態值清單,請參閱PRINTER_INFO_2結構的Status成員。 請注意, PRINTER_STATUS_PAUSEDPRINTER_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 參數為非零,請將此參數的值設定為零。 在此情況下,印表機會保留其目前狀態,而且函式會重新設定 LevelpPrinter 參數所指定的印表機資料。

如果 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結構的pServerNameAveragePPMStatuscJobs成員。

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

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

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

存取權限 安全性描述項元件
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_7pszObjectGUID成員設定為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