OpenPrinter2-Funktion
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 |
|
| Bibliothek |
|
| DLL |
|
| Unicode- und ANSI-Name |
OpenPrinter2W (Unicode) und OpenPrinter2A (ANSI) |