StartXpsPrintJob-Funktion (xpsprint.h)
[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.
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 |
|---|---|
|
Drucken Sie die Seite nicht. |
|
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 |
|---|---|
|
Die Methode wurde erfolgreich ausgeführt. |
|
printerName oder documentStream ist NULL. |
|
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.
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 |