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 [僅限傳統型應用程式]
標頭
Winspool.h (包含 Windows.h)
程式庫
Winspool.lib
DLL
Winspool.drv
Unicode 與 ANSI 名稱
 GetPrinterW (Unicode) 和 GetPrinterA (ANSI)

另請參閱

列印

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

AbortPrinter

AddPrinter

ClosePrinter

DeletePrinter

EnumPrinters

PRINTER_INFO_1

PRINTER_INFO_2

PRINTER_INFO_3

PRINTER_INFO_4

PRINTER_INFO_5

PRINTER_INFO_7

PRINTER_INFO_8

PRINTER_INFO_9

OpenPrinter

SetPrinter