Funzione StartXpsPrintJob (xpsprint.h)
[StartXpsPrintJob non è supportato e potrebbe essere modificato o non disponibile in futuro. ]
Avvia la stampa di un flusso di documenti XPS in una stampante.
Sintassi
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
);
Parametri
[in] printerName
Nome della stampante con cui verrà associato questo processo.
[in] jobName
Nome del processo specificato dall'utente da associare a questo processo. Se il processo non richiede un nome distinto, specificato dall'utente, questo parametro può essere impostato su NULL.
[in] outputFileName
Nome file del file o della porta in cui deve essere reindirizzato l'output di questo processo. Se si imposta questo valore, l'output del processo di stampa verrà indirizzato al file o alla porta specificata. Per inviare il processo di stampa alla stampante specificata da printerName, questo parametro deve essere impostato su NULL.
[in] progressEvent
Handle eventi segnalato quando si verificano le modifiche del processo di stampa seguenti:
- Un ID processo viene assegnato al processo di stampa
- La stampa di una pagina è stata completata
- La stampa di un documento è stata completata
- Il processo di stampa è stato annullato o è stato terminato a causa di un errore
L'API di stampa XPS non reimposta questo evento, ovvero la responsabilità del chiamante.
Se non è necessaria alcuna notifica di stato, questo parametro può essere impostato su NULL.
[in] completionEvent
Handle eventi segnalato al termine del processo di stampa. Questo evento è garantito che venga segnalato esattamente una volta per chiamata StartXpsPrintJob . L'API di stampa XPS non reimposta questo evento, ovvero la responsabilità del chiamante.
Se non è necessaria alcuna notifica di completamento, questo parametro può essere impostato su NULL.
[in] printablePagesOn
Il parametro fa riferimento a una matrice UINT8 i cui elementi specificano un subset di pagine di un documento da stampare. Come illustrato nella tabella seguente, il valore di ogni elemento indica se la pagina deve essere stampata.
| Valore dell'elemento Array | Significato |
|---|---|
|
Non stampare la pagina. |
|
Stampare la pagina. |
Gli eventi di avanzamento verranno segnalati solo per le pagine designate per la stampa.
Gli elementi nella matrice rappresentano tutte le pagine designate per la stampa, in tutti i documenti del pacchetto XPS. Ad esempio, se il pacchetto contiene due documenti con tre pagine, la matrice illustrata nella tabella seguente designa la stampa di pagine 0 e 2 dal documento 1 e le pagine 0 e 2 dal documento 2.
| Indice degli elementi | Valore elemento | Stampare? | Numero documento | Numero di pagina |
|---|---|---|---|---|
| 5 | 1 | Sì | 2 | 2 |
| 4 | 0 | No | 2 | 1 |
| 3 | 1 | Sì | 2 | 0 |
| 2 | 1 | Sì | 1 | 2 |
| 1 | 0 | No | 1 | 1 |
| 0 | 1 | Sì | 1 | 0 |
Se printablePagesOn è NULL, verranno stampate tutte le pagine del pacchetto.
Se printablePagesOn ha più elementi di quanto ci siano pagine nel pacchetto, gli elementi superflui verranno ignorati.
Se la matrice ha meno elementi rispetto a quelle presenti nel documento, il valore dell'ultimo elemento matrice della matrice viene applicato alle pagine rimanenti. Questa regola semplifica la specifica di un intervallo aperto o che ottiene solo alcune pagine di un documento di grandi dimensioni stampato.
[in] printablePagesOnCount
Numero di elementi nella matrice a cui fa riferimento printablePagesOn. Se printablePagesOn è NULL, questo parametro viene ignorato.
[out] xpsPrintJob
Puntatore all'interfaccia IXpsPrintJob che rappresenta il processo di stampa creato da StartXpsPrintJob. Per ottenere lo stato del processo di stampa o annullarlo, usare l'interfaccia IXpsPrintJob . Se non è necessario un oggetto IXpsPrintJob , questo parametro può essere impostato su NULL.
[out] documentStream
Puntatore all'interfaccia IXpsPrintJobStream in cui il chiamante scrive il documento XPS da stampare da questo processo di stampa.
[out] printTicketStream
Puntatore all'interfaccia IXpsPrintJobStream usata dal chiamante per scrivere il ticket di stampa a livello di processo associato a questo processo. Se questo parametro è impostato su NULL, verranno usati i ticket di stampa (se presenti) dal documento XPS scritto in documentStream .
Valore restituito
Il metodo restituisce un HRESULT. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente.
| Codice restituito | Descrizione |
|---|---|
|
Il metodo è riuscito. |
|
printerName o documentStream è NULL. |
|
Memoria insufficiente per creare un nuovo oggetto IXpsPrintJob . |
Commenti
StartXpsPrintJob è una funzione asincrona, che può restituire prima che lo spooler di stampa crei o avvia un processo di stampa.
Le interfacce restituite in xpsPrintJob, documentStream e printTicketStream non devono essere usate finché StartXpsPrintJob non viene restituito correttamente.
Dopo l'avvio dell'invio dei dati, il chiamante deve monitorare gli eventi di stato segnalati all'evento passato in progressEvent. Quando l'evento viene segnalato, il chiamante deve chiamare IXpsPrintJob::GetJobStatus per ottenere lo stato corrente del processo di stampa.
Al termine del processo di stampa, indipendentemente dal fatto che l'evento passato in completionEvent venga segnalato una sola volta e una sola volta. Per evitare la perdita di dati, il chiamante deve monitorare questo evento e il thread o l'applicazione del chiamante non deve essere terminato finché l'evento non è stato segnalato.
Gli stati del processo non sono né archiviati né accodati dallo spooler di stampa. Poiché l'elaborazione del processo non attende che lo stato venga letto dopo la segnalazione degli eventi, il chiamante potrebbe perdere alcune modifiche di stato, a seconda del ritardo tra il momento in cui l'applicazione ha ricevuto la notifica di modifica e l'ora in cui ha chiamato IXpsPrintJob::GetJobStatus. Per ricevere notifiche successive, l'applicazione deve reimpostare l'evento di stato dopo la ricezione della notifica.
Se una chiamata a StartXpsPrintJob ha esito negativo, lo stato del processo verrà aggiornato, gli eventi di completamento e stato verranno segnalato e verrà restituito un codice di errore. Per ottenere lo stato del processo di stampa non riuscito, chiamare IXpsPrintJob::GetJobStatus.
StartXpsPrintJob chiama DuplicateHandle in completionEvent e progressEvent per assicurarsi che rimangano validi per la durata del processo. Poiché lo spooler di stampa usa un handle duplicato per gli eventi, è possibile che il chiamante chiuda questi handle in qualsiasi momento senza influire sull'esecuzione del processo. La procedura consigliata, tuttavia, è che il chiamante chiuda questi handle solo dopo che l'evento completionEvent è stato segnalato e osservato dal chiamante.
Le interfacce IXpsPrintJobStream restituite in documentStream e printTicketStream sono flussi di sola scrittura che non consentono la ricerca, ma che possono essere chiusi. Il chiamante scrive il contenuto del documento XPS e del ticket di stampa in questi flussi e quindi chiama Chiudi dopo la scrittura di tutti i dati. Le chiamate al metodo Write dei flussi sono thread-safe; Tuttavia, se tali chiamate vengono effettuate da thread diversi, non è garantito che venga eseguito il commit nel flusso nell'ordine previsto.
Requisiti
| Client minimo supportato | Windows 7 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | xpsprint.h |
| Libreria | XpsPrint.lib |
| DLL | XpsPrint.dll |
Vedi anche
Documents (Documenti)