GetPrinter, fonction

Article
06/12/2023

La fonction GetPrinter récupère des informations sur une imprimante spécifiée.

Syntaxe

BOOL GetPrinter(
  _In_  HANDLE  hPrinter,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinter,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded
);

Paramètres

hPrinter [in]

Handle de l’imprimante pour laquelle la fonction récupère des informations. Utilisez la fonction OpenPrinter ou AddPrinter pour récupérer un handle d’imprimante.

Niveau [in]

Niveau ou type de structure que la fonction stocke dans la mémoire tampon pointée par pPrinter.

Cette valeur peut être 1, 2, 3, 4, 5, 6, 7, 8 ou 9.

pPrinter [out]

Pointeur vers une mémoire tampon qui reçoit une structure contenant des informations sur l’imprimante spécifiée. La mémoire tampon doit être suffisamment grande pour recevoir la structure et toutes les chaînes ou autres données vers lesquelles pointent les membres de la structure. Si la mémoire tampon est trop petite, le paramètre pcbNeeded retourne la taille de mémoire tampon requise.

Le type de structure est déterminé par la valeur de Level.

Level	Structure
1	Structure PRINTER_INFO_1 contenant des informations générales sur l’imprimante.
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	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	Structure PRINTER_INFO_5 contenant des informations sur l’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 qui indique si l’imprimante est publiée dans le service d’annuaire.
8	Structure PRINTER_INFO_8 spécifiant les paramètres globaux par défaut de l’imprimante.
9	Structure PRINTER_INFO_9 spécifiant les paramètres d’imprimante par défaut par utilisateur.

cbBuf [in]

Taille, en octets, de la mémoire tampon pointée par pPrinter.

pcbNeeded [out]

Pointeur vers une variable que la fonction définit sur la taille, en octets, des informations d’imprimante. Si cbBuf est inférieur à cette valeur, GetPrinter échoue et la valeur représente la taille de mémoire tampon requise. Si cbBuf est égal ou supérieur à cette valeur, GetPrinter réussit et la valeur représente le nombre d’octets stockés dans la mémoire tampon.

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.

Le membre pDevMode dans les structures PRINTER_INFO_2, PRINTER_INFO_8 et PRINTER_INFO_9 peut être NULL. Dans ce cas, l’imprimante est inutilisable tant que le pilote n’a pas été réinstallé.

Pour les structures PRINTER_INFO_2 et PRINTER_INFO_3 qui contiennent un pointeur vers un descripteur de sécurité, la fonction récupère uniquement les composants du descripteur de sécurité que l’appelant est autorisé à lire. Pour récupérer 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 pour récupérer un handle sur l’imprimante. Le tableau suivant présente les droits d’accès requis pour lire les différents composants du descripteur de sécurité.

Droit d'accès	Composant de descripteur de sécurité
READ_CONTROL	Propriétaire Groupe principal Liste de contrôle d’accès discrétionnaire (DACL)
ACCESS_SYSTEM_SECURITY	Liste de contrôle d’accès système (SACL)

Si vous spécifiez le niveau 7, le membre dwAction de PRINTER_INFO_7 retourne l’une des valeurs suivantes pour indiquer si l’imprimante est publiée dans le service d’annuaire.

Valeur dwAction	Signification
DSPRINT_PUBLISH	L’imprimante est publiée. Le membre pszObjectGUID contient le GUID de l’objet file d’attente d’impression des services d’annuaire associé à l’imprimante.
DSPRINT_UNPUBLISH	L’imprimante n’est pas publiée.
DSPRINT_PENDING	Indique que le système tente d’effectuer une opération de publication ou d’annulation de publication. Si un appel SetPrinter ne parvient pas à publier ou à annuler la publication d’une imprimante, le système tente d’effectuer l’opération en arrière-plan.

À compter de Windows Vista, les données d’imprimante retournées par GetPrinter sont récupérées à partir d’un cache local lorsque hPrinter fait référence à une imprimante hébergée par un serveur d’impression et qu’il existe au moins une connexion ouverte au serveur d’impression. Dans toutes les autres configurations, les données de l’imprimante sont interrogées à partir du serveur d’impression.

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	GetPrinterW (Unicode) et GetPrinterA (ANSI)

Voir aussi

Impression
Fonctions API du spouleur d’impression
AbortPrinter
Addprinter
ClosePrinter
DeletePrinter
EnumPrinters
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_3
PRINTER_INFO_4
PRINTER_INFO_5
PRINTER_INFO_7
PRINTER_INFO_8
PRINTER_INFO_9
OpenPrinter
SetPrinter

Partager via