StartXpsPrintJob, fonction (xpsprint.h)
[StartXpsPrintJob n’est pas pris en charge et peut être modifié ou indisponible à l’avenir. ]
Commence à imprimer un flux de documents XPS sur une imprimante.
Syntaxe
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
);
Paramètres
[in] printerName
Nom de l’imprimante à laquelle ce travail sera associé.
[in] jobName
Nom de travail spécifié par l’utilisateur à associer à ce travail. Si le travail ne nécessite pas de nom distinct spécifié par l’utilisateur, ce paramètre peut être défini sur NULL.
[in] outputFileName
Nom de fichier du fichier ou du port vers lequel la sortie de ce travail doit être redirigée. Si vous définissez cette valeur, la sortie du travail d’impression est dirigée vers le fichier ou le port spécifié. Pour envoyer le travail d’impression à l’imprimante spécifiée par printerName, ce paramètre doit avoir la valeur NULL.
[in] progressEvent
Un handle d’événement qui est signalé lorsque les modifications de travail d’impression suivantes se produisent :
- Un ID de travail est affecté au travail d’impression
- L’impression d’une page est terminée
- L’impression d’un document est terminée
- Le travail d’impression a été annulé ou s’est terminé en raison d’une erreur
L’API d’impression XPS ne réinitialise pas cet événement, c’est-à-dire la responsabilité de l’appelant.
Si aucune notification de progression n’est requise, ce paramètre peut être défini sur NULL.
[in] completionEvent
Handle d’événement qui est signalé à la fin de la tâche d’impression. Cet événement est garanti pour être signalé exactement une fois par appel StartXpsPrintJob . L’API d’impression XPS ne réinitialise pas cet événement, c’est-à-dire la responsabilité de l’appelant.
Si aucune notification d’achèvement n’est requise, ce paramètre peut être défini sur NULL.
[in] printablePagesOn
Le paramètre fait référence à un tableau UINT8 dont les éléments spécifient un sous-ensemble des pages d’un document à imprimer. Comme indiqué dans le tableau suivant, la valeur de chaque élément indique si la page doit être imprimée.
| Valeur de l’élément array | Signification |
|---|---|
|
N’imprimez pas la page. |
|
Imprimez la page. |
Les événements de progression sont signalés uniquement pour les pages qui sont désignées pour l’impression.
Les éléments du tableau représentent toutes les pages qui sont désignées pour l’impression, dans tous les documents du package XPS. Par exemple, si le package contient deux documents de trois pages chacun, le tableau présenté dans le tableau suivant désigne l’impression des pages 0 et 2 à partir du document 1 et des pages 0 et 2 du document 2.
| Index d’élément | Valeur de l’élément | Imprimer? | Numéro du document | Nombre de pages |
|---|---|---|---|---|
| 5 | 1 | Oui | 2 | 2 |
| 4 | 0 | Non | 2 | 1 |
| 3 | 1 | Oui | 2 | 0 |
| 2 | 1 | Oui | 1 | 2 |
| 1 | 0 | Non | 1 | 1 |
| 0 | 1 | Oui | 1 | 0 |
Si printablePagesOn a la valeur NULL, toutes les pages du package seront imprimées.
Si printablePagesOn contient plus d’éléments qu’il n’y a de pages dans le package, les éléments superflus sont ignorés.
Si le tableau contient moins d’éléments qu’il n’y a de pages dans le document, la valeur du dernier élément de tableau du tableau est appliquée aux pages restantes. Cette règle facilite la spécification d’une plage ouverte ou qui n’affiche que quelques pages d’un document volumineux.
[in] printablePagesOnCount
Nombre d’éléments dans le tableau référencé par printablePagesOn. Si printablePagesOn a la valeur NULL, ce paramètre est ignoré.
[out] xpsPrintJob
Pointeur vers l’interface IXpsPrintJob qui représente le travail d’impression créé par StartXpsPrintJob. Pour obtenir le status du travail d’impression ou l’annuler, utilisez l’interface IXpsPrintJob. Si un IXpsPrintJob n’est pas requis, ce paramètre peut être défini sur NULL.
[out] documentStream
Pointeur vers l’interface IXpsPrintJobStream dans laquelle l’appelant écrit le document XPS à imprimer par ce travail d’impression.
[out] printTicketStream
Pointeur vers l’interface IXpsPrintJobStream utilisée par l’appelant pour écrire le ticket d’impression au niveau du travail qui sera associé à ce travail. Si ce paramètre a la valeur NULL, les tickets d’impression (le cas échéant) du document XPS écrit dans documentStream seront utilisés.
Valeur retournée
Cette méthode retourne un code HRESULT. Les valeurs possibles sont notamment celles figurant dans le tableau suivant.
| Code de retour | Description |
|---|---|
|
S_OK |
|
printerName ou documentStream a la valeur NULL. |
|
Mémoire insuffisante pour créer un objet IXpsPrintJob . |
Remarques
StartXpsPrintJob est une fonction asynchrone, qui peut être retournée avant que le spouleur d’impression crée ou démarre un travail d’impression.
Les interfaces retournées dans xpsPrintJob, documentStream et printTicketStream ne doivent pas être utilisées tant que StartXpsPrintJob n’a pas été retourné avec succès.
Une fois que l’appelant a commencé à envoyer des données, il doit surveiller les événements de progression qui sont signalés à l’événement passé dans progressEvent. Lorsque l’événement est signalé, l’appelant doit appeler IXpsPrintJob ::GetJobStatus pour obtenir le status actuel du travail d’impression.
Lorsque le travail d’impression se termine, qu’il réussisse ou non, l’événement passé dans completionEvent est signalé une fois et une seule fois. Pour éviter la perte de données, l’appelant doit surveiller cet événement et le thread ou l’application de l’appelant ne doit pas être arrêté tant que l’événement n’a pas été signalé.
Les états de travail ne sont ni stockés ni mis en file d’attente par le spouleur d’impression. Étant donné que le traitement du travail n’attend pas que le status soit lu après le signal des événements, l’appelant peut manquer certaines modifications d’état, en fonction du délai entre le moment où l’application a reçu la notification de modification et l’heure à laquelle elle a appelé IXpsPrintJob ::GetJobStatus. Pour recevoir des notifications ultérieures, l’application doit réinitialiser l’événement de progression après avoir reçu la notification.
Si un appel à StartXpsPrintJob échoue, le travail status est mis à jour, les événements d’achèvement et de progression sont signalés et un code d’erreur est retourné. Pour obtenir la status du travail d’impression ayant échoué, appelez IXpsPrintJob ::GetJobStatus.
StartXpsPrintJob appelle DuplicateHandle sur completionEvent et progressEvent pour s’assurer qu’ils restent valides pendant toute la durée de vie du travail. Étant donné que le spouleur d’impression utilise un handle en double pour les événements, il est possible pour l’appelant de fermer ces handles à tout moment sans affecter l’exécution du travail. Toutefois, la procédure recommandée consiste à ce que l’appelant ferme ces handles uniquement après que l’événement completionEvent a été signalé et observé par l’appelant.
Les interfaces IXpsPrintJobStream retournées dans documentStream et printTicketStream sont des flux en écriture seule qui ne permettent pas la recherche, mais qui peuvent être fermés. L’appelant écrit le document XPS et imprime le contenu du ticket dans ces flux, puis appelle Close une fois toutes les données écrites. Les appels à la méthode Write des flux sont thread-safe ; Toutefois, si de tels appels sont effectués à partir de threads différents, il n’est pas garanti qu’ils soient validés dans le flux dans l’ordre attendu.
Configuration requise
| Client minimal pris en charge | Windows 7 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 R2 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | xpsprint.h |
| Bibliothèque | XpsPrint.lib |
| DLL | XpsPrint.dll |