EnumPrinters-Funktion

Artikel
06/13/2023

Die EnumPrinters-Funktion listet verfügbare Drucker, Druckserver, Domänen oder Druckanbieter auf.

Syntax

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

Parameter

Flaggen [in]

Die Typen von Druckobjekten, die die Funktion auflisten soll. Dieser Wert kann mindestens einer der folgenden Werte sein.

Wert	Bedeutung
PRINTER_ENUM_LOCAL	Wenn das flag PRINTER_ENUM_NAME nicht auch übergeben wird, ignoriert die Funktion den Parameter Name und listet die lokal installierten Drucker auf. Wenn auch PRINTER_ENUM_NAME übergeben wird, listet die Funktion die lokalen Drucker unter Name auf.
PRINTER_ENUM_NAME	Die Funktion listet den drucker auf, der durch Name identifiziert wird. Dies kann ein Server, eine Domäne oder ein Druckanbieter sein. Wenn NameNULL ist, listet die Funktion die verfügbaren Druckanbieter auf.
PRINTER_ENUM_SHARED	Die Funktion listet Drucker auf, die über das freigegebene Attribut verfügen. Kann nicht isoliert verwendet werden. Verwenden Sie einen OR-Vorgang, um mit einem anderen PRINTER_ENUM Typ zu kombinieren.
PRINTER_ENUM_CONNECTIONS	Die Funktion listet die Liste der Drucker auf, mit denen der Benutzer vorherige Verbindungen hergestellt hat.
PRINTER_ENUM_NETWORK	Die Funktion listet Netzwerkdrucker in der Domäne des Computers auf. Dieser Wert ist nur gültig, wenn Ebene 1 ist.
PRINTER_ENUM_REMOTE	Die Funktion listet Netzwerkdrucker und Druckserver in der Domäne des Computers auf. Dieser Wert ist nur gültig, wenn Ebene 1 ist.
PRINTER_ENUM_CATEGORY_3D	Die Funktion listet nur 3D-Drucker auf.
PRINTER_ENUM_CATEGORY_ALL	Die Funktion listet alle Druckgeräte auf, einschließlich 3D-Druckern.

Wenn Stufe 4 ist, können Sie nur die PRINTER_ENUM_CONNECTIONS und PRINTER_ENUM_LOCAL Konstanten verwenden.

Hinweis

3D-Druckgeräte werden standardmäßig nicht aufgelistet. Sie müssen sowohl PRINTER_ENUM_CATEGORY_3D als auch PRINTER_ENUM_LOCAL einschließen, um nur 3D-Drucker aufzulisten. Um 3D-Drucker zusammen mit allen anderen lokalen Druckern einzubeziehen, verwenden Sie PRINTER_ENUM_CATEGORY_ALL und PRINTER_ENUM_LOCAL.

Name [in]

Wenn Ebene 1 ist, Flags PRINTER_ENUM_NAME enthält und Name nicht NULL ist, ist Name ein Zeiger auf eine null-beendete Zeichenfolge, die den Namen des zu enumerierenden Objekts angibt. Diese Zeichenfolge kann der Name eines Servers, einer Domäne oder eines Druckanbieters sein.

Wenn Ebene 1 ist, Flags PRINTER_ENUM_NAME und NameNULL ist, listet die Funktion die verfügbaren Druckanbieter auf.

Wenn Ebene 1 ist, Flags PRINTER_ENUM_REMOTE und NameNULL ist, listet die Funktion die Drucker in der Domäne des Benutzers auf.

Wenn Level 2 oder 5 ist, ist Name ein Zeiger auf eine NULL-Zeichenfolge, die den Namen eines Servers angibt, dessen Drucker aufgelistet werden sollen. Wenn diese Zeichenfolge NULL ist, listet die Funktion die auf dem lokalen Computer installierten Drucker auf.

Wenn Ebene 4 ist, sollte der NameNULL sein. Die Funktion fragt immer auf dem lokalen Computer ab.

Wenn NameNULL ist, legen Sie Flags auf PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS listet Drucker auf, die auf dem lokalen Computer installiert sind. Zu diesen Druckern gehören die Drucker, die physisch an den lokalen Computer angeschlossen sind, sowie Remotedrucker, mit denen eine Netzwerkverbindung verbunden ist.

Wenn Name nicht NULL ist, legen Sie Flags auf PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME listet die lokalen Drucker auf, die auf dem Servernamen installiert sind.

Ebene [in]

Der Typ der Datenstrukturen, auf die von pPrinterEnum verwiesen wird. Gültige Werte sind 1, 2, 4 und 5, die den Datenstrukturen PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 und PRINTER_INFO_5 entsprechen.

Dieser Wert kann 1, 2, 4 oder 5 sein.

pPrinterEnum [out]

Ein Zeiger auf einen Puffer, der ein Array von PRINTER_INFO_1-, PRINTER_INFO_2-, PRINTER_INFO_4- oder PRINTER_INFO_5-Strukturen empfängt. Jede Struktur enthält Daten, die ein verfügbares Druckobjekt beschreiben.

Wenn Ebene 1 ist, enthält das Array PRINTER_INFO_1 Strukturen. Wenn Ebene 2 ist, enthält das Array PRINTER_INFO_2 Strukturen. Wenn Ebene 4 ist, enthält das Array PRINTER_INFO_4 Strukturen. Wenn Ebene 5 ist, enthält das Array PRINTER_INFO_5 Strukturen.

Der Puffer muss groß genug sein, um das Array von Datenstrukturen und allen Zeichenfolgen oder anderen Daten zu empfangen, auf die die Strukturmember verweisen. Wenn der Puffer zu klein ist, gibt der pcbNeeded-Parameter die erforderliche Puffergröße zurück.

cbBuf [in]

Die Größe des Puffers in Bytes, auf den pPrinterEnum verweist.

pcbNeeded [ out]

Ein Zeiger auf einen Wert, der die Anzahl der kopierten Bytes empfängt, wenn die Funktion erfolgreich ist, oder die Anzahl der erforderlichen Bytes, wenn cbBuf zu klein ist.

pcReturned [out]

Ein Zeiger auf einen Wert, der die Anzahl der PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 oder PRINTER_INFO_5 Strukturen empfängt, die die Funktion im Array zurückgibt, auf das pPrinterEnum verweist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.

Bemerkungen

Rufen Sie diese Methode nicht in DllMain auf.

Hinweis

Dies ist eine blockierende oder synchrone Funktion und wird möglicherweise nicht sofort zurückgegeben. Wie schnell diese Funktion zurückgibt, hängt von Laufzeitfaktoren wie Netzwerk-status, Druckserverkonfiguration und Druckertreiberimplementierungsfaktoren ab, die beim Schreiben einer Anwendung schwer vorherzusagen sind. Wenn Sie diese Funktion über einen Thread aufrufen, der die Interaktion mit der Benutzeroberfläche verwaltet, kann die Anwendung nicht reagieren.

Wenn EnumPrinters eine PRINTER_INFO_1-Struktur zurückgibt, in der PRINTER_ENUM_CONTAINER angegeben wird, gibt dies an, dass eine Hierarchie von Druckerobjekten vorhanden ist. Eine Anwendung kann die Hierarchie auflisten, indem sie EnumPrinters erneut aufruft und Name auf den Wert des pName-Elements der PRINTER_INFO_1-Struktur festlegt.

Die EnumPrinters-Funktion ruft keine Sicherheitsinformationen ab. Wenn PRINTER_INFO_2 Strukturen in dem Array zurückgegeben werden, auf das pPrinterEnum verweist, werden ihre pSecurityDescriptor-Member auf NULL festgelegt.

Rufen Sie GetDefaultPrinter auf, um Informationen zum Standarddrucker abzurufen.

Die PRINTER_INFO_4-Struktur bietet eine einfache und extrem schnelle Möglichkeit zum Abrufen der Namen der Drucker, die auf einem lokalen Computer installiert sind, sowie die Remoteverbindungen, die ein Benutzer eingerichtet hat. Wenn EnumPrinters mit einer PRINTER_INFO_4 Datenstruktur aufgerufen wird, fragt diese Funktion die Registrierung nach den angegebenen Informationen ab und gibt dann sofort zurück. Dies unterscheidet sich vom Verhalten von EnumPrinters , wenn sie mit anderen Ebenen von PRINTER_INFO_* -Datenstrukturen aufgerufen werden. Insbesondere wenn EnumPrinters mit einer Datenstruktur der Ebene 2 (PRINTER_INFO_2) aufgerufen wird, führt es einen OpenPrinter-Aufruf für jede Remoteverbindung aus. Wenn eine Remoteverbindung ausfällt oder der Remoteserver nicht mehr vorhanden ist oder der Remotedrucker nicht mehr vorhanden ist, muss die Funktion warten, bis das RPC-Timeout auftritt und folglich beim OpenPrinter-Aufruf fehlschlägt. Dies kann eine Weile dauern. Durch das Übergeben einer PRINTER_INFO_4-Struktur kann eine Anwendung ein Minimum an erforderlichen Informationen abrufen. wenn ausführlichere Informationen gewünscht werden, kann ein nachfolgender EnumPrinters-Aufruf der Stufe 2 erfolgen.

Windows Vista: Die von EnumPrinters zurückgegebenen Druckerdaten werden aus einem lokalen Cache abgerufen, wenn der Wert von Level 4 ist.

Die folgende Tabelle zeigt die EnumPrinters-Ausgabe für verschiedene Flags-Werte , wenn der Level-Parameter auf 1 festgelegt ist.

In der Spalte Name-Parameter der Tabelle sollten Sie einen entsprechenden Namen für Druckanbieter, Domäne und Computer ersetzen. Beispielsweise können Sie für "Druckanbieter" den Namen des Netzwerkdruckanbieters oder den Namen des lokalen Druckanbieters verwenden. Um Die Namen des Druckanbieters abzurufen, rufen Sie EnumPrinters auf, wobei Name auf NULL festgelegt ist.

Flags-Parameter	Nameparameter	Ergebnis
PRINTER_ENUM_LOCAL (und nicht PRINTER_ENUM_NAME)	Der Name-Parameter wird ignoriert.	Alle lokalen Drucker.
PRINTER_ENUM_NAME	"Druckanbieter"	Alle Domänennamen
PRINTER_ENUM_NAME	"Druckanbieter! Domäne"	Alle Drucker und Druckserver in der Domäne des Computers
PRINTER_ENUM_NAME	"Druckanbieter!! \\Computer"	Alle Unter \\Machine freigegebenen Drucker
PRINTER_ENUM_NAME	Eine leere Zeichenfolge, ""	Alle lokalen Drucker.
PRINTER_ENUM_NAME	NULL	Alle Druckanbieter in der Domäne des Computers
PRINTER_ENUM_CONNECTIONS	Der Name-Parameter wird ignoriert.	Alle verbundenen Remotedrucker
PRINTER_ENUM_NETWORK	Der Name-Parameter wird ignoriert.	Alle Drucker in der Domäne des Computers
PRINTER_ENUM_REMOTE	Eine leere Zeichenfolge, ""	Alle Drucker und Druckserver in der Domäne des Computers
PRINTER_ENUM_REMOTE	"Druckanbieter"	Identisch mit PRINTER_ENUM_NAME
PRINTER_ENUM_REMOTE	"Druckanbieter! Domäne"	Alle Drucker und Druckserver in der Domäne des Computers, unabhängig von der angegebenen Domäne .
PRINTER_ENUM_CATEGORY_3D	Der Name-Parameter wird ignoriert.	Es werden nur 3D-Drucker aufgelistet.
PRINTER_ENUM_CATEGORY_ALL	Der Name-Parameter wird ignoriert.	3D-Drucker werden zusammen mit allen anderen Druckern aufgelistet.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	Winspool.h (einschließlich Windows.h)
Bibliothek	Winspool.lib
DLL	Winspool.drv
Unicode- und ANSI-Name	EnumPrintersW (Unicode) und EnumPrintersA (ANSI)

Siehe auch

Drucken
Druckspooler-API-Funktionen
AddPrinter
DeletePrinter
GetPrinter
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_4
PRINTER_INFO_5
SetPrinter

Share via