SetPrinterDataEx, fonction

La fonction SetPrinterDataEx définit les données de configuration d’une imprimante ou d’un serveur d’impression. La fonction stocke les données de configuration sous la clé de Registre de l’imprimante.

Syntaxe

DWORD SetPrinterDataEx(
  _In_ HANDLE  hPrinter,
  _In_ LPCTSTR pKeyName,
  _In_ LPCTSTR 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.

pKeyName [in]

Pointeur vers une chaîne terminée par null qui spécifie la clé contenant la valeur à définir. Si la ou les sous-clés spécifiées n’existent pas, la fonction les crée.

Pour stocker les données de configuration qui peuvent être publiées dans le service d’annuaire (DS), spécifiez l’une des clés de Registre prédéfinies suivantes.

Valeur Signification
SPLDS_DRIVER_KEY
Les pilotes d’imprimante utilisent cette clé pour stocker les propriétés du pilote.
SPLDS_SPOOLER_KEY
Réservé. Utilisé uniquement par le spouleur d’impression pour stocker les propriétés internes du spouleur.
SPLDS_USER_KEY
Les applications utilisent cette clé pour stocker les propriétés de l’imprimante, telles que les numéros de ressources d’imprimante.

Les valeurs stockées sous la clé SPLDS_USER_KEY sont publiées dans le service d’annuaire uniquement si le schéma contient une propriété correspondante. Un administrateur de domaine doit créer la propriété si elle n’existe pas déjà. Pour publier une propriété définie par l’utilisateur après avoir utilisé SetPrinterDataEx pour ajouter ou modifier une valeur, appelez SetPrinter avec Level = 7 et avec le membre dwAction de PRINTER_INFO_7 défini sur DSPRINT_UPDATE.

Vous pouvez spécifier d’autres clés pour stocker des données de configuration non-DS. Utilisez la barre oblique inverse ( \ ) comme délimiteur pour spécifier un chemin qui a une ou plusieurs sous-clés.

Si hPrinter est un handle pour une imprimante et que pKeyName a la valeur NULL ou une chaîne vide, SetPrinterDataEx retourne ERROR_INVALID_PARAMETER.

Si hPrinter est un handle pour un serveur d’impression, pKeyName est ignoré.

N’utilisez pas SPLDS_SPOOLER_KEY. Pour modifier les propriétés de l’imprimante du spouleur, utilisez SetPrinter avec Level = 2.

pValueName [in]

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

Pour les imprimantes, cette chaîne spécifie le nom d’une valeur sous la clé pKeyName .

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

Type [in]

Code indiquant 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 du Registre.

Si pKeyName spécifie l’une des clés de service d’annuaire prédéfinies, Type doit être REG_SZ, REG_MULTI_SZ, REG_DWORD ou REG_BINARY. Si REG_BINARY est utilisé, cbData doit être égal à 1 et le service d’annuaire traite les données comme une valeur booléenne.

pData [in]

Pointeur vers une mémoire tampon 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

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 ou un spouleur d’impression, appelez la fonction GetPrinterDataEx .

Appeler SetPrinterDataEx avec le paramètre pKeyName défini sur « PrinterDriverData » équivaut à appeler la fonction SetPrinterData .

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

Le passage de l’une des valeurs prédéfinies suivantes en tant que pValueName définit 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, à laquelle un travail est redémarré sur un autre port après qu’une erreur s’est produite. 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. La durée réelle peut être plus longue, en fonction des paramètres de moniteur 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 du 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, auquel le moniteur de port met à jour le spouleur avec le port status.

Pour s’assurer que le spouleur redirige les travaux vers l’imprimante disponible suivante dans le pool (lorsque le travail d’impression n’est pas imprimé dans le délai défini), le moniteur de port doit prendre en charge SNMP et les ports réseau du pool doivent être configurés comme « SNMP status activé ». Le moniteur de port qui prend en charge SNMP est le moniteur de port TCP/IP standard.

Dans Windows 7 et versions ultérieures de Windows, les travaux d’impression envoyés à un serveur d’impression sont affichés sur le client par défaut. Vous pouvez configurer le rendu côté client des travaux d’impression en définissant pKeyName sur « PrinterDriverData » et pValueName sur la valeur de paramètre dans le tableau suivant.

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 affiché sur le client, il le sera sur le serveur. Si un travail d’impression ne peut pas être affiché sur le serveur, il échoue.
La valeur 1 affiche les travaux d’impression sur le client. Si un travail d’impression ne peut pas être affiché 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
SetPrinterDataExW (Unicode) et SetPrinterDataExA (ANSI)

Voir aussi

Impression

Fonctions API du spouleur d’impression

GetPrinterDataEx

OpenPrinter

SetPrinter

PRINTER_INFO_7