OpenPrinter2-Funktion

Artikel
06/13/2023

Ruft ein Handle für den angegebenen Drucker, Druckserver oder andere Arten von Handles im Drucksubsystem ab, während einige der Druckeroptionen festgelegt werden.

Syntax

BOOL OpenPrinter2(
  _In_  LPCTSTR            pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault,
  _In_  PPRINTER_OPTIONS   pOptions
);

Parameter

pPrinterName [in]

Ein Zeiger auf eine konstante NULL-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.

Windows Vista: Bei NULL wird der lokale Druckserver angegeben.

phPrinter [out]

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

pDefault [in]

Ein Zeiger auf eine PRINTER_DEFAULTS-Struktur . Dieser Wert kann NULL sein.

pOptions [in]

Ein Zeiger auf eine PRINTER_OPTIONS Struktur. Dieser Wert kann NULL sein.

Rückgabewert

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

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

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.

Die ANSI-Version dieser Funktion ist nicht implementiert und gibt ERROR_NOT_SUPPORTED zurück.

Mit dem pDefault-Parameter 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 überschreiben, indem Sie die SetJob-Funktion verwenden, nachdem ein Dokument gestartet wurde.

Sie können die OpenPrinter2-Funktion aufrufen, um ein Handle für einen Druckserver zu öffnen oder Clientzugriffsrechte für einen Druckserver zu bestimmen. 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 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-Element der PRINTER_DEFAULTS-Struktur , um die erforderlichen Zugriffsrechte anzugeben. Die Zugriffsrechte können eine der folgenden sein.

Gewünschter Zugriffswert	Bedeutung
PRINTER_ACCESS_ADMINISTER	Zum Ausführen von Verwaltungsaufgaben, z. B. die von SetPrinter bereitgestellten.
PRINTER_ACCESS_USE	So führen Sie grundlegende Druckvorgänge aus.
PRINTER_ALL_ACCESS	So führen Sie alle verwaltungstechnischen Aufgaben und grundlegenden Druckvorgänge mit Ausnahme von SYNCHRONIZE aus. Siehe Standardzugriffsrechte.
PRINTER_ACCESS_MANAGE_LIMITED	Zum Ausführen von Verwaltungsaufgaben, z. B. von SetPrinter und SetPrinterData. Dieser Wert ist ab Windows 8.1 verfügbar.
generische Sicherheitswerte, z. B. WRITE_DAC	Um bestimmte Kontrollzugriffsrechte 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 OpenPrinter2-Aufruf fehl, und GetLastError gibt den Wert ERROR_ACCESS_DENIED zurück.

Wenn pPrinterName ein lokaler Drucker ist, ignoriert OpenPrinter2 alle Werte der dwFlags , auf die die PRINTER_OPTIONS Struktur mithilfe von pOptions verweist, mit Ausnahme von PRINTER_OPTION_CLIENT_CHANGE. Wenn letzteres übergeben wird, gibt OpenPrinter2 ERROR_ACCESS_DENIED zurück. Entsprechend bietet OpenPrinter2 beim Öffnen eines lokalen Druckers keinen Vorteil gegenüber OpenPrinter.

Windows Vista: Die von OpenPrinter2 zurückgegebenen Druckerdaten werden aus einem lokalen Cache abgerufen, es sei denn, das PRINTER_OPTION_NO_CACHE-Flag wird im Feld dwFlags der PRINTER_OPTIONS Struktur festgelegt, auf die von pOptions verwiesen wird.

Beispiele

In diesem Beispiel schlägt OpenPrinter2 fehl, wenn PRINTER_ACCESS_MANAGE_LIMITED an die PRINTER_DEFAULTS-Struktur übergeben wird und der Benutzer nicht über die entsprechende Berechtigung verfügt.

// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;

// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
                     &printer,                  // Printer handle
                     &defaults,                 // Printer defaults
                     nullptr));                 // Printer options

assert(GetLastError() == ERROR_ACCESS_DENIED);

if (printer)
{
    ClosePrinter(printer);
}

Ein Beispielprogramm zur Verwendung dieser Funktion finden Sie unter Vorgehensweise: Drucken mithilfe der GDI-Druck-API.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Header	Winspool.h (einschließlich Windows.h)
Bibliothek	Winspool.lib
DLL	Spoolss.dll
Unicode- und ANSI-Name	OpenPrinter2W (Unicode) und OpenPrinter2A (ANSI)

Siehe auch

Drucken
Druckspooler-API-Funktionen
ClosePrinter
PRINTER_DEFAULTS
PRINTER_OPTIONS
SetJob
SetPrinter
StartDocPrinter
OpenPrinter

Share via