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 [僅限傳統型應用程式] |
| 標頭 |
|
| 程式庫 |
|
| DLL |
|
| Unicode 與 ANSI 名稱 |
SetPrinterW (Unicode) 和 SetPrinterA (ANSI) |