StartXpsPrintJob1-Funktion (xpsprint.h)
[StartXpsPrintJob1 wird nicht unterstützt und kann in Zukunft geändert oder nicht mehr verfügbar sein. ]
Erstellt einen Druckauftrag zum Senden von XPS-Dokumentinhalten an einen Drucker. Diese Funktion erstellt einen effizienteren Druckpfad als StartXpsPrintJob.
Syntax
HRESULT StartXpsPrintJob1(
[in] LPCWSTR printerName,
[in, optional] LPCWSTR jobName,
[in, optional] LPCWSTR outputFileName,
[in, optional] HANDLE progressEvent,
[in, optional] HANDLE completionEvent,
[out, optional] IXpsPrintJob **xpsPrintJob,
[out] IXpsOMPackageTarget **printContentReceiver
);
Parameter
[in] printerName
Der Name des Druckers, dem dieser Auftrag zugeordnet wird.
[in, optional] jobName
Ein benutzerdefinierter Auftragsname, der diesem Auftrag zugeordnet werden soll. Sie können diesen Parameter auf NULL festlegen, wenn der Auftrag keinen separaten, benutzerdefinierten Namen erfordert.
[in, optional] outputFileName
Der Dateiname der Datei oder des Ports, an die die Ausgabe dieses Auftrags umgeleitet werden soll. Wenn Sie diesen Wert festlegen, wird die Ausgabe des Druckauftrags an die angegebene Datei oder den angegebenen Port weitergeleitet. Um den Druckauftrag an den druckername angegebenen Drucker zu senden, müssen Sie diesen Parameter auf NULL festlegen.
[in, optional] progressEvent
Ein Ereignishandle, das signalisiert wird, wenn eine der folgenden Druckauftragsänderungen erfolgt:
- Dem Druckauftrag wird eine Auftrags-ID zugewiesen.
- Der Druck einer Seite ist abgeschlossen
- Der Druck eines Dokuments ist abgeschlossen
- Der Druckauftrag wurde abgebrochen oder aufgrund eines Fehlers beendet.
Die XPS-Druck-API setzt dieses Ereignis nicht zurück. Dies liegt in der Verantwortung des Aufrufers.
Legen Sie diesen Parameter auf NULL fest, wenn Sie nicht über den Fortschritt benachrichtigt werden möchten.
[in, optional] completionEvent
Ein Ereignishandle, das beim Abschluss des Druckauftrags signalisiert wird. Dieses Ereignis wird garantiert genau einmal pro StartXpsPrintJob1-Aufruf signalisiert. Die XPS-Druck-API setzt dieses Ereignis nicht zurück. Dies liegt in der Verantwortung des Aufrufers.
Legen Sie diesen Parameter auf NULL fest, wenn sie nicht über die Vervollständigung benachrichtigt werden möchten.
[out, optional] xpsPrintJob
Ein Zeiger auf die IXpsPrintJob-Schnittstelle , die den von StartXpsPrintJob1 erstellten Druckauftrag darstellt. Verwenden Sie die IXpsPrintJob-Schnittstelle, um die status des Druckauftrags abzurufen oder ihn abzubrechen. Legen Sie diesen Parameter auf NULL fest, wenn Sie ihn nicht benötigen.
[out] printContentReceiver
Ein Zeiger auf die IXpsOMPackageTarget-Schnittstelle , die von dieser Funktion erstellt wurde. Dieser Parameter ist erforderlich, und Sie können ihn nicht auf NULL festlegen.
Um Dokumentinhalte an den von dieser Funktion erstellten Druckauftrag zu senden, verwenden Sie die IXpsOMPackageWriter-Schnittstelle, die Sie erstellen, indem Sie die CreateXpsOMPackageWriter-Methode der in xpsOMPackageTarget zurückgegebenenIXpsOMPackageTarget-Schnittstelle aufrufen.
Rückgabewert
Die Methode gibt ein HRESULT zurück. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Die Methode wurde erfolgreich ausgeführt. |
|
printerName oder xpsOMPackageTarget ist NULL. |
|
Nicht genügend Arbeitsspeicher, um ein neues IXpsPrintJob-Objekt zu erstellen. |
Hinweise
StartXpsPrintJob1 ist eine asynchrone Funktion und kann daher zurückgegeben werden, bevor der Druckspooler einen Druckauftrag erstellt oder startet.
Verwenden Sie die Schnittstellen, die in xpsPrintJob und xpsOMPackageTarget zurückgegeben werden, erst dann, wenn StartXpsPrintJob1 erfolgreich zurückgegeben wurde.
Nachdem der Aufrufer mit dem Senden von Daten begonnen hat, empfiehlt es sich, die Fortschrittsereignisse zu überwachen, die dem Ereignis signalisiert werden, das in progressEvent übergeben wird. Wenn das Ereignis signalisiert wird, muss der Aufrufer IXpsPrintJob::GetJobStatus aufrufen, um den aktuellen status des Druckauftrags abzurufen.
Wenn der Druckauftrag erfolgreich abgeschlossen ist oder nicht, wird das ereignis, das in completionEvent übergeben wird, nur einmal signalisiert. Um Datenverlust zu verhindern, ist es eine gute Programmierpraxis für den Aufrufer, das Vervollständigungsereignis zu überwachen und sicherzustellen, dass weder der Thread noch die Anwendung, die den Druckauftrag erstellt hat, beendet werden, bis das Vervollständigungsereignis signalisiert wurde.
Auftragszustände werden vom Druckspooler weder gespeichert noch in die Warteschlange gestellt. Da die Auftragsverarbeitung nicht darauf wartet, dass der status gelesen wird, nachdem Ereignisse signalisiert wurden, kann der Aufrufer einige Zustandsänderungen verpassen, abhängig von der Verzögerung zwischen dem Zeitpunkt, zu dem die Anwendung die Änderungsbenachrichtigung empfangen hat, und der Zeit, zu der sie IXpsPrintJob::GetJobStatus aufgerufen hat. Um nachfolgende Benachrichtigungen zu erhalten, muss die Anwendung das Statusereignis zurücksetzen, nachdem sie die Benachrichtigung erhalten hat.
Wenn ein Aufruf von StartXpsPrintJob1 fehlschlägt, aktualisiert der Druckspooler den Auftrag status, signalisiert die Vervollständigungs- und Fortschrittsereignisse und gibt einen Fehlercode zurück. Um die status des fehlerhaften Druckauftrags abzurufen, rufen Sie IXpsPrintJob::GetJobStatus auf.
StartXpsPrintJob1 ruft DuplicateHandle bei completionEvent und progressEvent auf, um sicherzustellen, dass sie für die Lebensdauer des Auftrags gültig bleiben. Da der Druckspooler ein dupliziertes Handle für die Ereignisse verwendet, kann der Aufrufer diese Handles jederzeit schließen, ohne die Auftragsausführung zu beeinträchtigen. Es wird jedoch empfohlen, dass der Aufrufer diese Handles erst schließen, nachdem das completionEvent-Ereignis signalisiert wurde und der Aufrufer es beobachtet hat.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 7 mit SP1, Windows Vista und Platform Update Supplement für Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 R2 mit SP1, Windows Server 2008 und Plattformupdate-Ergänzung für Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | xpsprint.h |
| Bibliothek | XpsPrint.lib |
| DLL | XpsPrint.dll |