OpenPrinter-Funktion

Die OpenPrinter-Funktion ruft ein Handle an den angegebenen Drucker oder Druckserver oder andere Arten von Handles im Drucksubsystem ab.

Syntax

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

Parameter

pPrinterName [in]

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des Druckers oder Druckservers, 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 NULL, gibt er den lokalen Druckerserver an.

phPrinter [out]

Ein Zeiger auf eine Variable, die ein Handle (nicht threadsicher) auf das geöffnete Drucker- oder Druckserverobjekt empfängt.

Der parameter phPrinter kann ein Xcv-Handle zur 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 null.

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

Bemerkungen

Rufen Sie diese Methode nicht in DllMain auf.

Hinweis

Ein Handle, das für einen Remotedrucker durch einen Aufruf von OpenPrinter für einen Remotedrucker abgerufen wird, greift über einen lokalen Cache im Druckspoolerdienst auf den Drucker zu. Dieser Cache ist nicht in Echtzeit genau. 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 Druckerhandle zurück, das andere Druck-API-Aufrufe verwendet, und umgeht den lokalen Cache. Diese Methode blockiert das Warten auf die Netzwerkkommunikation mit dem Remotedrucker, sodass sie möglicherweise nicht sofort zurückgegeben wird. 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 aus einem Thread aufrufen, der benutzeroberflächeninteraktionen verwaltet, reagiert die Anwendung möglicherweise nicht mehr.

Hinweis

Ein Handle, das durch einen Aufruf von OpenPrinter für einen Remotedrucker abgerufen wird, greift über einen lokalen Cache im Druckspoolerdienst auf den Drucker zu. Dieser Cache ist standardmäßig 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. Auf diese Weise gibt die Funktion ein Druckerhandle zurück, das andere Druck-API-Aufrufe durchführt, um den lokalen Cache zu umgehen. Beachten Sie, dass dieser Ansatz während des Wartens auf die Roundtrip-Netzwerkkommunikation mit dem Remotedrucker blockiert wird, sodass er möglicherweise nicht sofort zurückgegeben wird. Wie schnell diese Funktion zurückgibt, hängt von Laufzeitfaktoren wie Netzwerk-status, Druckerserverkonfiguration und Druckertreiberimplementierung ab. Faktoren, die beim Schreiben einer Anwendung schwer vorhergesagt werden können. Daher könnte das Aufrufen dieser Funktion aus einem Thread, der die Interaktion mit der Benutzeroberfläche verwaltet, dazu führen, dass die Anwendung nicht mehr reagiert.

Das Handle, auf das von phPrinter verwiesen wird, ist nicht threadsicher. Wenn Aufrufer es gleichzeitig für mehrere Threads verwenden müssen, müssen sie mithilfe der Synchronisierungsfunktionen einen benutzerdefinierten Synchronisierungszugriff auf das Druckerhandle bereitstellen. Um das Schreiben von benutzerdefiniertem Code zu vermeiden, kann die Anwendung bei Bedarf ein Druckerhandle für jeden Thread öffnen.

Mit dem pDefault-Parameter können Sie die Werte des Datentyps und des Gerätemodus angeben, die zum Drucken von Dokumenten verwendet werden, die von der StartDocPrinter-Funktion übermittelt werden. Sie können diese Werte jedoch überschreiben, indem Sie die SetJob-Funktion verwenden, 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-Elements der DOC_INFO_1-Struktur , der im pDocInfo-Parameter des StartDocPrinter-Aufrufs übergeben wurde, "RAW" lautet. Wenn ein allgemeines Dokument (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 Druckauftragseinstellungen im DEVMODE-Stil vollständig in der sprache beschreiben, die von der Hardware verstanden wird.

Sie können die OpenPrinter-Funktion aufrufen, um ein Handle für einen Druckserver zu öffnen oder die Zugriffsrechte zu bestimmen, die ein Client für einen Druckserver hat. Geben Sie hierzu den Namen des Druckservers im pPrinterName-Parameter an, legen Sie die pDatatype - und pDevMode-Member der PRINTER_DEFAULTS-Struktur auf NULL fest, und legen Sie das DesiredAccess-Element fest, um einen Serverzugriffsmaskenwert wie SERVER_ALL_ACCESS anzugeben. Wenn Sie mit dem Handle fertig sind, übergeben Sie es an die ClosePrinter-Funktion , um es zu schließen.

Verwenden Sie den DesiredAccess-Member der PRINTER_DEFAULTS-Struktur , um die Zugriffsrechte anzugeben, die Sie für den Drucker benötigen. Die Zugriffsrechte können eines der folgenden sein. (Wenn pDefaultNULL ist, werden die Zugriffsrechte PRINTER_ACCESS_USE.)

Gewünschter Zugriffswert Bedeutung
PRINTER_ACCESS_ADMINISTER Zum Ausführen von verwaltungstechnischen Aufgaben, z. B. von SetPrinter.
PRINTER_ACCESS_USE Zum Ausführen grundlegender Druckvorgänge.
PRINTER_ALL_ACCESS So führen Sie alle administrativen Aufgaben und grundlegenden Druckvorgänge mit Ausnahme von SYNCHRONIZE aus (siehe Standardzugriffsrechte.
PRINTER_ACCESS_MANAGE_LIMITED Zum Ausführen von verwaltungstechnischen Aufgaben, z. B. von SetPrinter und SetPrinterData. Dieser Wert ist ab Windows 8.1 verfügbar.
generische Sicherheitswerte, z. B. WRITE_DAC Um bestimmte Zugriffsberechtigungen für die Steuerung zuzulassen. Siehe Standardzugriffsrechte.

Wenn ein Benutzer nicht über die Berechtigung zum Öffnen eines angegebenen Druckers oder Druckservers mit dem gewünschten Zugriff verfügt, schlägt der OpenPrinter-Aufruf mit dem Rückgabewert null fehl, und GetLastError gibt den Wert ERROR_ACCESS_DENIED zurück.

Beispiele

Ein Beispielprogramm, das diese Funktion verwendet, finden Sie unter Vorgehensweise: 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 (Einschließen von 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

PRINTER_DEFAULTS

SetJob

SetPrinter

StartDocPrinter