SetPrinterData 函式

SetPrinterData函式會設定印表機或列印伺服器的組態資料。

若要指定要儲存資料的登錄機碼，請呼叫 SetPrinterDataEx 函式。 呼叫 SetPrinterData 相當於呼叫 SetPrinterDataEx 函式，並將 pKeyName 參數設定為 「PrinterDriverData」。

語法

DWORD SetPrinterData(
  _In_ HANDLE hPrinter,
  _In_ LPTSTR pValueName,
  _In_ DWORD  Type,
  _In_ LPBYTE pData,
  _In_ DWORD  cbData
);

參數

hPrinter [in]

函式設定組態資料的印表機或列印伺服器的控制碼。 使用 OpenPrinter、 OpenPrinter2或 AddPrinter 函式來擷取印表機控制碼。

pValueName [in]

識別要設定之資料的 Null 終止字串指標。

對於印表機，此字串是在登錄中印表機的 「PrinterDriverData」 機碼底下登錄值的名稱。

對於列印伺服器，此字串是下列一節所列的其中一個預先定義字串。

輸入 [in]

表示 pData 參數指向之資料類型的程式碼。 如需可能的類型代碼清單，請參閱 登錄實數值型別。

pData [in]

包含印表機組態資料的位元組陣列指標。

cbData [in]

陣列的大小，以位元組為單位。

傳回值

如果函式成功，傳回值 會ERROR_SUCCESS。

如果函式失敗，則傳回值是錯誤值。

備註

注意

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

若要擷取印表機的現有組態資料，請呼叫 GetPrinterDataEx 或 GetPrinterData 函式。

如果 hPrinter 是列印伺服器的控制碼， pValueName 可以指定下列其中一個預先定義的值。

值	註解
SPLREG_ALLOW_USER_MANAGEFORMS	Windows XP with Service Pack 2 (SP2) 和更新版本 Windows Server 2003 Service Pack 1 (SP1) 和更新版本
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP	Windows Server 2003 和更新版本不支援
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS	Windows 7 和更新版本
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE	Windows 7 和更新版本
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE	Windows 7 和更新版本
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT	Windows 7 和更新版本
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY	Windows 7 和更新版本
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY	Windows 7 和更新版本
SPLREG_RETRY_POPUP	成功傳回時，如果伺服器設定為重試所有工作的快顯視窗， 則 pData 會包含 1，如果伺服器未重試所有作業的快顯視窗，則為 0。 Windows Server 2003 和更新版本不支援
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT	Windows Server 2003 和更新版本

pValueName的下列值會決定發生錯誤時的集區列印行為。

值	註解
SPLREG_RESTART_JOB_ON_POOL_ERROR	pData的值表示發生錯誤後，作業在另一個埠上重新開機的時間，以秒為單位。 此設定會與 SPLREG_RESTART_JOB_ON_POOL_ENABLED搭配使用。
SPLREG_RESTART_JOB_ON_POOL_ENABLED	pData中的非零值表示已啟用SPLREG_RESTART_JOB_ON_POOL_ERROR。

SPLREG_RESTART_JOB_ON_POOL_ERROR中指定的時間是最短的時間。 根據下列埠監視器設定而定，實際時間可能較長，這些設定是此登錄機碼下的登錄值：

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\ <MonitorName> \Ports

呼叫 RegSetValueEx 函式來設定這些值。

埠監視設定	資料類型	意義
StatusUpdateEnabled	REG_DWORD	如果非零值，可讓埠監視器以埠狀態更新多工緩衝處理常式。
StatusUpdateInterval	REG_DWORD	指定埠監視器以埠狀態更新多工緩衝處理常式的間隔，以分鐘為單位。

在 Windows 7 和更新版本的 Windows 中，預設會在用戶端上轉譯傳送至列印伺服器的列印工作。 您可以在 pValueName中設定下列值，為每部印表機設定列印工作的用戶端轉譯。

設定	資料類型	描述
EMFDespoolingSetting	REG_DWORD	值為 0，如果登錄中沒有此值，則啟用列印工作的預設用戶端轉譯。 值為 1 會停用列印工作的用戶端轉譯。
ForceClientSideRendering	REG_DWORD	值為 0，或如果此值不存在於登錄中，會導致列印工作在用戶端上轉譯。 如果無法在用戶端上轉譯列印工作，則會在伺服器上轉譯。 如果無法轉譯伺服器上的列印工作，它將會失敗。 值為 1 會在用戶端上轉譯列印工作。 如果無法在用戶端上轉譯列印工作，它將會失敗。

規格需求

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

另請參閱

列印

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

GetPrinter

GetPrinterData

GetPrinterDataEx

OpenPrinter

SetPrinterDataEx