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 |
|
| Bibliothek |
|
| DLL |
|
| Unicode- und ANSI-Name |
OpenPrinterW (Unicode) und OpenPrinterA (ANSI) |