Fonction SetPrinterData

Article
06/13/2023

La fonction SetPrinterData définit les données de configuration d’une imprimante ou d’un serveur d’impression.

Pour spécifier la clé de Registre sous laquelle stocker les données, appelez la fonction SetPrinterDataEx . Appeler SetPrinterData revient à appeler la fonction SetPrinterDataEx avec le paramètre pKeyName défini sur « PrinterDriverData ».

Syntaxe

DWORD SetPrinterData(
  _In_ HANDLE hPrinter,
  _In_ LPTSTR pValueName,
  _In_ DWORD  Type,
  _In_ LPBYTE pData,
  _In_ DWORD  cbData
);

Paramètres

hPrinter [in]

Handle de l’imprimante ou du serveur d’impression pour lequel la fonction définit les données de configuration. Utilisez la fonction OpenPrinter, OpenPrinter2 ou AddPrinter pour récupérer un handle d’imprimante.

pValueName [in]

Pointeur vers une chaîne terminée par null qui identifie les données à définir.

Pour les imprimantes, cette chaîne est le nom d’une valeur de Registre sous la clé « PrinterDriverData » de l’imprimante dans le Registre.

Pour les serveurs d’impression, cette chaîne est l’une des chaînes prédéfinies répertoriées dans la section Remarques suivante.

Type [in]

Code qui indique le type de données vers lequel pointe le paramètre pData . Pour obtenir la liste des codes de type possibles, consultez Types de valeurs de registre.

pData [in]

Pointeur vers un tableau d’octets qui contient les données de configuration de l’imprimante.

cbData [in]

Taille, en octets, du tableau.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est une valeur d’erreur.

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.

Pour récupérer des données de configuration existantes pour une imprimante, appelez la fonction GetPrinterDataEx ou GetPrinterData .

Si hPrinter est un handle pour un serveur d’impression, pValueName peut spécifier l’une des valeurs prédéfinies suivantes.

Valeur	Commentaires
SPLREG_ALLOW_USER_MANAGEFORMS	Windows XP avec Service Pack 2 (SP2) et versions ultérieures Windows Server 2003 avec Service Pack 1 (SP1) et versions ultérieures
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP	Non pris en charge dans Windows Server 2003 et versions ultérieures
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS	Windows 7 et ultérieur
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE	Windows 7 et ultérieur
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE	Windows 7 et ultérieur
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT	Windows 7 et ultérieur
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY	Windows 7 et ultérieur
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY	Windows 7 et ultérieur
SPLREG_RETRY_POPUP	En cas de retour réussi, pData contient 1 si le serveur est configuré pour réessayer des fenêtres contextuelles pour tous les travaux, ou 0 si le serveur ne tente pas de nouvelles fenêtres contextuelles pour tous les travaux. Non pris en charge dans Windows Server 2003 et versions ultérieures
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT	Windows Server 2003 et versions ultérieures

Les valeurs suivantes de pValueName déterminent le comportement d’impression du pool lorsqu’une erreur se produit.

Valeur	Commentaires
SPLREG_RESTART_JOB_ON_POOL_ERROR	La valeur de pData indique l’heure, en secondes, où un travail est redémarré sur un autre port après qu’une erreur se produit. Ce paramètre est utilisé avec SPLREG_RESTART_JOB_ON_POOL_ENABLED.
SPLREG_RESTART_JOB_ON_POOL_ENABLED	Une valeur différente de zéro dans pData indique que SPLREG_RESTART_JOB_ON_POOL_ERROR est activé.

L’heure spécifiée dans SPLREG_RESTART_JOB_ON_POOL_ERROR est une durée minimale. Le temps réel peut être plus long, en fonction des paramètres de surveillance de port suivants, qui sont des valeurs de Registre sous cette clé de Registre :

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports

Appelez la fonction RegSetValueEx pour définir ces valeurs.

Paramètre de moniteur de port	Type de données	Signification
StatusUpdateEnabled	REG_DWORD	Si une valeur différente de zéro, permet au moniteur de port de mettre à jour le spouleur avec le port status.
StatusUpdateInterval	REG_DWORD	Spécifie l’intervalle, en minutes, lorsque le moniteur de port met à jour le spouleur avec le port status.

Dans Windows 7 et les versions ultérieures de Windows, les travaux d’impression envoyés à un serveur d’impression sont affichés sur le client par défaut. Le rendu côté client d’un travail d’impression peut être configuré pour chaque imprimante en définissant les valeurs suivantes dans pValueName.

Paramètre	Type de données	Description
EMFDespoolingSetting	REG_DWORD	La valeur 0, ou si cette valeur n’est pas présente dans le Registre, active le rendu côté client par défaut des travaux d’impression. La valeur 1 désactive le rendu côté client des travaux d’impression.
ForceClientSideRendering	REG_DWORD	La valeur 0, ou si cette valeur n’est pas présente dans le Registre, entraîne le rendu des travaux d’impression sur le client. Si un travail d’impression ne peut pas être rendu sur le client, il sera rendu sur le serveur. Si une tâche d’impression ne peut pas être affichée sur le serveur, elle échoue. La valeur 1 affiche les travaux d’impression sur le client. Si un travail d’impression ne peut pas être rendu sur le client, il échoue.

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	SetPrinterDataW (Unicode) et SetPrinterDataA (ANSI)

Voir aussi

Impression
Fonctions API du spouleur d’impression
GetPrinter
GetPrinterData
GetPrinterDataEx
OpenPrinter
SetPrinterDataEx

Partager via