StartXpsPrintJob1-Funktion (xpsprint.h)

Artikel
08/28/2023

[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.

Hinweis Dieses Ereignis wird erst signalisiert, nachdem die Anwendung mit dem Senden von Daten an den Druckauftrag begonnen hat.

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
S_OK	Die Methode wurde erfolgreich ausgeführt.
E_POINTER	printerName oder xpsOMPackageTarget ist NULL.
E_OUTOFMEMORY	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.

Hinweis Wenn Ihre Anwendung in eine Datei ausgibt, ist die Anwendung dafür verantwortlich, den Wert bereitzustellen, der im outputFileName-Parameter für Druck-in-Datei-Vorgänge übergeben werden soll. Um auf einem Drucker zu drucken, der einen Treiber verwendet, der an den FILE:-Port ausgibt, muss der Aufrufer den Dateinamen vom Benutzer abrufen, indem das Dialogfeld allgemeine Datei angezeigt wird.

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

Siehe auch

Dokumente

IXpsOMPackageTarget

IXpsOMPackageWriter

XML Paper Specification

Freigeben über