StartXpsPrintJob1, fonction (xpsprint.h)
[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
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 |
|
printerName ou xpsOMPackageTarget a la valeur NULL. |
|
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é.
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 |