Share via

StartXpsPrintJob-Funktion (xpsprint.h)

  • Artikel

[StartXpsPrintJob wird nicht unterstützt und kann in Zukunft geändert oder nicht mehr verfügbar sein. ]

Startet das Drucken eines XPS-Dokumentstreams auf einem Drucker.

Syntax

HRESULT StartXpsPrintJob(
  [in]  LPCWSTR            printerName,
  [in]  LPCWSTR            jobName,
  [in]  LPCWSTR            outputFileName,
  [in]  HANDLE             progressEvent,
  [in]  HANDLE             completionEvent,
  [in]  UINT8              *printablePagesOn,
  [in]  UINT32             printablePagesOnCount,
  [out] IXpsPrintJob       **xpsPrintJob,
  [out] IXpsPrintJobStream **documentStream,
  [out] IXpsPrintJobStream **printTicketStream
);

Parameter

[in] printerName

Der Name des Druckers, dem dieser Auftrag zugeordnet wird.

[in] jobName

Ein benutzerdefinierter Auftragsname, der diesem Auftrag zugeordnet werden soll. Wenn der Auftrag keinen separaten, benutzerdefinierten Namen erfordert, kann dieser Parameter auf NULL festgelegt werden.

[in] 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 Drucker zu senden, der von printerName angegeben wird, muss dieser Parameter auf NULL festgelegt werden.

[in] progressEvent

Ein Ereignishandle, das signalisiert wird, wenn die folgenden Druckauftragsänderungen auftreten:

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

Wenn keine Statusbenachrichtigung erforderlich ist, kann dieser Parameter auf NULL festgelegt werden.

[in] completionEvent

Ein Ereignishandle, das beim Abschluss des Druckauftrags signalisiert wird. Dieses Ereignis wird garantiert genau einmal pro StartXpsPrintJob-Aufruf signalisiert. Die XPS-Druck-API setzt dieses Ereignis nicht zurück. Dies liegt in der Verantwortung des Aufrufers.

Wenn keine Vervollständigungsbenachrichtigung erforderlich ist, kann dieser Parameter auf NULL festgelegt werden.

[in] printablePagesOn

Der Parameter verweist auf ein UINT8-Array, dessen Elemente eine Teilmenge der zu druckenden Seiten eines Dokuments angeben. Wie in der folgenden Tabelle gezeigt, gibt der Wert jedes Elements an, ob die Seite gedruckt werden soll.

Arrayelementwert Bedeutung
0
 Drucken Sie die Seite nicht.
Nicht Null
 Drucken Sie die Seite.
 

Fortschrittsereignisse werden nur für die Seiten signalisiert, die zum Drucken bestimmt sind.

Die Elemente im Array stellen alle Seiten dar, die für den Druck in allen Dokumenten des XPS-Pakets vorgesehen sind. Wenn das Paket beispielsweise zwei Dokumente mit jeweils drei Seiten enthält, bestimmt das in der folgenden Tabelle dargestellte Array den Druck der Seiten 0 und 2 aus Dokument 1 sowie der Seiten 0 und 2 aus Dokument 2.

Elementindex Elementwert Drucken? Dokumentnummer Seitenzahl
5 1 Ja 2 2
4 0 Nein 2 1
3 1 Ja 2 0
2 1 Ja 1 2
1 0 Nein 1 1
0 1 Ja 1 0
 

Wenn printablePagesOnNULL ist, werden alle Seiten im Paket gedruckt.

Wenn printablePagesOn mehr Elemente enthält, als Seiten im Paket vorhanden sind, werden die überflüssigen Elemente ignoriert.

Wenn das Array über weniger Elemente verfügt, als Seiten im Dokument vorhanden sind, wird der Wert des letzten Arrayelements des Arrays auf die restlichen Seiten angewendet. Diese Regel erleichtert die Angabe eines Bereichs, der offen ist oder nur wenige Seiten eines großen Dokuments gedruckt wird.

[in] printablePagesOnCount

Die Anzahl der Elemente im Array, auf die von printablePagesOn verwiesen wird. Wenn printablePagesOnNULL ist, wird dieser Parameter ignoriert.

[out] xpsPrintJob

Ein Zeiger auf die IXpsPrintJob-Schnittstelle , die den von StartXpsPrintJob erstellten Druckauftrag darstellt. Verwenden Sie die IXpsPrintJob-Schnittstelle, um die status des Druckauftrags abzurufen oder ihn abzubrechen. Wenn kein IXpsPrintJob erforderlich ist, kann dieser Parameter auf NULL festgelegt werden.

[out] documentStream

Ein Zeiger auf die IXpsPrintJobStream-Schnittstelle , in die der Aufrufer das XPS-Dokument schreibt, das von diesem Druckauftrag gedruckt werden soll.

[out] printTicketStream

Ein Zeiger auf die IXpsPrintJobStream-Schnittstelle , die vom Aufrufer verwendet wird, um das Druckticket auf Auftragsebene zu schreiben, das diesem Auftrag zugeordnet wird. Wenn dieser Parameter auf NULL festgelegt ist, werden die Drucktickets (sofern vorhanden) aus dem XPS-Dokument verwendet, das in documentStream geschrieben wird.

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 documentStream ist NULL.
E_OUTOFMEMORY
 Nicht genügend Arbeitsspeicher, um ein neues IXpsPrintJob-Objekt zu erstellen.

Hinweise

StartXpsPrintJob ist eine asynchrone Funktion, die zurückgegeben werden kann, bevor der Druckspooler einen Druckauftrag erstellt oder startet.

Die in xpsPrintJob, documentStream und printTicketStream zurückgegebenen Schnittstellen dürfen erst verwendet werden, wenn StartXpsPrintJob erfolgreich zurückgegeben wurde.

Nachdem der Aufrufer mit dem Senden von Daten begonnen hat, sollte er die Fortschrittsereignisse ü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, einmal und nur einmal signalisiert. Um Datenverluste zu verhindern, sollte der Aufrufer dieses Ereignis überwachen, und der Thread oder die Anwendung des Aufrufers sollte erst beendet werden, wenn das Ereignis 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 StartXpsPrintJob fehlschlägt, wird der Auftrag status aktualisiert, die Vervollständigungs- und Fortschrittsereignisse werden signalisiert, und ein Fehlercode wird zurückgegeben. Um die status des fehlerhaften Druckauftrags abzurufen, rufen Sie IXpsPrintJob::GetJobStatus auf.

StartXpsPrintJob 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, ist es für den Aufrufer möglich, diese Handles jederzeit zu schließen, ohne die Auftragsausführung zu beeinträchtigen. Die empfohlene Prozedur besteht jedoch darin, dass der Aufrufer diese Handles erst schließt, nachdem das ereignis completionEvent signalisiert und vom Aufrufer beobachtet wurde.

Die IXpsPrintJobStream-Schnittstellen , die in documentStream und printTicketStream zurückgegeben werden, sind schreibgeschützte Datenströme, die keine Suche zulassen, aber geschlossen werden können. Der Aufrufer schreibt das XPS-Dokument und druckt Ticketinhalte in diese Streams und ruft dann Schließen auf, nachdem alle Daten geschrieben wurden. Aufrufe der Write-Methode von Streams sind threadsicher. Wenn solche Aufrufe jedoch von verschiedenen Threads erfolgen, wird nicht garantiert, dass sie in der erwarteten Reihenfolge an den Stream gebunden werden.

Hinweis Beim Drucken in eine Datei ist die Anwendung dafür verantwortlich, den Wert bereitzustellen, der im outputFileName-Parameter für Druck-in-Datei-Vorgänge übergeben wird. 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 er das Dialogfeld "Allgemeine Datei" anzeigt.
 

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile xpsprint.h
Bibliothek XpsPrint.lib
DLL XpsPrint.dll

Siehe auch

Dokumente

StartXpsPrintJob1

XML Paper Specification