GetPrinter 函式
GetPrinter函式會擷取指定印表機的相關資訊。
語法
BOOL GetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_Out_ LPBYTE pPrinter,
_In_ DWORD cbBuf,
_Out_ LPDWORD pcbNeeded
);
參數
-
hPrinter [in]
-
函式擷取資訊的印表機控制碼。 使用 OpenPrinter 或 AddPrinter 函式來擷取印表機控制碼。
-
層級 [in]
-
函式儲存至 pPrinter所指向之緩衝區的層級或結構類型。
此值可以是 1、2、3、4、5、6、7、8 或 9。
-
pPrinter [out]
-
緩衝區的指標，這個緩衝區會接收包含指定印表機相關資訊的結構。 緩衝區必須夠大，才能接收結構成員指向的任何字串或其他資料。 如果緩衝區太小， 則 azureNeeded 參數會傳回所需的緩衝區大小。
結構的類型取決於 Level的值。
層級 結構 - 1
包含一般印表機資訊的 PRINTER_INFO_1 結構。 - 2
包含印表機詳細資訊 的PRINTER_INFO_2 結構。 - 3
包含印表機安全性資訊的 PRINTER_INFO_3 結構。 - 4
包含最少印表機資訊的 PRINTER_INFO_4 結構，包括印表機的名稱、伺服器的名稱，以及印表機是遠端還是本機。 - 5
包含印表機屬性和逾時設定等印表機資訊的 PRINTER_INFO_5 結構。 - 6
指定印表機狀態值的 PRINTER_INFO_6 結構。 - 7
PRINTER_INFO_7結構，指出印表機是否在目錄服務中發佈。 - 8
指定全域預設印表機設定 的PRINTER_INFO_8 結構。 - 9
指定每個使用者預設印表機設定 的PRINTER_INFO_9 結構。 -
cbBuf [in]
-
pPrinter所指向之緩衝區的大小，以位元組為單位。
-
azureNeeded [out]
-
函式設定為印表機資訊大小，以位元組為單位的變數指標。 如果 cbBuf 小於此值， GetPrinter 就會失敗，而值代表所需的緩衝區大小。 如果 cbBuf 等於或大於此值， GetPrinter 就會成功，而值代表儲存在緩衝區中的位元組數目。
傳回值
如果函式成功，則傳回值是非零值。
如果此函式失敗，則傳回值為零。
備註
注意
這是封鎖或同步函式，可能不會立即傳回。 此函式傳回的速度取決於執行時間因素，例如網路狀態、列印伺服器組態，以及難以在撰寫應用程式時預測的印表機驅動程式實作因素。 從管理與使用者介面互動的執行緒呼叫此函式，可能會讓應用程式看起來沒有回應。
PRINTER_INFO_2、PRINTER_INFO_8和PRINTER_INFO_9結構中的pDevMode成員可以是Null。 發生這種情況時，印表機將無法使用，直到驅動程式重新安裝成功為止。
對於 包含 安全性描述元指標的 PRINTER_INFO_2和PRINTER_INFO_3 結構，函式只會擷取呼叫端有權讀取之安全性描述元的那些元件。 若要擷取特定的安全性描述元元件，您必須在呼叫 OpenPrinter 函式以擷取印表機控制碼時指定必要的存取權限。 下表顯示讀取各種安全性描述元元件所需的存取權限。
| 存取權限 | 安全性描述項元件 |
|---|---|
| READ_CONTROL |
擁有者 主要群組 DACL () 的任意存取控制清單 |
| ACCESS_SYSTEM_SECURITY |
SACL (系統存取控制清單) |
如果您指定層級 7，PRINTER_INFO_7的dwAction成員會傳回下列其中一個值，以指出印表機是否在目錄服務中發佈。
| dwAction 值 | 意義 |
|---|---|
| DSPRINT_PUBLISH | 印表機已發佈。 pszObjectGUID成員包含與印表機相關聯的目錄服務列印佇列物件的 GUID。 |
| DSPRINT_UNPUBLISH | 印表機未發佈。 |
| DSPRINT_PENDING | 表示系統嘗試完成發佈或取消發佈作業。 如果 SetPrinter 呼叫無法發佈或取消發佈印表機，系統會進一步嘗試在背景中完成作業。 |
從 Windows Vista 開始，當hPrinter參考由列印伺服器裝載的印表機，且至少有一個與列印伺服器的開啟連線時，GetPrinter所傳回的印表機資料會從本機快取擷取。 在所有其他設定中，會從列印伺服器查詢印表機資料。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows 2000 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows 2000 Server [僅限傳統型應用程式] |
| 標頭 |
|
| 程式庫 |
|
| DLL |
|
| Unicode 與 ANSI 名稱 |
GetPrinterW (Unicode) 和 GetPrinterA (ANSI) |