GetPrinterDataEx 函式

  • 發行項

GetPrinterDataEx函式會擷取指定印表機或列印伺服器的組態資料。 GetPrinterDataEx 可以擷取 SetPrinterData 函式儲存的值。 此外， GetPrinterDataEx 可以擷取 SetPrinterDataEx 函數儲存在指定索引鍵下的值。

語法

DWORD GetPrinterDataEx(
  _In_  HANDLE  hPrinter,
  _In_  LPCTSTR pKeyName,
  _In_  LPCTSTR pValueName,
  _Out_ LPDWORD pType,
  _Out_ LPBYTE  pData,
  _In_  DWORD   nSize,
  _Out_ LPDWORD pcbNeeded
);

參數

hPrinter [in]

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

pKeyName [in]

Null 終止字串的指標，指定要擷取之值的索引鍵。 使用反斜線 ( \ ) 字元做為分隔符號來指定具有一或多個子機碼的路徑。

如果 hPrinter 是印表機的控制碼，且 pKeyName 為 Null 或空字串， GetPrinterDataEx 會傳回 ERROR_INVALID_PARAMETER。

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

pValueName [in]

識別要擷取之資料的 Null 終止字串指標。

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

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

pType [out]

變數的指標，可接收儲存在 值中的資料型別。 函式會在儲存資料時傳回 SetPrinterDataEx 呼叫中指定的類型。 如果您不需要資訊，此參數可以是 Null 。 GetPrinterDataEx會將pType傳遞為RegQueryValueEx函式呼叫的lpdwType參數。

pData [out]

接收組態資料的緩衝區指標。

nSize [in]

pData所指向之緩衝區的大小，以位元組為單位。

azureNeeded [out]

接收組態資料大小之變數的指標，以位元組為單位。 如果 nSize 指定的緩衝區大小太小，則函式會傳回 ERROR_MORE_DATA， 而ERROR_MORE_DATA，而eded 表示所需的緩衝區大小。

傳回值

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

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

備註

注意

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

GetPrinterDataEx 會擷取 SetPrinterDataEx 和 SetPrinterData 函式所設定的印表機組態資料。

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

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

值 註解
SPLREG_ALLOW_USER_MANAGEFORMS Windows XP with Service Pack 2 (SP2) 和更新版本
Windows Server 2003 Service Pack 1 (SP1) 和更新版本
SPLREG_ARCHITECTURE
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_DNS_MACHINE_NAME
SPLREG_DS_PRESENT 成功傳回時，如果電腦位於 DS 網域， 則 pData 會包含0x0001，否則為 0。
SPLREG_DS_PRESENT_FOR_USER 成功傳回時，如果使用者登入 DS 網域， 則 pData 會包含0x0001，否則為 0。
SPLREG_EVENT_LOG
SPLREG_MAJOR_VERSION
SPLREG_MINOR_VERSION
SPLREG_NET_POPUP Windows Server 2003 和更新版本不支援
SPLREG_NET_POPUP_TO_COMPUTER 成功傳回時，如果應該將作業通知傳送至用戶端電腦， 則 pData 會包含 1，如果作業通知要傳送給使用者，則為 0。
Windows Server 2003 和更新版本不支援
SPLREG_OS_VERSION Windows XP 及更新版本
SPLREG_OS_VERSIONEX
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_REMOTE_FAX 成功傳回時，如果傳真服務支援遠端用戶端， 則 pData 會包含0x0001，否則為 0。
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

呼叫 RegQueryValueEx 函式來查詢這些值。

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

如果 pKeyName 是其中一個預先定義的目錄服務 (DS) 索引鍵 (，請參閱 SetPrinter) ，且 pValueName 包含逗號 ('，') ，則逗號前面的 pValueName 部分是值名稱，而逗號右邊的 pValueName 部分是 DS 屬性 OID。 系統會建立名為 OID 的子機碼，並建立包含值名稱的新值，並在 OID 機碼下輸入 OID。 SetPrinterDataEx 也會在 DS 索引鍵下新增值名稱和資料。

在 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 名稱
 GetPrinterDataExW (Unicode) 和 GetPrinterDataExA (ANSI)

另請參閱

列印

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

OpenPrinter

SetPrinterDataEx