StartXpsPrintJob1, fonction (xpsprint.h)

  • Article

[StartXpsPrintJob1 n’est pas pris en charge et peut être modifié ou indisponible à l’avenir. ]

Crée un travail d’impression pour envoyer du contenu de document XPS à une imprimante. Cette fonction crée un chemin d’impression plus efficace que StartXpsPrintJob.

Syntaxe

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
);

Paramètres

[in] printerName

Nom de l’imprimante à laquelle ce travail sera associé.

[in, optional] jobName

Nom de travail spécifié par l’utilisateur à associer à ce travail. Vous pouvez définir ce paramètre sur NULL si le travail ne nécessite pas de nom distinct spécifié par l’utilisateur.

[in, optional] 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, vous devez définir ce paramètre sur NULL.

[in, optional] progressEvent

Un handle d’événement qui est signalé quand l’une des modifications de travail d’impression suivantes se produit :

  • 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
Note Cet événement n’est signalé qu’après que l’application a commencé à envoyer des données au travail d’impression.
 

L’API d’impression XPS ne réinitialise pas cet événement, c’est-à-dire la responsabilité de l’appelant.

Définissez ce paramètre sur NULL si vous ne souhaitez pas être informé de la progression.

[in, optional] 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 StartXpsPrintJob1 . L’API d’impression XPS ne réinitialise pas cet événement, c’est-à-dire la responsabilité de l’appelant.

Définissez ce paramètre sur NULL si vous ne souhaitez pas être informé de l’achèvement.

[out, optional] xpsPrintJob

Pointeur vers l’interface IXpsPrintJob qui représente le travail d’impression créé par StartXpsPrintJob1 . Pour obtenir le status du travail d’impression ou l’annuler, utilisez l’interface IXpsPrintJob. Définissez ce paramètre sur NULL si vous n’en avez pas besoin.

[out] printContentReceiver

Pointeur vers l’interface IXpsOMPackageTarget créée par cette fonction. Ce paramètre est obligatoire et vous ne pouvez pas le définir sur NULL.

Pour envoyer du contenu de document au travail d’impression créé par cette fonction, utilisez l’interface IXpsOMPackageWriter que vous créez en appelant la méthode CreateXpsOMPackageWriter de l’interface IXpsOMPackageTarget retournée dans xpsOMPackageTarget.

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
 S_OK
E_POINTER
 printerName ou xpsOMPackageTarget a la valeur NULL.
E_OUTOFMEMORY
 Mémoire insuffisante pour créer un objet IXpsPrintJob .

Remarques

StartXpsPrintJob1 est une fonction asynchrone. Par conséquent, elle peut être retournée avant que le spouleur d’impression crée ou démarre un travail d’impression.

N’utilisez pas les interfaces retournées dans xpsPrintJob et xpsOMPackageTarget tant que StartXpsPrintJob1 n’a pas été retourné avec succès.

Une fois que l’appelant a commencé à envoyer des données, il est recommandé de surveiller les événements de progression 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.

Une fois le travail d’impression terminé, qu’il soit réussi ou non, l’événement passé dans completionEvent n’est signalé qu’une seule fois. Pour éviter la perte de données, il est recommandé à l’appelant de surveiller l’événement d’achèvement et de s’assurer que ni le thread ni l’application qui a créé le travail d’impression ne sont arrêtés tant que l’événement d’achèvement 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 la signalisation 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 le moment où elle a appelé IXpsPrintJob ::GetJobStatus. Pour recevoir les notifications suivantes, l’application doit réinitialiser l’événement de progression après avoir reçu la notification.

Si un appel à StartXpsPrintJob1 échoue, le spouleur d’impression met à jour le status de travail, signale les événements d’achèvement et de progression, et retourne un code d’erreur. Pour obtenir le status du travail d’impression ayant échoué, appelez IXpsPrintJob ::GetJobStatus.

StartXpsPrintJob1 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, l’appelant peut fermer ces handles à tout moment sans affecter l’exécution du travail. Toutefois, nous recommandons à l’appelant de fermer ces handles uniquement une fois que l’événement completionEvent a été signalé et que l’appelant l’a observé.

Note Lorsque votre application imprime dans un fichier, l’application est chargée de fournir la valeur à transmettre au paramètre outputFileName pour les opérations d’impression à fichier. Pour imprimer sur une imprimante qui utilise un pilote qui sort vers le port FILE :, l’appelant doit récupérer le nom de fichier de l’utilisateur en affichant la boîte de dialogue fichier commun.
 

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 7 avec SP1, Windows Vista et supplément de mise à jour de la plateforme pour Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 R2 avec SP1, Windows Server 2008 et supplément de mise à jour de plateforme pour Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête xpsprint.h
Bibliothèque XpsPrint.lib
DLL XpsPrint.dll

Voir aussi

Documents

IXpsOMPackageTarget

IXpsOMPackageWriter

XML Paper Specification