共用方式為


SetPrinterDataEx 函式

SetPrinterDataEx 函式會設定印表機或列印伺服器的組態資料。 函式會將組態資料儲存在印表機的登錄機碼之下。

語法

DWORD SetPrinterDataEx(
  _In_ HANDLE  hPrinter,
  _In_ LPCTSTR pKeyName,
  _In_ LPCTSTR pValueName,
  _In_ DWORD   Type,
  _In_ LPBYTE  pData,
  _In_ DWORD   cbData
);

參數

hPrinter [in]

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

pKeyName [in]

Null 終止字串的指標,指定要設定之值的索引鍵。 如果指定的索引鍵或子機碼不存在,函式會建立它們。

若要儲存可在 DS (DS) 目錄中發佈的設定資料,請指定下列其中一個預先定義的登錄機碼。

意義
SPLDS_DRIVER_KEY
印表機驅動程式會使用此金鑰來儲存驅動程式屬性。
SPLDS_SPOOLER_KEY
保留的。 只供列印多工緩衝處理常式用來儲存內部多工緩衝處理常式屬性。
SPLDS_USER_KEY
應用程式會使用此金鑰來儲存印表機屬性,例如印表機資產編號。

只有在架構中有對應的屬性時,才會在目錄服務中發佈儲存在SPLDS_USER_KEY金鑰底下的值。 如果屬性不存在,則網域系統管理員必須建立屬性。 若要在使用SetPrinterDataEx新增或變更值之後發佈使用者定義屬性,請使用Level = 7 呼叫SetPrinter,並將dwAction成員設定為PRINTER_INFO_7 DSPRINT_UPDATE

您可以指定其他金鑰來儲存非 DS 組態資料。 使用反斜線 ( \ ) 字元做為分隔符號,指定具有一或多個子機碼的路徑。

如果 hPrinter 是印表機的控制碼,而 pKeyNameNull 或空字串, SetPrinterDataEx 會傳回 ERROR_INVALID_PARAMETER

如果 hPrinter 是列印伺服器的控制碼,則會忽略 pKeyName

請勿使用 SPLDS_SPOOLER_KEY。 若要變更多工緩衝處理器印表機屬性,請使用具有Level = 2 的SetPrinter

pValueName [in]

以 Null 結束之字串的指標,可識別要設定的資料。

對於印表機,此字串會指定 pKeyName 機碼下的值名稱。

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

輸入 [in]

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

如果 pKeyName 指定其中一個預先定義的目錄服務金鑰, 則 Type 必須是 REG_SZREG_MULTI_SZREG_DWORDREG_BINARY。 如果使用 REG_BINARYcbData 必須等於 1,而目錄服務會將資料視為布林值。

pData [in]

包含印表機組態資料的緩衝區指標。

cbData [in]

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

傳回值

如果函式成功,傳回值會 ERROR_SUCCESS

如果函式失敗,傳回值為錯誤值。

備註

注意

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

若要擷取印表機或列印多工緩衝處理器的現有組態資料,請呼叫 GetPrinterDataEx 函 式。

呼叫 SetPrinterDataEx 並將 pKeyName 參數設定為 「PrinterDriverData」 相當於呼叫 SetPrinterData 函式。

如果 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 指定埠監視器以埠狀態更新多工緩衝處理常式的間隔,以分鐘為單位。

為了確保多工緩衝處理常式會在集區中未列印列印工作時,將作業重新導向至集區中的下一個可用印表機 () ,埠監視器必須支援 SNMP,而且集區中的網路埠必須設定為「啟用 SNMP 狀態」。支援 SNMP 的埠監視器是標準 TCP/IP 埠監視器。

在 Windows 7 和更新版本的 Windows 中,預設會在用戶端上轉譯傳送至列印伺服器的列印工作。 您可以將 pKeyName 設定為 「PrinterDriverData」,並將 pValueName 設定為下表中的設定值,以設定列印工作的用戶端轉譯。

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

規格需求

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

另請參閱

列印

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

GetPrinterDataEx

OpenPrinter

SetPrinter

PRINTER_INFO_7