OpenPrinter-Funktion

Die OpenPrinter-Funktion ruft ein Handle für den angegebenen Drucker oder Druckerserver oder andere Handles im Drucksubsystem ab.

Syntax

BOOL OpenPrinter(
  _In_  LPTSTR             pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault
);

Parameter

pPrinterName [ In]

Ein Zeiger auf eine nullbeendigte Zeichenfolge, die den Namen des Druckers oder Druckerservers, des Druckerobjekts, des XcvMonitor oder des XcvPort angibt.

Verwenden Sie für ein Druckerobjekt: PrinterName, Job xxxx. Verwenden Sie für einen XcvMonitor ServerName, XcvMonitor MonitorName. Verwenden Sie für einen XcvPort ServerName, XcvPort PortName.

Wenn DER WERT NULL ist, wird der lokale Druckerserver angegeben.

phPrinter [ out]

Ein Zeiger auf eine Variable, die ein Handle (nicht threadsicher) zum geöffneten Drucker- oder Druckerserverobjekt empfängt.

Der phPrinter-Parameter kann ein Xcv-Handle für die Verwendung mit der XcvData-Funktion zurückgeben. Weitere Informationen zu XcvData finden Sie im DDK.

pDefault [ In]

Ein Zeiger auf eine PRINTER _ DEFAULTS-Struktur. Dieser Wert kann NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich 0 (null).

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

Hinweise

Rufen Sie diese Methode nicht in DllMain auf.

Hinweis

Ein Handle, das durch einen Aufruf von OpenPrinter für einen Remotedrucker ermittelt wurde, greifen über einen lokalen Cache im Druckspoolerdienst auf den Drucker zu. Dieser Cache ist nicht in Echtzeit präzise. Um genaue Daten zu erhalten, ersetzen Sie den OpenPrinter-Aufruf durch OpenPrinter2 durch pOptions.dwFlags, der auf PRINTER _ OPTION NO CACHE festgelegt _ _ ist. Beachten Sie, dass nur OpenPrinter2W funktionsfähig ist. Die Funktion gibt ein Druckerhand handle zurück, das andere Druck-API-Aufrufe verwendet und den lokalen Cache umgeht. Diese Methode blockiert, während auf die Netzwerkkommunikation mit dem Remotedrucker gewartet wird, sodass sie möglicherweise nicht sofort zurückkehrt. Wie schnell diese Funktion zurückgegeben wird, hängt von Laufzeitfaktoren wie Netzwerkstatus, Druckerserverkonfiguration und Implementierungsfaktoren des Druckertreibers ab, die beim Schreiben einer Anwendung schwer vorherzusagen sind. Wenn Sie diese Funktion aus einem Thread aufrufen, der die Interaktion mit der Benutzeroberfläche verwaltet, reagiert die Anwendung möglicherweise nicht mehr.

Hinweis

Ein Handle, das durch einen Aufruf von OpenPrinter für einen Remotedrucker ermittelt wird, wird über einen lokalen Cache im Druckspoolerdienst auf den Drucker zugreifen. Dieser Cache ist entwurfsweise nicht in Echtzeit genau. Wenn Sie genaue Daten abrufen müssen, ersetzen Sie den OpenPrinter-Aufruf durch OpenPrinter2 durch pOptions.dwFlags, der auf PRINTER OPTION NO CACHE festgelegt _ _ _ ist. Beachten Sie, dass nur OpenPrinter2W funktionsfähig ist. Dadurch gibt die Funktion einen Druckerhandpunkt zurück, der andere Druck-API-Aufrufe zum Umgehen des lokalen Caches vorgibt. Beachten Sie, dass dieser Ansatz blockiert wird, während auf die Roundtrip-Netzwerkkommunikation mit dem Remotedrucker gewartet wird, sodass er möglicherweise nicht sofort zurückkehrt. Wie schnell diese Funktion zurückgegeben wird, hängt von Laufzeitfaktoren wie Netzwerkstatus, Druckerserverkonfiguration und Druckertreiberimplementierung ab– Faktoren, die beim Schreiben einer Anwendung schwer vorherzusagen sind. Daher kann das Aufrufen dieser Funktion aus einem Thread, der die Interaktion mit der Benutzeroberfläche verwaltet, dazu kommen, dass die Anwendung nicht reagiert.

Das Handle, auf das phPrinter zeigt, ist nicht threadsicher. Wenn Aufrufer sie gleichzeitig auf mehreren Threads verwenden müssen, müssen sie mithilfe der Synchronisierungsfunktionen benutzerdefinierten Synchronisierungszugriff auf das Druckerhandler bereitstellen. Um zu vermeiden, dass benutzerdefinierter Code geschrieben wird, kann die Anwendung bei Bedarf ein Druckerhand handle für jeden Thread öffnen.

Mit dem Parameter pDefault können Sie den Datentyp und die Gerätemoduswerte angeben, die zum Drucken von Dokumenten verwendet werden, die von der StartDocPrinter-Funktion übermittelt werden. Sie können diese Werte jedoch mithilfe der SetJob-Funktion überschreiben, nachdem ein Dokument gestartet wurde.

Die DEVMODE-Einstellungen, die in der PRINTER _ DEFAULTS-Struktur des pDefault-Parameters definiert sind, werden nicht verwendet, wenn der Wert des pDatatype-Members der DOC INFO _ _ 1-Struktur, der im pDocInfo-Parameter des StartDocPrinter-Aufrufs übergeben wurde, "RAW" ist. Wenn ein Dokument auf hoher Ebene (z. B. eine Adobe PDF- oder Microsoft Word-Datei) oder andere Druckerdaten (z. B. PCL, PS oder HPGL) direkt an einen Drucker gesendet werden, bei dem pDatatype auf "RAW" festgelegt ist, muss das Dokument die DevMODE-Druckauftragseinstellungen in der sprache, die von der Hardware verstanden wird, vollständig beschreiben.

Sie können die OpenPrinter-Funktion aufrufen, um ein Handle für einen Druckerserver zu öffnen oder um die Zugriffsrechte zu bestimmen, die ein Client für einen Druckerserver hat. Geben Sie dazu den Namen des Druckerservers im Parameter pPrinterName an, legen Sie die Member pDatatype und pDevMode der PRINTER _ DEFAULTS-Struktur auf NULL fest, und legen Sie den DesiredAccess-Member so fest, dass ein Serverzugriffsmaskenwert wie SERVER ALL ACCESS angegeben _ _ wird. Wenn Sie mit dem Handle fertig sind, übergeben Sie es an die ClosePrinter-Funktion, um es zu schließen.

Verwenden Sie das DesiredAccess-Mitglied der PRINTER _ DEFAULTS-Struktur, um die Zugriffsrechte anzugeben, die Sie für den Drucker benötigen. Die Zugriffsrechte können wie folgt sein. (Wenn pDefault NULL ist, sind die Zugriffsrechte PRINTER. _ ACCESS _ USE.)

Gewünschter Zugriffswert Bedeutung
_ _ DRUCKERZUGRIFFSVERWALTUNG So führen Sie administrative Aufgaben aus, z. B. die von SetPrinter bereitgestellten.
_ _ DRUCKERZUGRIFFSNUTZUNG So führen Sie grundlegende Druckvorgänge aus.
DRUCKERZUGRIFF _ _ AUF ALLE So führen Sie alle administrativen Aufgaben und grundlegenden Druckvorgänge mit Ausnahme von SYNCHRONIZE aus (siehe Standardzugriffsrechte.
DRUCKERZUGRIFF _ _ VERWALTEN _ EINGESCHRÄNKT So führen Sie administrative Aufgaben aus, z. B. die von SetPrinter und SetPrinterData bereitgestellten. Dieser Wert ist ab dem Windows 8.1.
Generische Sicherheitswerte, z. B. WRITE _ DAC So lassen Sie bestimmte Zugriffsberechtigungen für die Steuerung zu. Weitere Informationen finden Sie unter Standardzugriffsrechte.

Wenn ein Benutzer nicht über die Berechtigung verfügt, einen angegebenen Drucker oder Druckerserver mit dem gewünschten Zugriff zu öffnen, tritt beim OpenPrinter-Aufruf ein Fehler mit dem Rückgabewert 0 auf, und GetLastError gibt den Wert ERROR _ ACCESS _ DENIED zurück.

Beispiele

Ein Beispielprogramm, das diese Funktion verwendet, finden Sie unter How To: Print Using the GDI Print API (How To: Drucken mithilfe der GDI-Druck-API).

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 (include Windows.h)
Bibliothek
Winspool.lib
DLL
Winspool.drv
Unicode- und ANSI-Name
OpenPrinterW (Unicode) und OpenPrinterA (ANSI)

Siehe auch

Drucken

Druckspooler-API-Funktionen

WritePrinter

ClosePrinter

_DRUCKEREINSTELLUNGEN

SetJob

SetPrinter

StartDocPrinter