EnumPrinters 函式

發行項
06/13/2023

EnumPrinters函式會列舉可用的印表機、列印伺服器、網域或列印提供者。

語法

BOOL EnumPrinters(
  _In_  DWORD   Flags,
  _In_  LPTSTR  Name,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinterEnum,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded,
  _Out_ LPDWORD pcReturned
);

參數

旗標 [in]

函式應該列舉的列印物件類型。此值可以是下列一或多個值。

值	意義
PRINTER_ENUM_LOCAL	如果未傳遞PRINTER_ENUM_NAME旗標，函式會忽略 Name 參數，並列舉本機安裝的印表機。如果也會傳遞PRINTER_ENUM_NAME，函式會在 Name上列舉本機印表機。
PRINTER_ENUM_NAME	函式會列舉名稱所識別的印表機。這可以是伺服器、網域或列印提供者。如果 Name 為 Null，函式會列舉可用的列印提供者。
PRINTER_ENUM_SHARED	函式會列舉具有共用屬性的印表機。無法隔離使用;使用 OR 作業來結合另一個PRINTER_ENUM類型。
PRINTER_ENUM_CONNECTIONS	函式會列舉使用者已建立先前連線的印表機清單。
PRINTER_ENUM_NETWORK	函式會列舉電腦網域中的網路印表機。只有在 Level 為 1 時，這個值才有效。
PRINTER_ENUM_REMOTE	函式會列舉電腦網域中的網路印表機和列印伺服器。只有在 Level 為 1 時，這個值才有效。
PRINTER_ENUM_CATEGORY_3D	函式只會列舉 3D 印表機。
PRINTER_ENUM_CATEGORY_ALL	函式會列舉所有列印裝置，包括 3D 印表機。

如果 Level 為 4，您只能使用PRINTER_ENUM_CONNECTIONS和PRINTER_ENUM_LOCAL常數。

注意

預設不會列舉 3D 列印裝置。您必須同時包含 PRINTER_ENUM_CATEGORY_3D 和 PRINTER_ENUM_LOCAL ，才能只列舉 3D 印表機。若要包含 3D 印表機，以及所有其他本機印表機，請使用 PRINTER_ENUM_CATEGORY_ALL 和 PRINTER_ENUM_LOCAL。

名稱 [in]

如果 Level 為 1， Flags 會包含PRINTER_ENUM_NAME，而 Name 為非Null，則 Name 是 Null 終止字串的指標，指定要列舉的物件名稱。此字串可以是伺服器、網域或列印提供者的名稱。

如果 Level 為 1， Flags 會包含PRINTER_ENUM_NAME， 而 Name 為 Null，則函式會列舉可用的列印提供者。

如果 Level 為 1， Flags 會包含PRINTER_ENUM_REMOTE， 而 Name 為 Null，則函式會列舉使用者網域中的印表機。

如果 Level 為 2 或 5，Name 是 Null 終止字串的指標，指定要列舉其印表機的伺服器名稱。如果此字串為 Null，則函式會列舉安裝在本機電腦上的印表機。

如果 Level 為 4， 則 Name 應該是 Null。函式一律會在本機電腦上查詢。

當 Name 為 Null時，將 Flags 設定為 PRINTER_ENUM_LOCAL |PRINTER_ENUM_CONNECTIONS列舉安裝在本機電腦上的印表機。這些印表機包括實際連接到本機電腦以及其具有網路連線的遠端印表機。

當 Name 不是 Null時，將 Flags 設定為 PRINTER_ENUM_LOCAL |PRINTER_ENUM_NAME列舉安裝在伺服器名稱上的本機印表機。

層級 [in]

pPrinterEnum所指向的資料結構類型。有效值為 1、2、4 和 5，對應至 PRINTER_INFO_1、 PRINTER_INFO_2 、 PRINTER_INFO_4和 PRINTER_INFO_5 資料結構。

此值可以是 1、2、4 或 5。

pPrinterEnum [out]

緩衝區的指標，可接收 PRINTER_INFO_1、 PRINTER_INFO_2、 PRINTER_INFO_4或 PRINTER_INFO_5 結構的陣列。每個結構都包含描述可用列印物件的資料。

如果 Level 為 1，陣列會包含 PRINTER_INFO_1 結構。如果 Level 為 2，陣列會包含 PRINTER_INFO_2 結構。如果 Level 為 4，陣列會包含 PRINTER_INFO_4 結構。如果 Level 為 5，陣列會包含 PRINTER_INFO_5 結構。

緩衝區必須夠大，才能接收資料結構陣列，以及結構成員指向的任何字串或其他資料。如果緩衝區太小， 則 azureNeeded 參數會傳回所需的緩衝區大小。

cbBuf [in]

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

azureNeeded [out]

值指標，這個值會接收函式成功時所複製的位元組數目，或 cbBuf 太小時所需的位元組數目。

pcReturned [out]

值的指標，這個值會接收pPrinterEnum指向的陣列中PRINTER_INFO_1、PRINTER_INFO_2、PRINTER_INFO_4或PRINTER_INFO_5結構。

傳回值

如果函式成功，則傳回值是非零值。

如果此函式失敗，則傳回值為零。

備註

請勿在 DllMain中呼叫這個方法。

注意

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

如果 EnumPrinters 傳回 指定PRINTER_ENUM_CONTAINER PRINTER_INFO_1結構，這表示有印表機物件的階層。應用程式可以再次呼叫EnumPrinters來列舉階層，並將Name設定為結構pName成員PRINTER_INFO_1的值。

EnumPrinters函式不會擷取安全性資訊。如果pPrinterEnum指向的陣列中傳回PRINTER_INFO_2結構，其pSecurityDescriptor成員會設定為Null。

若要取得預設印表機的相關資訊，請呼叫 GetDefaultPrinter。

PRINTER_INFO_4結構提供簡單且非常快速的方式，可擷取安裝在本機電腦上的印表機名稱，以及使用者已建立的遠端連線。當使用PRINTER_INFO_4資料結構呼叫EnumPrinters時，該函式會查詢登錄中的指定資訊，然後立即傳回。這與使用其他層級的 PRINTER_INFO_*資料結構呼叫時，EnumPrinters的行為不同。特別是，當使用層級 2 (PRINTER_INFO_2 ) 資料結構呼叫EnumPrinters時，它會在每個遠端連線上執行OpenPrinter呼叫。如果遠端連線已關閉，或遠端伺服器已不存在，或遠端印表機已不存在，則函式必須等候 RPC 逾時，因此 OpenPrinter 呼叫失敗。這可能需要一段時間。傳遞 PRINTER_INFO_4 結構可讓應用程式擷取最少的必要資訊;如果需要更詳細的資訊，可以進行後續 的 EnumPrinters 層級 2 呼叫。

Windows Vista：EnumPrinters傳回的印表機資料會在Level值為 4 時，從本機快取擷取。

下表顯示當 Level參數設定為 1 時，各種Flags值的EnumPrinters輸出。

在資料表的 Name 參數資料行中，您應該為列印提供者、網域和電腦取代適當的名稱。例如，針對「列印提供者」，您可以使用網路列印提供者的名稱或本機列印提供者的名稱。若要擷取列印提供者名稱，請呼叫名稱設為Null的EnumPrinters。

Flags 參數	Name 參數	結果
PRINTER_ENUM_LOCAL (而非PRINTER_ENUM_NAME)	忽略 Name參數。	所有本機印表機。
PRINTER_ENUM_NAME	「列印提供者」	所有功能變數名稱
PRINTER_ENUM_NAME	「列印提供者！網域」	電腦網域中的所有印表機和列印伺服器
PRINTER_ENUM_NAME	「列印提供者！！\\Machine」	在 \\Machine 共用的所有印表機
PRINTER_ENUM_NAME	空字串「」	所有本機印表機。
PRINTER_ENUM_NAME	NULL	電腦網域中的所有列印提供者
PRINTER_ENUM_CONNECTIONS	會忽略 Name參數。	所有連線的遠端印表機
PRINTER_ENUM_NETWORK	會忽略 Name參數。	電腦網域中的所有印表機
PRINTER_ENUM_REMOTE	空字串「」	電腦網域中的所有印表機和列印伺服器
PRINTER_ENUM_REMOTE	「列印提供者」	與PRINTER_ENUM_NAME相同
PRINTER_ENUM_REMOTE	「列印提供者！網域」	電腦網域中的所有印表機和列印伺服器，不論指定網域為何。
PRINTER_ENUM_CATEGORY_3D	會忽略 Name參數。	只會列舉 3D 印表機。
PRINTER_ENUM_CATEGORY_ALL	會忽略 Name參數。	列舉 3D 印表機以及所有其他印表機。

規格需求

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

另請參閱

列印
列印多工緩衝處理器 API 函式
AddPrinter
DeletePrinter
GetPrinter
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_4
PRINTER_INFO_5
SetPrinter

共用方式為

EnumPrinters 函式

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源