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、OpenPrinter2或AddPrinter函式來擷取印表機控制碼。

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 是印表機的控制碼，而 pKeyName 為 Null 或空字串， SetPrinterDataEx 會傳回 ERROR_INVALID_PARAMETER。

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

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

pValueName [in]

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

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

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

輸入 [in]

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

如果 pKeyName 指定其中一個預先定義的目錄服務金鑰， 則 Type 必須是 REG_SZ、 REG_MULTI_SZ、 REG_DWORD或 REG_BINARY。 如果使用 REG_BINARY ， cbData 必須等於 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