SetJob, fonction

Article
06/12/2023

La fonction SetJob met en pause, reprend, annule ou redémarre un travail d’impression sur une imprimante spécifiée. Vous pouvez également utiliser la fonction SetJob pour définir des paramètres de travail d’impression, tels que la priorité du travail d’impression et le nom du document.

Vous pouvez utiliser la fonction SetJob pour attribuer une commande à un travail d’impression, définir des paramètres de travail d’impression ou effectuer les deux dans le même appel. La valeur du paramètre Command n’affecte pas la façon dont la fonction utilise les paramètres Level et pJob . En outre, vous pouvez utiliser SetJob avec JOB_INFO_3 pour lier un ensemble de travaux d’impression. Pour plus d'informations, consultez la section Notes.

Syntaxe

BOOL SetJob(
  _In_ HANDLE hPrinter,
  _In_ DWORD  JobId,
  _In_ DWORD  Level,
  _In_ LPBYTE pJob,
  _In_ DWORD  Command
);

Paramètres

hPrinter [in]

Handle pour l’objet d’imprimante qui vous intéresse. Utilisez la fonction OpenPrinter, OpenPrinter2 ou AddPrinter pour récupérer un handle d’imprimante.

JobId [in]

Identificateur qui spécifie le travail d’impression. Vous obtenez un identificateur de travail d’impression en appelant la fonction AddJob ou la fonction StartDoc .

Si le paramètre Level est défini sur 3, le paramètre JobId doit correspondre au membre JobId de la structure JOB_INFO_3 pointée par pJob

Niveau [in]

Type de structure d’informations de travail pointée vers le paramètre pJob .

Toutes les versions de Windows : vous pouvez définir le paramètre Level sur 0, 1 ou 2. Lorsque vous définissez Level sur 0, pJob doit avoir la valeur NULL. Utilisez ces valeurs lorsque vous ne définissez aucun paramètre de travail d’impression.

Vous pouvez également définir le paramètre Level sur 3.

À compter de Windows Vista : vous pouvez également définir le paramètre Level sur 4.

pJob [in]

Pointeur vers une structure qui définit les paramètres du travail d’impression.

Toutes les versions de Windows : pJob peut pointer vers une structure JOB_INFO_1 ou JOB_INFO_2 .

pJob peut également pointer vers une structure JOB_INFO_3 . Vous devez disposer JOB_ACCESS_ADMINISTER autorisation d’accès pour les travaux spécifiés par les membres JobId et NextJobId de la structure JOB_INFO_3 .

À compter de Windows Vista : pJob peut également pointer vers une structure JOB_INFO_4 .

Si le paramètre Level est 0, pJob doit avoir la valeur NULL.

Commande [in]

Opération de travail d’impression à effectuer. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
JOB_CONTROL_CANCEL	Ne pas utiliser. Pour supprimer un travail d’impression, utilisez JOB_CONTROL_DELETE.
JOB_CONTROL_PAUSE	Suspendez le travail d’impression.
JOB_CONTROL_RESTART	Redémarrez le travail d’impression. Un travail ne peut être redémarré que s’il était en cours d’impression.
JOB_CONTROL_RESUME	Reprendre un travail d’impression suspendu.
JOB_CONTROL_DELETE	Supprimez le travail d’impression.
JOB_CONTROL_SENT_TO_PRINTER	Utilisé par les moniteurs de port pour mettre fin au travail d’impression.
JOB_CONTROL_LAST_PAGE_EJECTED	Utilisé par les moniteurs de langue pour mettre fin au travail d’impression.
JOB_CONTROL_RETAIN	Windows Vista et versions ultérieures : conservez le travail dans la file d’attente après son impression.
JOB_CONTROL_RELEASE	Windows Vista et versions ultérieures : relâchez le travail d’impression.

Vous pouvez utiliser le même appel à la fonction SetJob pour définir des paramètres de travail d’impression et pour donner une commande à un travail d’impression. Par conséquent, Command n’a pas besoin d’être 0 si vous définissez des paramètres de travail d’impression, bien qu’il puisse l’être.

Valeur retournée

Si la fonction réussit, la valeur de retour est une valeur différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro.

Notes

Il s’agit d’une fonction bloquante ou synchrone qui peut ne pas être retournée immédiatement. La rapidité avec laquelle cette fonction retourne dépend de facteurs d’exécution tels que l’status réseau, la configuration du serveur d’impression et les facteurs d’implémentation du pilote d’imprimante qui sont difficiles à prédire lors de l’écriture d’une application. L’appel de cette fonction à partir d’un thread qui gère l’interaction avec l’interface utilisateur peut donner l’impression que l’application ne répond pas.

Vous pouvez utiliser la fonction SetJob pour définir différents paramètres de travail d’impression en fournissant un pointeur vers une structure JOB_INFO_1, JOB_INFO_2, JOB_INFO_3 ou JOB_INFO_4 qui contient les données nécessaires.

Pour supprimer ou supprimer tous les travaux d’impression d’une imprimante particulière, appelez la fonction SetPrinter avec son paramètre Command défini sur PRINTER_CONTROL_PURGE.

Les membres suivants d’une structure JOB_INFO_1, JOB_INFO_2 ou JOB_INFO_4 sont ignorés lors d’un appel à SetJob : JobId, pPrinterName, pMachineName, pUserName, pDrivername, Size, Submitted, Time et TotalPages.

Vous devez disposer PRINTER_ACCESS_ADMINISTER autorisation d’accès pour une imprimante afin de modifier la position d’un travail d’impression dans la file d’attente d’impression.

Si vous ne souhaitez pas définir la position d’un travail d’impression dans la file d’attente d’impression, vous devez définir le membre Position de la structure JOB_INFO_1, JOB_INFO_2 ou JOB_INFO_4 sur JOB_POSITION_UNSPECIFIED.

Utilisez la fonction SetJob avec la structure JOB_INFO_3 pour lier un ensemble de travaux d’impression (également appelé chaîne). Cela est utile dans les situations où un seul document se compose de plusieurs parties que vous souhaitez afficher séparément. Pour imprimer les travaux A, B, C et D dans l’ordre, appelez SetJob avec JOB_INFO_4 pour lier A à B, B à C et C à D.

Si vous liez des travaux d’impression, notez les points suivants :

Des travaux peuvent être ajoutés au début ou à la fin d’une chaîne.
Tous les travaux de la chaîne doivent avoir le même type de données.
La chaîne doit être entièrement liée avant le début du spouleur. Sinon, le spouleur peut imprimer et supprimer les travaux mis en pool avant de les lier tous. Il existe deux façons d’empêcher la chaîne d’imprimer prématurément :
- Suspendez le premier travail de la chaîne jusqu’à ce que la chaîne soit entièrement liée. L’état suspendu du premier travail régit l’état de tous les travaux de la chaîne.
- Laissez le premier travail incomplet, c’est-à-dire n’appelez pas EndDoc ou ScheduleJob pour le premier travail. Toutefois, si l’option « imprimer pendant la mise en file d’attente » est activée (valeur par défaut), cette méthode bloque le port pendant la création de la chaîne, ce qui empêche également l’impression de travaux non liés.
L’application doit gérer le cas où l’utilisateur supprime un travail dans la chaîne avant la fin de l’impression de la chaîne. GetLastError retourne INVALID_PARAMETER lorsqu’aucun JobID n’existe.

Spécifications

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	WinSpool.h (inclure Windows.h)
Bibliothèque	WinSpool.lib
DLL	WinSpool.drv
Noms Unicode et ANSI	SetJobW (Unicode) et SetJobA (ANSI)

Voir aussi

Impression
Fonctions API du spouleur d’impression
AddJob
GetJob
OpenPrinter
SetPrinter
JOB_INFO_1
JOB_INFO_2
JOB_INFO_3
JOB_INFO_4