Fonction SetPrinter
La fonction SetPrinter définit les données d’une imprimante spécifiée ou définit l’état de l’imprimante spécifiée en suspendant l’impression, en reprenant l’impression ou en supprimant tous les travaux d’impression.
Syntaxe
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Paramètres
-
hPrinter [in]
-
Handle de l’imprimante. Utilisez la fonction OpenPrinter, OpenPrinter2 ou AddPrinter pour récupérer un handle d’imprimante.
-
Niveau [in]
-
Type de données que la fonction stocke dans la mémoire tampon pointée par pPrinter. Si le paramètre Command n’est pas égal à zéro, le paramètre Level doit être égal à zéro.
Cette valeur peut être 0, 2, 3, 4, 5, 6, 7, 8 ou 9.
-
pPrinter [in]
-
Pointeur vers une mémoire tampon contenant des données à définir pour l’imprimante ou contenant des informations pour la commande spécifiée par le paramètre Command . Le type de données dans la mémoire tampon est déterminé par la valeur de Level.
Level Structure - 0
Si le paramètre Command est PRINTER_CONTROL_SET_STATUS, pPrinter doit contenir une valeur DWORD qui spécifie la nouvelle status d’imprimante à définir. Pour obtenir la liste des valeurs status possibles, consultez le membre Status de la structure PRINTER_INFO_2. Notez que les PRINTER_STATUS_PAUSED et les PRINTER_STATUS_PENDING_DELETION ne sont pas des valeurs status valides à définir.
Si Level a la valeur 0, mais que le paramètre Command n’est pas PRINTER_CONTROL_SET_STATUS, pPrinter doit avoir la valeur NULL.- 2
Structure PRINTER_INFO_2 contenant des informations détaillées sur l’imprimante. - 3
Structure PRINTER_INFO_3 contenant les informations de sécurité de l’imprimante. - 4
Une structure PRINTER_INFO_4 contenant des informations minimales sur l’imprimante, notamment le nom de l’imprimante, le nom du serveur et si l’imprimante est distante ou locale. - 5
Une structure PRINTER_INFO_5 contenant des informations d’imprimante telles que les attributs de l’imprimante et les paramètres de délai d’attente. - 6
Structure PRINTER_INFO_6 spécifiant la valeur status d’une imprimante. - 7
Structure PRINTER_INFO_7 . Le membre dwAction de cette structure indique si SetPrinter doit publier, annuler, republier ou mettre à jour les données de l’imprimante dans le service d’annuaire. - 8
Structure PRINTER_INFO_8 spécifiant les paramètres d’imprimante par défaut globaux. - 9
Structure PRINTER_INFO_9 spécifiant les paramètres d’imprimante par défaut par utilisateur. -
Commande [in]
-
l’action à effectuer.
Si le paramètre Level est différent de zéro, définissez la valeur de ce paramètre sur zéro. Dans ce cas, l’imprimante conserve son état actuel et la fonction reconfigure les données d’imprimante comme spécifié par les paramètres Level et pPrinter .
Si le paramètre Level est égal à zéro, définissez la valeur de ce paramètre sur l’une des valeurs suivantes.
Valeur Signification - PRINTER_CONTROL_PAUSE
Suspendre l’imprimante. - PRINTER_CONTROL_PURGE
Supprimez tous les travaux d’impression dans l’imprimante. - PRINTER_CONTROL_RESUME
Reprendre une imprimante en pause. - PRINTER_CONTROL_SET_STATUS
Définissez le status de l’imprimante.
Définissez le paramètre pPrinter sur un pointeur vers une valeur DWORD qui spécifie la nouvelle status d’imprimante.
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.
Si Level a la valeur 7 et que l’action de publication a échoué, SetPrinter retourne ERROR_IO_PENDING et tente d’effectuer l’action en arrière-plan. Si Level a la valeur 7 et que l’action de mise à jour a échoué, SetPrinter retourne ERROR_FILE_NOT_FOUND.
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.
Vous ne pouvez pas utiliser SetPrinter pour modifier l’imprimante par défaut.
Pour modifier les paramètres d’imprimante actuels, appelez la fonction GetPrinter pour récupérer les paramètres actuels dans une structure de PRINTER_INFO_2 , modifiez les membres de cette structure si nécessaire, puis appelez SetPrinter.
La fonction SetPrinter ignore les membres pServerName, AveragePPM, Status et cJobs d’une structure PRINTER_INFO_2 .
La suspension d’une imprimante interrompt la planification de tous les travaux d’impression pour cette imprimante, à l’exception de la seule tâche d’impression en cours d’impression. Les travaux d’impression peuvent être envoyés à une imprimante en pause, mais aucune tâche n’est planifiée pour imprimer sur cette imprimante tant que l’impression n’est pas reprise. Si une imprimante est effacée, tous les travaux d’impression de cette imprimante sont supprimés, à l’exception de la tâche d’impression en cours.
Si vous utilisez SetPrinter pour modifier la structure DEVMODE par défaut d’une imprimante (définition globale des valeurs par défaut de l’imprimante), vous devez d’abord appeler la fonction DocumentProperties pour valider la structure DEVMODE .
Pour les structures PRINTER_INFO_2 et PRINTER_INFO_3 qui contiennent un pointeur vers un descripteur de sécurité, la fonction peut définir uniquement les composants du descripteur de sécurité que l’appelant est autorisé à modifier. Pour définir des composants de descripteur de sécurité particuliers, vous devez spécifier les droits d’accès nécessaires lorsque vous appelez la fonction OpenPrinter ou OpenPrinter2 pour récupérer un handle sur l’imprimante. Le tableau suivant montre les droits d’accès nécessaires pour modifier les différents composants de descripteur de sécurité.
| Autorisation d’accès | Composant de descripteur de sécurité |
|---|---|
| WRITE_OWNER | Propriétaire Groupe principal |
| WRITE_DAC | Liste de contrôle d’accès discrétionnaire (DACL) |
| ACCESS_SYSTEM_SECURITY | Liste de contrôle d’accès système (SACL) |
Si le descripteur de sécurité contient un composant que l’appelant n’a pas le droit d’accès à modifier, SetPrinter échoue. Les composants d’un descripteur de sécurité que vous ne souhaitez pas modifier doivent être NULL ou ne pas être présents, le cas échéant. Si vous ne souhaitez pas modifier le descripteur de sécurité et que vous appelez SetPrinter avec une structure PRINTER_INFO_2 , définissez le membre pSecurityDescriptor de cette structure sur NULL.
Le pare-feu de connexion Internet (ICF) bloque les ports d’imprimante par défaut, mais une exception pour le partage de fichiers et d’impression peut être activée. Si SetPrinter est appelé par un administrateur de machine, il active l’exception. S’il est appelé par un non-administrateur et que l’exception n’a pas déjà été activée, l’appel échoue.
Vous pouvez utiliser le niveau 7 avec la structure PRINTER_INFO_7 pour publier, annuler ou mettre à jour les données du service d’annuaire pour l’imprimante. Les données du service d’annuaire d’une imprimante incluent toutes les données stockées sous les clés SPLDS_* par les appels à la fonction SetPrinterDataEx pour l’imprimante. Avant d’appeler SetPrinter, définissez le membre pszObjectGUID de PRINTER_INFO_7 sur NULL et définissez le membre dwAction sur l’une des valeurs suivantes.
| Valeur | Description |
|---|---|
|
DSPRINT_PUBLISH |
Publie les données du service d’annuaire. |
|
DSPRINT_REPUBLISH |
Les données du service d’annuaire pour l’imprimante ne sont pas publiées, puis publiées à nouveau, ce qui actualise toutes les propriétés de l’imprimante publiée. La rééditation modifie également le GUID de l’imprimante publiée. Utilisez cette valeur si vous pensez que les données publiées de l’imprimante ont été endommagées. |
|
DSPRINT_UNPUBLISH |
Annule la publication des données du service d’annuaire. |
|
DSPRINT_UPDATE |
Mises à jour les données du service d’annuaire. Cela est identique à DSPRINT_PUBLISH, sauf que SetPrinter échoue avec ERROR_FILE_NOT_FOUND si l’imprimante n’est pas déjà publiée. Utilisez DSPRINT_UPDATE pour mettre à jour les propriétés publiées, mais pas pour forcer la publication. Les pilotes d’imprimante doivent toujours utiliser DSPRINT_UPDATE plutôt que DSPRINT_PUBLISH. |
DSPRINT_PENDING n’est pas une valeur dwAction valide pour SetPrinter.
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 |
|
| Bibliothèque |
|
| DLL |
|
| Noms Unicode et ANSI |
SetPrinterW (Unicode) et SetPrinterA (ANSI) |